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.
In this Article
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 [email protected].
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.
In this page also enter the Audience Restriction/URI provided (ENTITY_ID in the sample)
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 [email protected], 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 [email protected] 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. It’s not clear if it’s on purpose or a bug on Okta.
To bring that button back please go to the Provisioning tab, then Integration, and then Edit the SCIM Connection. Don’t change anything here, just click on Save and this will 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.
After that the Push Group request will be sent to 5th Kind Core to map the Push Group with 5th Kind Core Role. You should see the Push Group as active after a few seconds.
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 [email protected] 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.
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 [email protected] so the appropriate changes can be made on both sides