Skip to main content

Add Okta Workforce as a SAML connection

Before you start

Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP).

When you configure a SAML connection with Okta Workforce as your IdP, your users can sign up and sign in to your application with their Okta account. In this guide, you configure the connection in the Clerk Dashboard, while the customer (whoever manages the Okta application) configures it on the Okta side.

Tip

This guide requires coordination between you and your customers' IT administrators. If you're creating an enterprise connection for an Organization, you can allow your customers' IT admins to configure SSO themselves. See the guide on self-serve SSO for more information.

Create an Okta SAML connection in Clerk

  1. In the Clerk Dashboard, navigate to the SSO connections page.
  2. Select Add connection and select For specific domains or organizations.
  3. Under SAML, select Okta Workforce.
  4. Enter the Domain. This is the email domain of the users you want to allow to sign in to your app. Optionally, select an Organization.
  5. Enter the Name. This will be displayed on the sign-in form.
  6. Select Add connection. You'll be redirected to the connection's configuration page. Note that the connection is disabled by default.
  7. In the Service Provider Configuration section, save the Single sign-on URL and Audience URI (SP Entity ID) values somewhere secure. You'll need to give these to the customer so they can configure their Okta app.

Configure SAML application

Now that the enterprise connection is configured in Clerk and the Single sign-on URL and Audience URI (SP Entity ID) are known, the customer's Okta app needs to be configured. At a high level, the process is:

  • Create a SAML application in Okta.
  • Add the Single sign-on URL and Audience URI (SP Entity ID) from Clerk to the Okta app's SAML configuration.
  • Configure the attribute statements.
  • Assign users or groups to the application.
  • Share the app's Metadata URL.

To get you started, you can use the following email template with detailed instructions. Remember to share the Single sign-on URL and Audience URI (SP Entity ID):

Here are the instructions for setting up SAML SSO with Okta Workforce:

Step 1: Create a SAML application in Okta

  1. Sign in to Okta and go to Admin → Applications.
  2. Select Create App Integration and select SAML 2.0.
  3. Fill in the General Settings. The app name is required.
  4. Select Next to open the Configure SAML page.
  5. Add the Single sign-on URL and Audience URI (SP Entity ID) values provided to you.
  6. From the Feedback page, select This is an internal app that we have created, then select Finish.

Step 2: Configure attribute statements

Your SAML response must include the user's email, and can optionally include their first and last name.

  1. Find the Attribute Statements section.

  2. Select Add Expression for each attribute, and enter the following name and expression pairs:

    Attribute nameRequiredExpression
    mail✅user.profile.email
    firstName❌user.profile.firstName
    lastName❌user.profile.lastName

Step 3: Assign users to the application

Assign users or groups before they can sign in with SSO.

  1. Select the Assignments tab.
  2. Open the Assign dropdown and select Assign to people or Assign to groups.
  3. Search for the user or group to assign.
  4. Select Assign next to the user or group.
  5. Select Done.

Step 4: Share the app's metadata URL

On the application's Sign On tab, under Sign on methods, copy the Metadata URL and send it back.

Add the Metadata URL in the Clerk Dashboard

After following the instructions in the email, your customer should have sent you the Okta app's Metadata URL. Now, you're going to add it to the Clerk connection, completing the SAML connection configuration.

  1. Navigate to the SSO connections page in the Clerk Dashboard.
  2. Select the SAML connection.
  3. In the Identity Provider Configuration section, under Metadata configuration, paste the Metadata URL that you received from the customer.
  4. Select Fetch & save. Keep the page open for the next step.

Map IdP claims to Clerk fields

Clerk automatically maps the standard SAML claims (email, first name, and last name) to the User object. To review them, open the connection's SSO tab and find the Common attributes section under Attribute mapping.

To map a claim that has no standard Clerk field, store it in the user's publicMetadata. The approach depends on whether the connection also uses Directory Sync:

  • SSO only: In the IdP, prefix the claim name with public_metadata_. For example, mapping a phone number to public_metadata_phone_number stores it under phone_number in User.publicMetadata. Some IdPs, such as Microsoft Entra, send claims as URLs; map those as plain strings.
  • SSO with Directory Sync: Define a custom attribute so the mapping applies to both SSO and SCIM. Define it on the connection's Overview tab (in the Identity provider attributes section), then map it in the SSO tab (in the Custom attributes section of the Attribute mapping section). Refer to the guide on custom attribute mapping. While Directory Sync is enabled, SCIM is the only source for these values and overrides SSO.

Learn more about accessing user metadata from the API.

Enable the connection in Clerk

You have configured the SAML connection. Once enabled, all users with email addresses ending in the domain will be redirected to your identity provider at sign-up and sign-in.

Warning

If the SAML configuration in Clerk or your identity provider has an error, existing users with matching email domains will be unable to sign in once the connection is enabled. We recommend coordinating with your counterpart to test the connection at an off-peak time.

To make the connection available for your users to authenticate with:

  1. Navigate to the SSO connections page and select the connection.
  2. At the top of the page, toggle on Enable connection and select Save.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub