Setup OKTA SCIM for Automated User provisioning | Sohonet CORE Help Center

Setup OKTA SCIM for Automated User provisioning

September 5, 2023

SCIM (System for Cross-domain Identity Management) with Okta. Okta Users can be automatically provisioned into roles within CORE to streamline the onboarding and administrative process.

What is SCIM

SCIM, or System for Cross-domain Identity Management, is an open standard that allows for the automation of user provisioning. SCIM communicates user identity data between identity providers (such as companies with multiple individual users) and service providers requiring user identity information (such as enterprise SaaS apps).

Information required

Before you start, you should have received credentials. If you have not, please contact customer support at customer-support@sohonet.com.

SAML information

Single Sign On URL: https://[api-host]/auth/sso/saml2/login api-host to be provided
Recipient URL: (same as Single Sign On URL)
Destination URL: (same as Single Sign On URL)
Audience Restriction: TO-BE-PROVIDED
SCIM connector base URL: https://[api-host]/scim api-host to be provided

OAuth2 information

CORE Use OAuth2 for SCIM provisioning authentication.

Access token endpoint URI: https://[api-host]/oauth2/token api-host to be provided
Authorization endpoint URI: https://[api-host]/oauth2/authorize api-host to be provided
Client ID: TO-BE-PROVIDED
Client Secret: TO-BE-PROVIDED

SAML Setup

Regular SAML application

The SAML/SCIM integration starts as a regular App Integration Process.

SCIM integration is based on SAML, please choose SAML 2.0 Integration.

Enter the name of the app and click on Next.

Under SAML settings, enter the Single Sign On url, and then mark the checkbox to use the same url for Recipient and Destination.

All other settings are left as suggested by OKTA.

Required Fields for the Integration

The following fields are required for the integration to work. Optional fields are listed below as well.

UID (this is the userName)
FirstName
LastName
Email

Then the rest (optional):

Title on Okta maps to Position on CORE
Organization on Okta maps to Company on CORE
Department on Okta maps to Department on CORE
Group maps on Okta to Role on CORE

Important distinction between Groups and Push Groups: Groups map to Roles when using SSO only, Push Groups map to Roles when provisioning users through SCIM.

You might need to adjust these settings accordingly. From the CORE side, the following fields are required:

UID
FirstName
LastName
Email

Important notes about UID

Additionally, UID is used to identify the user. Please make sure that if a UID other than firstName + “.” + lastName is chosen, this change is communicated to customer support at customer-support@sohonet.com, since it would effectively change the identifier for users and could cause account duplication.

This UID is needed to connect provisioned users to those who sign in with SSO. If there is any mismatch, users might end up having duplicate accounts in CORE.

Lastly, mark the app as internal, since it’s not a published app within Okta.

Up to this point, SSO is properly configured.

SAML Certificate

Please share the certificate with Sohonet to get the integration working.

SCIM Provisioning

Provisioning tab

Now let’s enable provisioning on this new app.

Go to the General tab
Edit the App Settings
Choose SCIM.

This should enable the Provisioning section of the app.

Connection settings

Under SCIM Connection settings, enter the SCIM Connector Base URL, userName as Unique Identifier field for Users and enable the following items:

Import New Users and Profile Updates
Push New Users
Push Profile Updates
Push Groups

And leave Import Groups unchecked.

Authentication Mode

Then select the Authentication Mode as OAuth 2

Under OAuth2 settings, enter the provided URLs for this integration, Client ID and Client Secret, then click on Save. ( NOTE: Sohonet will need to provide the Client ID and Client Secret, please reach out to customer-support@sohonet.com to request this.)

This will trigger an authentication request to CORE.

If the authentication is successful, a green notification box will appear with the results. Click on the Re-authenticate button if that is not the case.

Important notes about Re-Authentication

If anything is changed under either General or Sign On tabs, this Re-authentication button will disappear. To bring that button back, go to the Provisioning tab, then Integration, and then Edit the SCIM Connection. Don’t change anything here, just click on Save to make the button reappear.

UID Attribute needed to match SAML provisioning

SCIM doesn’t offer a way to set the unique identifier when provisioning users. The SCIM protocol uses the userName attribute for that, querying the downstream system to check if the user exists. If not, a request will be sent to provision it.

CORE SSO login also provisions users when logging in. Users are identified by the UID attribute in the SAML assertion. This requires both SAML and SCIM provisioning to be aligned to make sure users don’t end up with duplicated accounts when provisioned through both channels.

To achieve this, we need to add a custom attribute to SCIM provisioning, name it UID (or the name used in SAML config if different) and make it match the value SAML will be using when negotiating the sign on.

Go to the “ Application”, “ Provisioning” Tab:

Under “ To App”, scroll down to “ [application name] Attribute Mappings” and click on “ Go to Profile Editor”.

In the “Go to Profile Editor” click on “ Add Attribute”.

Complete the form for the new attribute as follows, making sure the “External namespace” is set to “ urn:ietf:params:scim:schemas:extension:enterprise:2.0:User” , and that it’s Scope is “ Personal”.

Click on “Save” and navigate away from this page (to make sure Okta refreshes the content).

Navigate back to the app you are configuring under the Applications section.

Select your app, and go back to the “ Provisioning” tab.

In the “ To App” section, to complete the mapping for the new attribute.

Scroll down to find the new UID attribute and click on the “ Edit” pencil icon.

Then choose “ Map from Okta Profile” and select the value that will identify the user, which should be the same as the SAML configuration for UID. This value has to be unique per user.

Important:

If the unique identifier is named other than UID in the SAML config, choose the same name here, otherwise users would get duplicated accounts.

Assigning Groups to Users for SCIM (using Push Groups)

The only way for Okta to include groups in the user’s provisioning request is to link groups as Push Groups in the application configuration.

Go back to the Push Groups section of your application.

In this section,

Click on the small gear icon to open the settings dialog.
Uncheck the “ Rename app groups to match group name” in Okta settings.
Click Save.

This will allow sending the Group with a different name in the request to 5th Kind Core.

Find the Group you would like to link as Push Group either by name or by rule and choose the new name (the name of the Role in 5th Kind Core) or leave it as is if a different name is not needed.

Notes & Caveats About the CORE/Okta SSO SCIM integration

This is the first phase of our Okta SCIM provisioning, which we plan to expand upon further. Below is an outline including what you can and cannot yet achieve with the current integration. If you find that you require additional functionality, please submit your requests to support@5thkind.com and/or your client account manager.

Groups vs Push Groups.
- Groups on Okta are not sent to the Service Provider (CORE) through SCIM provisioning; they are however sent during the SAML authentication.
- To send Groups (Roles on CORE) when provisioning through SCIM, they have to be linked as Push Groups under the application’s Push Group section.
- If the name of the Push Group needs to have a different name from the Role in CORE, the Push Group setting “ Rename app groups to match group name in Okta” has to be unchecked to allow for a different name to be sent in the provisioning request to CORE.
- Push Groups is the only way for Okta to send the user’s provisioning request together with the groups they belong to. At the same time, this is the only place where the Push Group can be mapped to a different Role within CORE by sending a different name in the request.
- A Push Group can be created and active within the application but if the underlying Group is not assigned to the application it won’t be provisioned on CORE.
Deleting a group from SCIM will not delete the Role in CORE. When required, a role will need to be deleted directly within CORE.
Creating a group from SCIM will not create the Role in CORE. You will have to create a User Role (group) on the CORE side as well.
Deleting a user from SCIM will not delete this user from CORE. Instead, it will mark that user as 'expired', and they won’t be able to login anymore.
Changing a username once the user is synced and logged into 5th Kind Core will not change the user’s username; instead, it would cause an account duplication.
The username is expected to be an email address (this is OKTA default).
Changes to a user’s profile can be made for First Name, Last Name, Title, Company/org, and Department, after a user has logged in and synced with CORE.
It is not advised to update the user's email address from SCIM. To update user email addresses, it has to be done within CORE.
If a user is 'deactivated' on SCIM, it will be treated as 'expired' in CORE.
Reactivating a previously 'deactivated' user on Okta will not unexpire them on CORE. To reactivate an expired user, you will need to change the user’s status directly in Core.
Non-active users on SCIM won’t be sent to CORE.
When using the user’s Name as the UID (versus email for example), First Name or Last Name cannot be changed anymore. Doing so will cause the systems to lose the SSO handshake ID and there’s no way to reconnect the SSO ID, as it’s sent to Core by the identity provider in every login (SSO handshake). If you would like to configure the SCIM integration with another UID, such as user email, please make a request via customer-support@sohonet.com so the appropriate changes can be made on both sides.