This guide provides step-by-step instructions on configuring Okta as your IdP for Single Sign-On (SSO) authentication. Descope provides an integration with Okta to easily add a custom Okta application to your Okta App Dashboard. This guide contains setup instructions for the app integration and instructions on mapping user and group attributes correctly.
The Okta/Descope SAML integration currently supports the following features:
- SP-initiated SSO
- IdP-initiated SSO
- JIT (Just-In-Time) Provisioning
For more information on the listed features, visit the Okta Glossary.
Below is the table of contents for this particular guide.
Follow these steps to successful configure the Okta/Descope Integration in your Okta account. This will allow you to use SAML SSO to login to your own apps initiated from the IdP (Okta) and SP (Descope/Your App).
- Add the app from the Okta Integration Marketplace
- When you first add the integration, assign a name for the custom app you're building and click Done
NOTE: The logo can also be changed once the app has been added, so it uses your branding.
- Once you've added the app, under Assignments, add the relevant User and Group assignments to your new application.
- Now, head to the Tenants page in the Descope Console, and select the Tenant you wish to use with Descope (if you don’t have one, you can create one).
- Under Tenant Details, make sure that your domain is in the list of emails allowed to sign up with your tenant.
- Under SSO Configuration, copy over the Entity ID and the ACS URL. Then head back to Okta and paste the two values in under Sign On > Advanced Sign-on Settings:
- Back in Okta, go to Sign on methods > SAML 2.0 > Metadata details, to locate and copy your Metadata URL.
- Head back to the Descope Console, and under SSO Configuration, paste the Metadata URL (from the previous step). Also fill out the Tenant Domain (the domain of the tenant you wish to provision), and a Post Authentication Redirect URL if applicable.
After that, you should be able to use the custom app. If you wish to map user and group attributes to what you've configured in Okta, read on to the next section on Attribute Mapping.
If you wish to map user and group attributes from Descope in Okta, you will need to first configure them in your Descope Console, and then configure the mapping values in the app configuration settings. Follow the instructions below to complete this:
Note: Descope also allows you to map attributes from your IdP to custom user attributes when configuring your attribute mapping.
- In the Descope Console, select your Tenant and then click on SSO Mapping in the top menu. Ensure that all of the applicable user and group attributes are configured correctly in the Descope Console:
- Then head back to Okta, and select the Edit button in Settings under Sign On. You should be able to expand Attributes (Optional), where you can place the values you configured for Group and User attributes in previous step.
You can use those two pictures provided above, as an example of how the attributes and groups should be matched.
If you wish to use the Okta app to initiate the SSO, you'll need to make sure you're using the proper flow, to force initiated SSO if Descope recognizes it. You can do this by utilizing a Conditional block at the beginning of your flow:
An example flow that can use IdP-Initiated SSO can be downloaded from our Descope Explorer
The embed link you can use to started the IdP-Initiated SSO can be found under General in the Okta Configuration Dashboard:
https://auth.descope.io/YOUR_DESCOPE_PROJECT_ID?flow=YOUR_FLOW_IDto see your Flow in action and to test the SSO.
NOTE: the domain of the email you're using to login, must match how you configured SSO in your Descope Console
Currently Updating User Attributes, Deactiving Users, and Group Push are the only items supported by Descope. SCIM Create within Descope is not currently supported.
There are two methods for linking Okta Users and Descope Users, in order to succesfully update user attributes using SCIM:
1: Create two instances of the app, one for SAML (see instructions above) and one for SCIM. With this, you'll be able to login through SAML to create a user, then assign the same user to the SCIM app instance to link those users. 2. Create just one instance of the app. If you're using this method, you will need to make sure that your Descope and Okta Users are synced following the setup process. Refer to the Error Handling guide in order to handle this.
- You must already have SSO enabled and users logging in via SSO within your Descope tenant.
- You must create a tenant for your customer and be associated with an access key with the
Tenant Adminrole. It is essential to note the access key's expiration; if it is expired or revoked, the SCIM provisioning integration will no longer work. For more information on creating tenants, see the Tenant Management Guide. For more information on access keys, see the Access Key Management Guide.
- Within Okta, you should have People and Groups assigned to the application.
Enable SCIM provisioning. Once you have done this, you will see the provisioning tab added to your Okta application.
The next step is to navigate to the Provisioning tab within your application. Here you will provide the following:
- SCIM connector base URL:
- Unique identifier field for users:
- Supported provisioning actions:
Descope supports Push Profile Updatesand
Push Groups- select these two checkboxes.
- Authentication Mode: Select HTTP Header
- Authorization: This will be the bearer. The format for this bearer is
ProjectId:AccessKey. This AccessKey is the one referenced within the prerequisites and the Access Key associated with the tenant you are configuring SCIM provisioning.
Once you have populated these fields, you will test the connection configuration. This test will return a box that confirms both
Descope supports Push Profile Updatesand
Push Groupsare connected successfully.
The next step is to go to the
To Appsection within the Provisioning settings. Here you will check the checkboxes to enable
Update User Attributesand
The user must verify that the Assignments have correctly synced to the Descope service via SCIM provisioning. If there are errors within people or groups within the Assignments tab, you will need to follow the Error Handling guide below.
After successfully configuring the SCIM connection, you will have a new tab within the application for Push Groups. From this tab, you can push groups to the Descope tenant. These groups that are pushed to the Descope service will then be usable within API calls to the Descope service.
Once your tenant utilizes SCIM provisioning, all changes from Okta will be reflected in the Descope service and synced to the user's logins and sessions. These changes occur on the next refresh of the user's session JwT.
- Turn off SCIM Provisioning in the integration:
- Assign a user to the integration:
- Login using the Embed Link of the app, to create an account in Descope using SAML SSO:
- Go back to the screen in Step 1, and Turn on SCIM Provisioning.
- Click Provision User to link users in Okta and Descope:
Once that's complete, your user should be successfully linked in Okta with Descope, and SCIM provisioning can now be succesfully used.