From 82566277d2bc930bf48bca3ffe6be94377c2e6ad Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 12:31:42 -0400 Subject: [PATCH 1/5] wip --- .../enterprise-connections/saml/okta.mdx | 132 ++++++++++++------ 1 file changed, 86 insertions(+), 46 deletions(-) diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index 9ba0577d72..ee76ab7f00 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -17,77 +17,117 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. } ]} > - - Use Okta Workforce to enable SSO via SAML for your Clerk app + - Create a SSO connection via Clerk Dashboard + - Give your customer instructions on how to connect Okta Workforce to your app + - Enable and test the SAML connection Enabling SAML with Okta Workforce allows your users to sign up and sign in to your Clerk application with their Okta account. -To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for the [Okta dashboard](https://www.okta.com/). +This process requires configuration changes in both the Clerk Dashboard, and in your customer's Okta settings. - ## Enable Okta as a SAML connection in Clerk + ## Create an Okta SAML connection in Clerk 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For specific domains or organizations**. 1. Under **SAML**, select **Okta Workforce**. 1. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. 1. Enter the **Name**. This will be displayed on the sign-in form. - 1. Select **Add connection**. You'll be redirected to the connection's configuration page. - 1. In the **Service Provider Configuration** section, save the **Single sign-on URL** and **Audience URI (SP Entity ID)** values somewhere secure. Keep this page open. + 1. Select **Add connection**. You'll be redirected to the connection's configuration page. Note that the connection is disabled by default. + 1. 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 application. - ## Create a new enterprise application in Okta + ## Configure SAML application - 1. Navigate to [Okta](https://www.okta.com/) and sign in. - 1. In the Okta dashboard, select **Admin** in the top right corner. - 1. In the navigation sidenav, select the **Applications** dropdown and select **Applications**. - 1. Select **Create App Integration**. - 1. In the **Create a new app integration** modal, select the **SAML 2.0** option and select the **Next** button. - 1. Once redirected to the **Create SAML Integration** page, complete the **General Settings** fields. An **App name** is required. - 1. Select **Next**. You'll be redirected to the **Configure SAML** page. - 1. Paste the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values that you saved from the Clerk Dashboard into their respective fields. + 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 application needs to be configured. At a high level, the process is: - ## Map Okta claims to Clerk attributes + - Create a new enterprise app in Okta. + - Add the **Single sign-on URL** and **Audience URI (SP Entity ID)** from Clerk to the Okta application's SAML configuration. + - Verify that the attribute mappings are correct. + - Obtain and share the application's metadata URL. - Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk. + You are welcome the use the below email template with detailed instructions. They contain the following + template strings that you should replace with your actual values: - | Clerk attribute | Okta claim | - | - | - | - | `mail` | `user.email` | - | `firstName` | `user.firstName` | - | `lastName` | `user.lastName` | + - \[YOUR\_APPLICATION\_NAME] + - \[YOUR\_CLERK\_SINGLE\_SIGN\_ON\_URL] + - \[YOUR\_CLERK\_AUDIENCE\_URI] - 1. In the Okta dashboard, find the **Attribute Statements (optional)** section. - 1. For the **Name** field, enter `mail`. - 1. For the **Value** field, choose `user.email` from the dropdown. - 1. Select the **Add Another** button to add another attribute. - 1. For the **Name** field, enter `firstName`. - 1. For the **Value** field, choose `user.firstName` from the dropdown. - 1. Select the **Add Another** button to add another attribute. - 1. For the **Name** field, enter `lastName`. - 1. For the **Value** field, choose `user.lastName` from the dropdown. - 1. Scroll to the bottom of the page and select the **Next** button to continue. - 1. You will be redirected to the **Feedback** page. Fill out the feedback however you would like and select the **Finish** button to complete the setup. + + Here are the instructions for setting up SAML SSO with Okta Workforce: - ## Assign selected user or group in Okta + **Step 1: Create a new enterprise app in Okta** - You need to assign your users/user groups to your enterprise application. For example, if you were part of the Clerk organization, you would have access to users and groups in the Clerk organization. In this case, you could assign one or more users or entire groups to the enterprise application you just created. + 1. Navigate to [Okta](https://www.okta.com/) and sign in. + 1. In the Okta dashboard, select **Admin** in the top right corner. + 1. In the navigation sidenav, select the **Applications** dropdown and select **Applications**. + 1. Select **Create App Integration**. + 1. In the **Create a new app integration** modal, select the **SAML 2.0** option and select the **Next** button. + 1. Once redirected to the **Create SAML Integration** page, complete the **General Settings** fields. An **App name** is required. + 1. Select **Next**. You'll be redirected to the **Configure SAML** page. + 1. Paste the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values that you saved from the Clerk Dashboard into their respective fields. - 1. In the Okta dashboard, select the **Assignments** tab. - 1. Select the **Assign** dropdown. You can either select **Assign to people** or **Assign to groups**. - 1. In the search field, enter the user or group of users that you want to assign to the enterprise application. - 1. Select the **Assign** button next to the user or group that you want to assign. - 1. Select the **Done** button to complete the assignment. + **Step 2: Verify correct configuration of attributes and claims** - ## Configure Okta as your Identity Provider + We expect your SAML responses to have the following specific attributes: - Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected. + Email address (required). This is the email address that your users will use to authenticate into your app: - 1. Under **Sign on methods**, copy the **Metadata URL**. - 1. Navigate back to the Clerk Dashboard and find the **Identity Provider configuration** section. - 1. Under the **Metadata configuration** option, paste the **Metadata URL**. - 1. Select the **Fetch & save** button to complete the setup. + - Claim name: `user.email` + - Value: `user.mail` + + | Clerk attribute | Okta claim | + | - | - | + | `mail` | `user.email` | + | `firstName` | `user.firstName` | + | `lastName` | `user.lastName` | + + These are the defaults, and probably won't need you to change them. However, many SAML configuration errors are due to incorrect attribute mappings, so it's worth double-checking. Here's how: + + 1. In the Okta dashboard, find the **Attribute Statements (optional)** section. + 1. For the **Name** field, enter `mail`. + 1. For the **Value** field, choose `user.email` from the dropdown. + 1. Select the **Add Another** button to add another attribute. + 1. For the **Name** field, enter `firstName`. + 1. For the **Value** field, choose `user.firstName` from the dropdown. + 1. Select the **Add Another** button to add another attribute. + 1. For the **Name** field, enter `lastName`. + 1. For the **Value** field, choose `user.lastName` from the dropdown. + 1. Scroll to the bottom of the page and select the **Next** button to continue. + 1. You will be redirected to the **Feedback** page. Fill out the feedback however you would like and select the **Finish** button to complete the setup. + + **Step 3: Assign selected user or group in Okta** + + You need to assign users or groups to your enterprise application before they can use it to sign in. + + 1. In the Okta dashboard, select the **Assignments** tab. + 1. Select the **Assign** dropdown. You can either select **Assign to people** or **Assign to groups**. + 1. In the search field, enter the user or group of users that you want to assign to the enterprise application. + 1. Select the **Assign** button next to the user or group that you want to assign. + 1. Select the **Done** button to complete the assignment. + + **Step 4: Share the application's metadata URL** + + Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected. Under **Sign on methods**, copy the **Metadata URL**. + + + ## 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**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. + 1. Select the SAML connection. + 1. In the **Identity Provider Configuration** section, under **Metadata configuration**, paste the **Metadata URL** that you received from the customer. + 1. Select **Fetch & save**. Keep the page open for the next step. ## Enable the connection in Clerk - + The SAML connection is ready to enable! Once enabled, all users with email addresses ending in the domain will be redirected to Okta at sign-up and sign-in. + + > [!WARNING] + > If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Okta, those users will be **unable to sign in** when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time. + > To make the connection available for users to authenticate with: + + 1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection. + 1. At the top of the page, toggle on **Enable connection** and select **Save**. From 63209fe1c65fc7dccefd22a44cd1cee33f385725 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 12:40:27 -0400 Subject: [PATCH 2/5] updates --- .../enterprise-connections/saml/okta.mdx | 44 ++++++++----------- 1 file changed, 18 insertions(+), 26 deletions(-) diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index ee76ab7f00..40aa92e4b7 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -32,26 +32,22 @@ This process requires configuration changes in both the Clerk Dashboard, and in 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. 1. Select **Add connection** and select **For specific domains or organizations**. 1. Under **SAML**, select **Okta Workforce**. - 1. Enter the **Domain**. This is the email domain of the users you want to allow to sign in to your application. Optionally, select an **Organization**. + 1. 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**. 1. Enter the **Name**. This will be displayed on the sign-in form. 1. Select **Add connection**. You'll be redirected to the connection's configuration page. Note that the connection is disabled by default. - 1. 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 application. + 1. 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 + ## Configure SAML app - 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 application needs to be configured. At a high level, the process is: + 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 new enterprise app in Okta. - - Add the **Single sign-on URL** and **Audience URI (SP Entity ID)** from Clerk to the Okta application's SAML configuration. + - Add the **Single sign-on URL** and **Audience URI (SP Entity ID)** from Clerk to the Okta app's SAML configuration. - Verify that the attribute mappings are correct. - - Obtain and share the application's metadata URL. + - Assign selected users or groups to the app. + - Obtain and share the app's metadata URL. - You are welcome the use the below email template with detailed instructions. They contain the following - template strings that you should replace with your actual values: - - - \[YOUR\_APPLICATION\_NAME] - - \[YOUR\_CLERK\_SINGLE\_SIGN\_ON\_URL] - - \[YOUR\_CLERK\_AUDIENCE\_URI] + You are welcome the use the below email template with detailed instructions. Here are the instructions for setting up SAML SSO with Okta Workforce: @@ -71,16 +67,12 @@ This process requires configuration changes in both the Clerk Dashboard, and in We expect your SAML responses to have the following specific attributes: - Email address (required). This is the email address that your users will use to authenticate into your app: - - - Claim name: `user.email` - - Value: `user.mail` - - | Clerk attribute | Okta claim | - | - | - | - | `mail` | `user.email` | - | `firstName` | `user.firstName` | - | `lastName` | `user.lastName` | + - Email address (required). This is the email address that your users will use to authenticate into your app: + - Claim name: `user.email` + - First name (optional): + - Claim name: `user.firstName` + - Last name (optional): + - Claim name: `user.lastName` These are the defaults, and probably won't need you to change them. However, many SAML configuration errors are due to incorrect attribute mappings, so it's worth double-checking. Here's how: @@ -98,17 +90,17 @@ This process requires configuration changes in both the Clerk Dashboard, and in **Step 3: Assign selected user or group in Okta** - You need to assign users or groups to your enterprise application before they can use it to sign in. + You need to assign users or groups to your enterprise app before they can use it to sign in. 1. In the Okta dashboard, select the **Assignments** tab. 1. Select the **Assign** dropdown. You can either select **Assign to people** or **Assign to groups**. - 1. In the search field, enter the user or group of users that you want to assign to the enterprise application. + 1. In the search field, enter the user or group of users that you want to assign to the enterprise app. 1. Select the **Assign** button next to the user or group that you want to assign. 1. Select the **Done** button to complete the assignment. - **Step 4: Share the application's metadata URL** + **Step 4: Share the app's metadata URL** - Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected. Under **Sign on methods**, copy the **Metadata URL**. + Once you have completed the setup in Okta, you will be redirected to the application's instances page with the **Sign On** tab selected. Under **Sign on methods**, copy the **Metadata URL**. ## Add the Metadata URL in the Clerk Dashboard From 7632a8b241008eac2712aa4c4ca23509859fbe13 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 12:41:49 -0400 Subject: [PATCH 3/5] wip --- docs/authentication/enterprise-connections/saml/okta.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index 40aa92e4b7..42011d1c5c 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -45,7 +45,7 @@ This process requires configuration changes in both the Clerk Dashboard, and in - Add the **Single sign-on URL** and **Audience URI (SP Entity ID)** from Clerk to the Okta app's SAML configuration. - Verify that the attribute mappings are correct. - Assign selected users or groups to the app. - - Obtain and share the app's metadata URL. + - Obtain and share the app's **Metadata URL**. You are welcome the use the below email template with detailed instructions. From 3dc2e17e999a97f163954a53ac6f7560f92a08ff Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 13:02:39 -0400 Subject: [PATCH 4/5] copy update --- docs/authentication/enterprise-connections/saml/okta.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index 42011d1c5c..fb2795283f 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -47,7 +47,7 @@ This process requires configuration changes in both the Clerk Dashboard, and in - Assign selected users or groups to the app. - Obtain and share the app's **Metadata URL**. - You are welcome the use the below email template with detailed instructions. + To get you started, you can use the following email template with detailed instructions: Here are the instructions for setting up SAML SSO with Okta Workforce: From e15fc86330713f79f405809ec93f327e8d654e2d Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 2 Apr 2025 13:40:31 -0400 Subject: [PATCH 5/5] update intro --- docs/authentication/enterprise-connections/saml/okta.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/authentication/enterprise-connections/saml/okta.mdx b/docs/authentication/enterprise-connections/saml/okta.mdx index fb2795283f..d18c0ae5e3 100644 --- a/docs/authentication/enterprise-connections/saml/okta.mdx +++ b/docs/authentication/enterprise-connections/saml/okta.mdx @@ -18,13 +18,11 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO. ]} > - Create a SSO connection via Clerk Dashboard - - Give your customer instructions on how to connect Okta Workforce to your app + - Give your customer instructions on how to connect Okta Workforce to your Clerk app - Enable and test the SAML connection -Enabling SAML with Okta Workforce allows your users to sign up and sign in to your Clerk application with their Okta account. - -This process requires configuration changes in both the Clerk Dashboard, and in your customer's Okta settings. +Enabling SAML with Okta Workforce allows your users to sign up and sign in to your Clerk application with their Okta account. It requires that a SAML connection is configured in both the Clerk Dashboard and Okta. This guide assumes that you have access to the Clerk app's settings in the Clerk Dashboard. The "customer" in this case is whoever has access to the Okta Workforce's app settings. ## Create an Okta SAML connection in Clerk