# 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](mailto:customer-support@sohonet.com). ### SAML information - _Single Sign On URL_: [https://[api-host]/auth/sso/saml2/login](https://core-help.sohonet.com/en/articles/85864-setup-okta-scim-for-automated-user-provisioning) **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](https://core-help.sohonet.com/en/articles/85864-setup-okta-scim-for-automated-user-provisioning) **api-host to be provided** ### OAuth2 information CORE Use **OAuth2** for SCIM provisioning authentication. - _Access token endpoint URI_: [https://[api-host]/oauth2/token](https://core-help.sohonet.com/en/articles/85864-setup-okta-scim-for-automated-user-provisioning) **api-host to be provided** - _Authorization endpoint URI_: [https://[api-host]/oauth2/authorize](https://core-help.sohonet.com/en/articles/85864-setup-okta-scim-for-automated-user-provisioning) **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](mailto: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. 1. Go to the General tab 2. Edit the App Settings 3. 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](mailto: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, 1. Click on the small gear icon to open the settings dialog. 2. Uncheck the “ _Rename app groups to match group name_” in Okta settings. 3. 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](mailto: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](mailto:customer-support@sohonet.com) so the appropriate changes can be made on both sides.