Introduction

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.

1. How to Configure SAML
2. How to Configure OIDC
3. IdP-Initiated SSO
4. SP-Initiated SSO
5. Configuring SCIM

Note: IdP-initiated SSO is only supported with SAML SSO. Meanwhile SP-initiated SSO, JIT, and SCIM work with both OIDC and SAML SSO.

How To Configure SAML SSO

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).

1. Add the app from the Okta Integration Marketplace
2. 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.

3. Once you've added the app, under Assignments, add the relevant User and Group assignments to your new application.
4. 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).
5. Within Tenant Settings, make sure that your domain is in the list of emails allowed to sign up with your tenant.
6. Within Authentication Methods -> SSO, and select SAML. Then under Service Provider, copy over the Entity ID and the ACS URL and head back to Okta and paste the two values in under Sign On > Advanced Sign-on Settings:

7. Back in Okta, go to Sign on methods > SAML 2.0 > Metadata details, to locate and copy your Metadata URL.
8. Head back to the Descope Console, and under SSO Configuration, paste the Metadata URL (from the previous step). Also fill out the SSO Domain field (all of the domains of the tenant you wish to provision for SSO), 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.

SAML 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.

1. In the Descope Console, select your Tenant and under Authentication Methods -> SSO, ensure that all of the applicable user and group attributes are configured correctly in the Descope Console:

2. 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.

How To Configure OIDC SSO

Follow these steps to successful configure the Okta/Descope Integration in your Okta account. This will allow you to use OIDC SSO to login to your own apps initiated from the IdP (Okta) and SP (Descope/Your App).

1. Add the app from the Okta Integration Marketplace
2. When you first add the integration, assign a name for the custom app you're building and click Done

3. Once you've added the app, under Assignments, add the relevant User and Group assignments to your new application.
4. 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).
5. Within Tenant Settings, make sure that your domain is in the list of emails allowed to sign up with your tenant.
6. Within Authentication Methods -> SSO, and select OIDC. Then head back to Okta and under Sign On, select OpenID Connect and save your changes. You should see a Client ID and Client Secret present in the same field. Copy and paste those two values into the Descope SSO Configuration, along with the following items:

Example JSON:

{"issuer":"https://dev-428923423.okta.com","authorization_endpoint":"https://dev-428923423.okta.com/oauth2/v1/authorize","token_endpoint":"https://dev-428923423.okta.com/oauth2/v1/token","userinfo_endpoint":"https://dev-428923423.okta.com/oauth2/v1/userinfo","registration_endpoint":"https://dev-428923423.okta.com/oauth2/v1/clients","jwks_uri":"https://dev-428923423.okta.com/oauth2/v1/keys"}

You'll need to extract the following endpoints and place them in the SSO configuration settings in the Descope Console:

• Authorization endpoint
• Token endpoint
• Userinfo endpoint
• JWKs URI

7. You'll to need to make sure to add the Descope Callback URL to the Callback URL field in your Okta application:

NOTE: If you've configured a custom domain in Descope, make sure you input your custom domain in the Callback Domain field first, before copying the URL over into Okta.

After that, you should be able to use the custom app. If you wish to map custom user attributes to what you've configured in Okta, read on to the next section on Attribute Mapping.

OIDC 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 Okta API 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.

1. In the Descope Console, select your Tenant and under Authentication Methods -> SSO, ensure that all of the applicable user and group attributes are configured correctly in the Descope Console:

2. Then head back to Okta, and add custom claims to your OIDC tokens. You can do by following the steps in the Okta documentation. This will ensure all of the necessary claims are passed back to Descope.

You can use those two pictures provided above, as an example of how the attributes and groups should be matched.

IdP-Initiated SSO

Note: IdP-initiated SSO is only supported if you've configured SAML SSO. IdP-initiated SSO will not work with OIDC.

If you wish to use the Okta app to initiate the SAML 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:

SP Initiated SSO

Note: SP-initiated SSO is supported with SAML SSO and OIDC SSO.

If you want to test SP-Initiated SSO, you can use our Hosted Auth Application. You'll need to retrieve your Project ID, and the ID of the Flow you're using to use our hosted application.

NOTE: the domain of the email you're using to login, must match how you configured SSO in your Descope Console

Configuring SCIM

Note: SCIM is supported with SAML SSO and OIDC SSO.

The Okta/Descope SAML integration currently supports the following SCIM functions:

• Create Users
• Update User Attributes
• Deactivate Users
• Import Users
• Group Push

The Okta integration application also supports SCIM provisioning for your users. For more detailed information about SCIM or our SCIM endpoints, you can refer to our docs page.

If you're using SCIM and the SAML integration together, and you want to control user provisioning via SCIM, but authentication via SAML SSO. To do this, you can disable JIT Provisioning in the Descope Console.

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.

JIT Provisioning

By turning off JIT, this will ensure that SCIM is the primary manager of user attributes and groups, and that none of these user-level attributes are overwritten by any external SSO IdP.

Prerequisites for configuring SCIM

• 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 Admin role. 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.

Configure SCIM Connection

• Project ID - You can find your Project ID under Project Settings in the Descope Console.
• Access Keys - If you don't already have one you can create one under Access Keys. The access key has to be assigned to the specific SCIM tenant, with the role as a Tenant Admin.

Once you have populated these fields, you can test your configuration with the Test API Credentials button. If successful it should show a green box showing the API connection was verified.

Validating Assignments and Push Groups

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.

Note: With the Import Users functionality and SCIM, users created in Descope or Okta must include the attributes for givenName and familyName, in order for the respective IdPs to be able to recognize the users.

Error Handling

1. Turn off SCIM Provisioning in the integration:

2. Assign a user to the integration:

3. Login using the Embed Link of the app, to create an account in Descope using SAML SSO:

4. Go back to the screen in Step 1, and Turn on SCIM Provisioning.
5. 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.