Okta SAML2 + SCIM

Introduction

Connect Flexopus with Okta via SAML2 for Single Sign On. With the integration, you can manage which Okta users 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 navigate to Applications > Applications. Click on 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, enter the Single sign-on URL, Audience URL (SP Entity ID), and Default RelayState. You can find these parameters in Flexopus by navigating to Dashboard > Settings > Authentication as an administrator. Click on 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 complete the setup, follow these steps to share metadata with Flexopus:

1. Copy the content in the field labeled Provide the following IDP metadata to your SP provider (found at the bottom of the Okta configuration page).
2. Create a new, empty XML file on your computer.
3. Paste the copied content into this XML file and save it.

This file will serve as the metadata for Flexopus.

STEP 3 - Configure Flexopus

• In Flexopus, navigate to Dashboard > Settings > Authentication.
• Select the newly created SAML2 Provider.
• Enable SAML2 SSO.
• Choose Metadata file instead of metadata URL for the configuration option.
• Upload the Metadata file you created from Okta.

1. Enter the name for the SAML2 Login button to display on the login page (recommended: SSO Login).
2. (Optional) Enable synchronization for fields configured in the SAML2 settings, such as jobtitle or department.

• In Security Settings, set allowed domains for SSO to * and press ENTER. This will allow every user configured in your Active Directory to log in.
• By default, SAML2 SSO users are automatically registered after their first login attempt. This saves you from needing to create user profiles manually before the first login; however, this setting can be disabled if necessary (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 set up user and group provisioning between Okta and Flexopus. To start configuring SCIM:

1. Click on Edit in the App Settings.
2. Follow the instructions provided for SCIM setup to enable provisioning.

Select: Enable SCIM provisioning

• In Okta, navigate to the Provisioning tab and click on Edit.
• Go to your Flexopus admin dashboard: Dashboard > Settings > Integrations.
• Locate the SCIM connector base URL and generate the SCIM API token for 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 needs 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:

• In Okta, go to Applications > Browse App Catalog.
• Search for SCIM 2.0 Test App (Header Auth) and select it.

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

• In your Flexopus Dashboard, go to Dashboard > Settings > Integrations.
• Locate the Base URL and click Generate API token.
• Copy the Base URL and API token for use in Okta SCIM integration.

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

To optimize group management:

1. Sync Only Necessary Groups: Limit syncing to groups in Okta that have a clear purpose in Flexopus. Avoid syncing groups solely for desk assignments; manage those directly in Flexopus.
2. Centralized Group Management: Use Okta for broadly applicable groups (e.g., AllCompanyUsers). More specific groups (e.g., DepartmentAWorkstationGroup2) can be created and managed in Flexopus.
3. Define Management Responsibility: Decide which department (IT, Facility Management, HR) is responsible for group assignments. Only those responsible should manage these groups directly.
4. Minimize IT Dependence: Ensure group managers have direct access to manage relevant groups in Flexopus, reducing dependency on IT for adjustments and avoiding unnecessary support tickets.

Suggestion - One external group

To streamline user management:

1. Create a Single Access Group (AllFlexopusUsers):
   • Sync only the AllFlexopusUsers group, which contains all users requiring Flexopus access.
   • Provisioning this group syncs all users within to Flexopus, even if they haven’t logged in yet.
2. User Management in Flexopus:
   • Flexopus admins can locally create and manage additional groups.
   • Flexopus admins gain flexibility without needing IT for every change, minimizing admin workload.
3. Use Cases:
   • New Employee: Add new hires to AllFlexopusUsers in AD during onboarding to ensure their Flexopus access from day one.
   • Employee Leaving: Remove departing employees from AllFlexopusUsers or delete them from AD. Flexopus deactivates their profile automatically, blocking login. See the deletion concept in Flexopus for automating user removals.

How can I disable the SCIM Integration?

To disable the SCIM integration:

1. Go to Okta and turn off the SCIM integration.
2. In Flexopus, navigate to Dashboard > Settings > Integrations as an administrator.
3. Click Delete token to complete the deactivation.

When you click Delete token in Flexopus:

1. A popup will appear, prompting you to Detach the groups.
2. Enable this option to convert the current external read-only groups into internal groups, allowing you to edit them afterward.

You are done. The SCIM integration is deleted.

Trouble Shooting / FAQ

 R0087