Skip to main content

SCIM Setup with Authorization Code (Okta)

Updated

This page explains the setup process for user provisioning with SCIM using the Authorization Code authentication method, which is necessary to integrate with Okta. For an overview of the SCIM functionality, see Managing users with SCIM provisioning, and if you're using Microsoft Entra instead of Okta as your IdP, see SCIM Setup with Client Credentials (Microsoft Entra).

Step-by-Step Intructions

Please make sure to follow these setps carefully, as a misconfiguration may prevent the integration from working or result in unexpected provisioning behavior.

Step 1: Create Your App in Okta

You must create a custom application in Okta in order to manage this integration. If you have already created an app for the Okta SAML integration, then you can reuse that app and skip to Step 2.

  1. Login to the Okta admin console and navigate to the Applications page.

  2. Click Create App Integration.

  3. Select your sign-in method:

    • If you are also going to enable SAML single sign-on with Okta, then choose the SAML 2.0 option and follow the instructions in that article to configure the SAML aspect.
    • If you are only using Okta for SCIM provisioning and not for sign-in, then this choice matters less - the steps below show how it looks for SAML 2.0, but you could also use SWA - Secure Web Authentication.

  4. Give the app a name (e.g. "Read AI") and click next.

  5. If you are also enabling SAML, you should follow the instructions here to properly configure this step. If you will not be using SAML, you just need to enter some dummy values into the required fields on the Configure SAML step:

    Only the first two fields are required - any values will work, as long as your sign-on URL begins with https://. Scroll down and click next.

  6. Complete the final Feedback step (this is just feedback for Okta, and has no impact on the integration functionality), and click Finish.

Step 2: Generate SCIM Credentials in Read AI

The following steps all occur on Read AI.

  1. Go to your workspace settings and expand the Advanced section.

  2. Turn on the Enable SCIM provisioning setting.

  3. Select the OAuth 2.0 Authorization Code option.

  4. Add your redirect URI(s).

    The required redirect URI is https://system-admin.okta.com/admin/app/cpc/{appName}/oauth/callback, but you must replace the {appName} with the appropriate identifier from Okta.

    You can obtain the {appName} from the Okta Admin Console URL, when you have your app instance selected. The Admin Console URL has the following format: https://{orgSubDomain}-admin.{oktaEnvironment}.com/admin/app/{appName}/instance/{instanceID}/#tab-general

    The {appName} is the string between /app/ and /instance/ in the URL after you create your app integration instance in Okta.

    For more details and other URIs you may need to add depending on your situation, see Okta's documentation.

  5. Click Generate Credentials to obtain your Client ID and Client Secret (copy these; the secret is only shown once and will need to be regenerated if you lose it).

  6. Also note the Authorization URL, Tenant URL, and Token URL, as you'll need these later too.

  7. Decide whether you want license auto-charge to be enabled. If disabled, provisioning will fail and throw errors in Okta whenever you run out of available licenses in your workspace. You can configure a limit for the maximum number of seats your workspace can reach via auto-charge (more can always be purchased manually).

Step 3: Configure SCIM in Okta

Go back to your app in Okta to continue setup.

  1. On the General tab of your app in Okta, edit the App Settings to enable SCIM provisioning and click save.

  2. A new Provisioning tab will appear; click on it and edit the settings.

  3. Fill in the appropriate values for the settings.

    • SCIM connector base URL = copy the Tenant URL from Read AI workspace settings
    • Unique identifier field for users = userName
    • Supported provisioning actions = Import New Users and Profile Updates, Push New Users, Push Profile Updates
    • Authentication Mode = OAuth 2
    • Grant Type = Authorization Code
    • Access token endpoint URI = copy the Token URL from Read AI workspace settings
    • Authorization endpoint URI = copy the Authorization URL from Read AI workspace settings
    • Client ID = copy the Client ID from Read AI workspace settings
    • Client Secret = copy the Client Secret from Read AI workspace settings

  4. Click Save once you've provided all of the details, and Okta will automatically test the configuration.

  5. Click Authenticate with [your app's label] which will start the authorization process on Read AI. Allow access to proceed.

Step 4: Attribute Mapping

The next step involves configuring which attributes actually get sent to Read AI for the supported provisioning events.

  1. Back under the provisioning settings, select To App, edit to enable the Create Users, Update User Attributes, and Deactivate Users checkboxes, and click save.

  2. Scroll down to the Attribute Mapping section and unmap all attributes except the 5 shown here, by clicking the X on each row:

Step 5: Select Users and Groups to Sync

The final step is to "assign" users to your app, which is how you choose which users will be provisioned by SCIM. 

  1. Go to the Assignments tab of your app and use the Assign to People button.

  2. Search for users and click Assign next to the ones you want to add. You should not have to edit any of the other user properties here, just click Save and Go Back.

  3. Automatic provisioning will start immediately, and you may quickly see an error here if Okta is able to detect any issues with one of the users. E.g. if you are trying to provision a user who is already in another workspace, you'll see an error like this:

  4. Remember that only the users you assign here will be provisioned and managed by SCIM/Okta. We recommend assigning all users in Okta who you want to have access to Read AI.

Step 6: Complete and Monitor Provisioning

  1. Provisioning should have started automatically when you started assigning users.
  2. Provisioning runs automatically every ~40 minutes, creating and deactivating users in your Read AI workspace as necessary to keep it in sync with your Okta application.
  3. You can monitor sync status and errors in Okta. We will also send you email notifications if users fail to get provisioned for any reason.

Notes and Troubleshooting

Make sure to review the notes here to fully understand how SCIM provisioning works, and if you have any issues, check the troubleshooting tips. 

Related articles