Skip to main content

Other integrations

Okta SAML2 + SCIM

Introduction

Connect Flexopus with Okta via SAML2 for Single Sign On. With the integration, you can manage which Okta user should have access to Flexopus and force them to use their Okta credentials for the login. Based on a SAML2 Setting in Flexopus you can let the user profiles be created after the first successful SAML2 SSO login attempt to avoid a manual user creation process at Flexopus.

💡
Note: Visit the official Okta website for more information.

Setup Instruction Manual

Follow the step by step introduction manual to configure the integration. The manual also includes best practices and solution for some commonly made errors during the configuration. Still, if you need help with the setup, feel free to reach out to our support team via support@flexopus.com.


STEP 1 - Create custom SAML app

Open the Okta admin console and go to the Applications > Applications tab and click the Create App Integration Button.

Create app integration

A popup will open. Select the SAML2.0 option and click on Next

SAML 2.0

App name: Flexopus SAML2
Logo:

App visibility: Leave the unselected.

Click Next

General configuration

On this page, you need to enter the Single sign on URL, Audience URL (SP Entity ID) and the Default RelayState. These configuration parameters can be found within Flexopus. Navigate in Flexopus as an administrator to Dashbaord > Settings > Authentication. Click in the Add provider button and select the SAML2 SSO option.

Create SAML2 SSO Provider

Copy the URLs from Flexopus to your Okta configuration:
Entity ID = Audience URL (SP Entity ID)
Callback (ACS) URL = Single sign on URL
Relay state = Default RelayState
Name ID format = PRESISTENT
Application username = Okta username

Click Continue and first go back to Flexopus to finish the configurations there.

Configure URLs

No need to change the Advanced Settings, still here is a screenshot about the default settings:

Advanced Settings
💡
Note: Start URL is the default relay state at Google. We must set this value in order to be able to convert the IdP initiated login to an SP initiated login. This setting enables the login when the user clicks on the application from Google. (Select app at the top right)
💡
Note: You can configure multiple Single Sign On providers at the same time. In most of the cases there is only one Identity Provider (IdP), however in an organization with multiple companies may have multiple IdPs. For this reason, there is a prefix in the URL to differentiate between the SAML2 URLs per IdP.

Select: I'm an Okta customer adding an internal app
Select: It's required to contact the vendor to enable SAML
You can optionally give some information to Okta about Flexopus:
(optional) First Field: https://www.flexopus.com
(optional) Second Field: https://help.flexopus.com/de/integration-okta-sso
(optional) Third Field: no tips and additional comments.
Click on Finish at the end.

Okta survey

STEP 2 - Attribute mapping

Click on the View SAML setup instructions

SAML setup instructions

Configure the correct attribute mappings. Set the attributes as listed below.

Name Name format Value Note
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname URl Reference user.firstname required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress URl Reference user.email required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn URl Reference user.login required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname URl Reference user.lastName required
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name URl Reference user.displayName required
department Basic user.department optional
jobtitle Basic user.title optional
Attribute mapping

To finish the configuration, we need to share the metadata with Flexopus. Since Okta provides neither a direct metadata URL nor a Metadata File, you need to create the Metadata file for yourself like this:
Copy the content of the optional field in the bottom called: Provide the following IDP metadata to your SP provider. Create an empty XML file locally on your PC and copy the content into it.

Create metadata file

STEP 3 - Configure Flexopus

In Flexopus navigate to Dashboard > Settings > Authentication and select the created SAML2 Provider. Enable the SAML2 SSO and select instead of the metadata URL option the Metadata file option for the configuration. Upload the downloaded Metadata File you created.

Upload Metadata File

Enter the name of the SAML2 Login button, which will be displayed on the login page. Recommendation: SSO Login

(optional) Enable the synchronization of the fields that you configured in the SAML2 settings: jobtitle or department

Fields and button name

In the security settings, set at the allowed domains for SSO a * (star) and press ENTER. By this, you allow every user to log in that is configured in your Active Directory for the login.

By default, the SAML2 SSO user are registered after the first login attempt automatically. This is good for you, since you don't need to create the user profiles manually one by one before the first login, however you can disable this setting (not recommended).

Security settings

SAVE your settings in the bottom.


STEP 4 - Configure who can log in

If you try to log in now into Flexopus, you will see an error message, since you did not configure who can or cannot log in from your Okta user directory. You can set it under the assignments tab. Assign a test user to the application and test the connection at Flexopus.

Access management

Open the settings and decide which user or group can log in into the application. It's recommended enabling the login for the whole organization in case you don't have any reasonable limitations in place. In this case, you don't need to maintain the user's access for the login, and you can reduce the number of possible support cases regarding the login configuration.


SCIM configuration


(optional) SCIM API configuration

💡
IMPORTANT! The custom standard SCIM provisioning at OKTA is not working at the moment as intended. An issue was reported to the OKTA technical support team. Please skip this configuration manual and execute the configuration process as described in the OKTA SCIM WORKAROUND section (scroll down)
Date: 2023-10-30

Optionally, you can also configure a user and group provisioning between Okta and Flexopus.

Follow the instructions to configure SCIM:

Click on Edit at the App Settings

App Settings

Select: Enable SCIM provisioning

Enable SCIM

A new tab appears: Provisioning
Visit the Provisioning tab and click on Edit

Go to your Flexopus Dashboard as an administrator and visit the page Dashboard Settings > Integrations. Here you can see the SCIM connector base URL and you can generate the SCIM API token for the Authorization.

Configuration parameters

SCIM connector base URL: tenant URL
Unique identifier field for users: userName
Select options: Push New Users, Push Profile Updates, Push Groups
Select option: HTTP Header
Authorization: Generate a token in Flexopus.

💡
DO NOT SELECT IMPORT GROUPS!!!

Click on test. Test results looks like this:

Test results

Save the settings.

In the Provisioning tab select the To App menu point and click on Edit.

Enable: Select Create Users
Enable: Update User Attributes
Enable: Deactivate Users
The fourth option is not needed.

Edit syncronization options

Edit the attribute mapping to send only the necessary attributes through SCIM to Flexopus. Only keep the following mappings:

Attribute mapping

The Display Name need to be changed.

Attribute value: Expression

String.len(user.displayName) > 0 ? user.displayName : user.firstName + " " + user.lastName

Select option Create and Update

Edit attribute

Save the settings.

Test the connection by assigning a group to Flexopus. The groups should be synced to Flexopus within a few minutes. 


(optional) OKTA SCIM Workaround

At the current time (2023-10-30), due to a malfunction at Okta, the SCIM interface must be set up in SCIM via a detour. The normal “application” that we used for the SAML2 connection offers the “Provisioning” option, but cannot be used due to a technical error on the part of Okta. The problem has been reported by us to Okta, and we hope that it will change in the future. For the time being, you can use the alternative solution as follows:

💡
IMPROTANT! With Okta, the user groups are synchronized bidirectionally. In other words, you can send groups from Okta to Flexopus, but also from Flexopus to Okta. We don't need the second one, but we can't prevent it either, at least we haven't found a corresponding setting in Okta. For this reason, you should do the following before you configure:

WORKAROUND:

Navigate in Okta to Application > Browse App Catalog --> SCIM 2.0 Test App (Header Auth)

Add application

You can rename the application: Flexopus SCIM App

Rename application

Unfortunately, SAML2 cannot be configured in this application, so you can skip the settings below with the Done button. We have already configured SAML2 with the other application anyway.

Click on Provisioning and start the settings with Configure API Integration

Configure SCIM

Go to your Flexopus Dashboard as an administrator and visit the page Dashboard Settings > Integrations. Here you can find the Base URL and you can generate the API token

Base URL: Tenant URL
API Token: Bearer {api-token} 

💡
Important! You must also insert the "Bearer " part!

Click on Test connection

Configure SCIM base parameters

Enable: Select Create Users
Enable: Update User Attributes
Enable: Deactivate Users
The fourth option is not needed.

Synchronization options

Edit the attribute mapping to send only the necessary attributes through SCIM to Flexopus. Only keep the following mappings:

Attribute mapping

The Display Name need to be changed.

Attribute value: Expression

String.len(user.displayName) > 0 ? user.displayName : user.firstName + " " + user.lastName

Select option Create and Update

Edit attribute

Test the connection by assigning a group to Flexopus. The groups should be synchronized with Flexopus within a few minutes.


Assign groups and test

You can then link the groups to the application, to Assignment and to Push Groups.

Once you assigned a group and started the provisioning, you can expect the following changes in Flexopus. The groups will be provisioned with an external marking to Flexopus, which means that you can not edit the groups locally in Flexopus. You can not change the names, add user or delete user from the group. The single source of truth will be the group structure in your Okta Directory.

💡
Important! Flexopus only supports flat groups. For the nested groups, we only sync the first level. To provision nested groups, we recommend using a linked dynamic groups. Dynamic groups link to nested groups are flattened.
Synchronized groups

You can use the groups for access management within Flexopus similar to the other internal or system groups. 

Best practices using SCIM

The fact that you can synchronize groups from your Okta to Flexopus doesn't mean that you should manage all your groups through SCIM. We recommend syncing only a limited amount of groups, that also has a reason to be synchronized. The Okta directory is usually the playground of the IT department to manage access to applications and services, and not necessary to manage desk assignment on the user level.

Manage and maintain groups in Okta, which potentially can be used for other use cases as well. A group like AllCompanyUsers can be managed in Okta, but a group like DepartmenAWorkstationGroup2 could be managed in Flexopus directly.

Decide who should maintain the group for the desk assignment. Is it the responsibility of the IT department or is it the responsibility of the facility management, the departments, or the HR? The once that suppose to manage the groups shall have access to the group management. In most of the cases, the IT has access to the Okta and the other has no access. We should avoid creating support tickets for each change per group.

Suggestion - One external group

A very simple solution is to synchronize only one group. Let's name this groups AllFlexopusUsers. This group contains the users that suppose to have access to Flexopus.

Once you connected the AllFlexopusUsers groups and start the provisioning, the group itself and all the users within the groups will be synchronized to Flexopus, even if they did not log in into Flexopus yet.

This way we can provision all the users to Flexopus, and the Flexopus administrators can group them locally at Flexopus as they wish. You can grant permission to Flexopus administrators to create and manage other groups in Flexopus. This way, you as IT admin can outsource the management of the groups to the once that are interested in the management of the groups. You have only one group to manage in the AD.

USE CASE - New employee starting (create through provisioning)

In case a new employee will start on the first day of the next month, we will need to allow the new employee to book the right resource from day one. Which means that the employee should have the right groups for reservation before the first login. If we add the user as a part of the onboarding process to the AllFlexopusUsers group, the user profile will be created automatically at Flexopus. After the creation, the local Flexopus administrators can assign the suer profile to the local groups.

USE CASE - Employee leaving (delete through provisioning)
In case an employee is leaving the organization, you usually delete the users profile from your Active Directory or at least remove from the AllFleoxpusUsers group. Through the integration, we receive two requests:

  1. User deleted from group AllFlexopusUsers group
  2. User has no access to application

The second request will deactivate the user in Flexopus user directory and the user can not log in. The SAML2 Single Sign On will not work, and the user is also set to a deactivated status in Flexopus. Lear in the deletion concept how to automatically delete deactivated users:

How can I disable the SCIM Integration?

You can disable the SCIM integration by going to your Okta and turning it off. Then navigate to Flexopus as an administrator Dashboard > Settings > Integrations and click on the Delete token button.

Delete Token

A popup will open asking you to detach the groups. Enable this option. This will make the current external read only groups to an internal group, so that you can edit them later.

Detach external groups

You are done. The SCIM integration is deleted.


Trouble Shooting / FAQ

I got a 500 Error during the login.

In case you get a 500 error, you may misconfigure the URLs or the attributes. Check the settings based on the manual once again. If you can not find the issue, contact us via support@flexopus.com. We have server logs to see where the problem lies.

Can I change the UPN of the users?

As you may know, UPN stand for UNIQUE principal names. Unique attributes shall never change, especially the UPN of the user shall remain the same. It can be a number or anything else. External application are identifying users based on their UPN, if you change you may risk creating a new user within Flexopus. Still, you may have a reason to change the UPN. In this case, contact us via support@flexopus.com. We can assist you by deleting the UPNs and the External IDs of the user to allow you the change of the UPNs in your IdP.

Can I also synchronize the user profile pictures?

Unfortunately, the SAML2 SSO protocol is not supporting the synchronization of profile pictures. We are planning to develop a way via the API to synchronize the user profile pictures.

I saw an attribute costcenters. What is it doing?

Indeed, we have an additional attribute, which is called costcenters. The feature is currently in a BETA testing phase. More information will follow.

Does Flexopus support Identity Provider (IdP) Initiated single sign on login?

Yes and No. We provide a workaround for the IdP initiated logins. You need to configure the initiate-sp-login parameter for the RelayState. This will convert the IdP initiated login request into an SP initiated login. In this way, we can ensure a secure login process.
Reason: A classical IdP initiated login would enable a man in the middle attack for hackers. Through an SP initiated login, we can avoid it. This article explains the reasons in more details: https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso

What are nested groups, and why are you not supporting them?

Nested groups are groups that include other groups, that may include other groups. This could be theoretically an infinite data three. Supporting such a data structure through an automated interface like SCIM is a challenging development task. We are planning to face this development challenge, however we are not there yet.

Can I use SCIM without SAML2?

Yes, you can, but we do not recommend it. It can lead to many complex issues, since SCIM is writing important fields like: email, upn external id. In case you plan using SCIM without SAML2, reach out to us to validate your concept and reasons: support@flexopus.com

Can I generate a new SCIM token?

Yes, you can generate a new token at any time. Navigate to the admin dashboard and create a new token. A popup will ask you if you want to make the current external groups into an internal group.

How can SCIM identify the existing users to avoid double entries?

A user has 4 type of identification fields that are used. The identification priority is: SCIM_ID, EXTERNAL_PROVIDER_ID, UPN, EMAIL. First SCIM check, if the exists with the SCIM_ID, if not than it checks the EXTERNAL_PROVIDER_ID, which is a unique ID is set by the Identity Provider (IdP), in this case by Okta. If the EXTERNAL_PROVIDER_ID does not match with any existing user, then we check for the UPN and then for EMAIL. If none of the fields are matching, then we create a new user. This means that a double user creation is only possible, if the attribute matching is mixed up, or the fields that suppose to be unique are changing for any reason.

 R0087