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.
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.
A popup will open. Select the SAML2.0
option and click on Next
App name: Flexopus SAML2
Logo:
App visibility: Leave the unselected.
Click Next
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.
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.
No need to change the Advanced Settings, still here is a screenshot about the default settings:
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.
STEP 2 - Attribute mapping
Click on the View 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 |
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.
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.
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
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).
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.
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
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
Select: Enable SCIM provisioning
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
.
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.
IMPORT GROUPS
!!!Click on test. Test results looks like this:
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 the attribute mapping to send only the necessary attributes through SCIM to Flexopus. Only keep the following mappings:
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
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:
WORKAROUND:
Navigate in Okta to Application > Browse App Catalog --> SCIM 2.0 Test App (Header Auth)
You can rename the application: Flexopus SCIM App
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
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}
Click on Test connection
Enable: Select Create Users
Enable: Update User Attributes
Enable: Deactivate Users
The fourth option is not needed.
Edit the attribute mapping to send only the necessary attributes through SCIM to Flexopus. Only keep the following mappings:
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
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.
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:
- User deleted from group
AllFlexopusUsers
group - 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.
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.
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