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.

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

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.

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:

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.

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

 R0087