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
2. Attribute Mapping
3. IdP-Initiated SSO
4. SP-Initiated SSO
5. Configuring SCIM

How To Configure

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. Under Tenant Details, make sure that your domain is in the list of emails allowed to sign up with your tenant.
6. 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:

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

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 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:

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.

IdP-Initiated SSO

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:

SP Initiated 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

Currently Updating User Attributes, Deactiving Users, and Group Push are the only items supported by Descope. SCIM Create within Descope is not currently supported.

Use Cases of SCIM

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.

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.

Enable SCIM Provisioning

Configure SCIM Connection

The next step is to navigate to the Provisioning tab within your application. Here you will provide the following:

• SCIM connector base URL: https://api.descope.com/scim/v2
• Unique identifier field for users: email
• Supported provisioning actions: Descope supports Push Profile Updates and 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.

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.

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.