Okta OIDC

Each SSO identity provider requires specific information to create and configure a new SSO connection. Often, the information required to create an SSO connection will differ by identity provider.

To create an Okta OIDC SSO connection, you’ll need four pieces of information: a redirect URI, client ID, client secret, and discovery endpoint.

Start by logging in to your WorkOS dashboard and navigate to the Organizations page from the left-hand navigation bar.

Select the organization you’d like to configure an Okta OIDC SSO connection for, and select Configure manually under Single Sign-On.

Select Okta OIDC from the identity provider dropdown, enter a descriptive name for the connection, click Create Connection.

WorkOS provides the Redirect URI, which can be found in the Service Provider Details section on the SSO connection page in the WorkOS Dashboard.

• Redirect URI: The endpoint where identity providers send authentication responses after successful login

The Redirect URI is the location an identity provider redirects its authentication response to. In Okta’s case, it needs to be set as the Sign-in redirect URI when configuring your OIDC application in their Okta instance.

Specifically, the Redirect URI will need to be added to the Sign-in redirect URIs section in the Create OpenID Connect Integration wizard, which is outlined in step 2.

You will need to obtain three pieces of information from the organization:

• Client ID: Application identifier from the OIDC provider
• Client secret: Authentication secret for the application
• Discovery endpoint: Configuration URL containing OIDC metadata

Normally, this information will come from the organization’s IT Management team when they set up your application’s OIDC configuration in their Okta admin dashboard. But, should that not be the case during your setup, the next steps will show you how to obtain it.

Log in to the Okta admin console, and select Applications in the left-hand sidebar.

Click Create App Integration.

In the Create a new app integration dialog, select OIDC – OpenID Connect and Web Application.

Click Next.

Enter a descriptive App name, then configure the Sign-in redirect URI.

Locate the Sign-in redirect URIs section and click Add URI. Copy the Redirect URI from the SSO connection page in your WorkOS Dashboard and paste it into this field.

Scroll down to the Assignments section. Select Limit access to selected groups and assign the appropriate groups to the application. This can be edited later.

Click Save.

On the General tab, locate the Client ID and Client secret. Back in the WorkOS Dashboard, enter the client ID, and client secret into the respective fields in the Identity Provider Configuration section of the SSO connection.

In the top right-hand navigation, click your user email and locate the Okta tenant domain which usually ends with .okta.com.

Copy this value and define the discovery endpoint in the format: https://{tenant-domain}/.well-known/openid-configuration. Enter this URL in the Discovery Endpoint field in the WorkOS dashboard.

Click Save Configuration.

With identity provider role assignment, users can receive roles within your application based on their group memberships. Users will automatically be granted the assigned roles within your application when they authenticate. To enable this functionality:

Navigate to the Sign On tab of your OIDC application, locate the Claims section, and click Edit.

Set the Groups claim type to Filter. Define the Groups claim filter as groups and set a filter to match the appropriate Okta groups. To match all groups, use the regex .* as shown below.

In Okta, navigate to the Assignments tab in the application. Locate the Filters sidebar, click on Groups to filter and display all the assigned groups available to map.

From the SSO connection page in the WorkOS Dashboard, scroll to the Groups and role assignments section.

For each group you want to assign a role, click the Create group button and enter the following:

1. Copy the group name from Okta into the IdP ID field.
2. Optionally, enter a group name into the Name field.
3. Assign the appropriate role to the group.

Your Okta OIDC connection is now configured and ready to use. Users assigned to the application in Okta will be able to authenticate through WorkOS using their Okta credentials.

To start using this connection in your application, refer to the SSO guide for implementation details.