From 764008496c8879c99dfd44605361d73795f0d396 Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Wed, 4 Dec 2024 15:11:09 +0200 Subject: [PATCH 01/16] feat: Add docs for third party OIDC providers --- .../oidc/custom-provider.mdx | 61 +++++++++++++++++++ .../enterprise-connections/overview.mdx | 10 ++- docs/manifest.json | 11 ++++ 3 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 docs/authentication/enterprise-connections/oidc/custom-provider.mdx diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx new file mode 100644 index 0000000000..a2f992ff7a --- /dev/null +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -0,0 +1,61 @@ +--- +title: Add a custom OIDC Provider as an Enterprise Connection +description: Learn how to integrate a custom OIDC provider with Clerk for Enterprise SSO. +--- + + + - Use a custom OIDC provider to authenticate users with Enterprise SSO + + + + ### Set up an Enterprise Connection in Clerk + + To create an Enterprise 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**. + 1. Under **Third party**, select **OIDC**. + 1. Add the **Name** of the connection. + 1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation). + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. + 1. Select **Add connection**. You will be redirected to the connection's configuration page. + + The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them. + + ### Configure your Identity Provider + + If needed, create a new application in your IdP. Then, copy the **Authorized redirect URLs** from the connection's configuration page and add them to your IdP's whitelisted URLs. + + ### Configure the connection + + Locate your application's Client ID, Client Secret, and discovery endpoint in your IdP's settings. Copy these values to the **Identity Provider Configuration** section on the connection's configuration page. + + Finally set up the minimum required scopes according to the provider's documentation. The most commonly used OIDC scopes are `openid`, `email`, and `profile`. + + ### Attribute mapping (optional) + + If your provider returns claims in a non-standard format, under **Attribute mapping**, configure the mapping to match your provider's claim format. + + > [!CAUTION] + > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. For providers that don't return this claim, you can set a default value of true - but ensure you fully trust the Identity Provider before doing so to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). + + ### Enable the connection for Clerk + + To make the connection available for your users to authenticate with: + + 1. In the Clerk Dashboard, 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. Toggle on **Enable connection** and select **Save**. + diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 7964cc946f..6ab327f360 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -24,7 +24,11 @@ To configure subdomains for a SAML connection: > [!NOTE] > To enable the **Allow subdomains** option, your SAML connection domain must be an [eTLD+1](https://developer.mozilla.org/en-US/docs/Glossary/eTLD). -## EASIE +## OIDC + +Clerk also supports Enterprise SSO via the OpenID Connect (OIDC) protocol, either through [EASIE](#easie) or by [integrating with any OIDC-compatible provider](/docs/authentication/enterprise-connections/oidc/custom-provider). + +### EASIE [EASIE](https://easie.dev) SSO is a way for applications to provide enterprise-grade SSO through a multi-tenant OpenID provider. It is designed to be an easier alternative to SAML SSO. @@ -33,7 +37,7 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _ - [Google](docs/authentication/social-connections/google) - [Microsoft](docs/authentication/social-connections/azure) -### Automatic deprovisioning +#### Automatic deprovisioning Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the app. @@ -41,7 +45,7 @@ Within 10 minutes of a user being removed from the OpenID provider (e.g. [suspen It is ultimately the app's responsibility to handle this unauthenticated state and display something appropriate to the user. For example, Next.js apps using [`auth.protect()`](docs/references/nextjs/auth#auth-protect) will automatically redirect the user to the sign-in page. -## SAML vs. EASIE +### SAML vs. EASIE The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), apps that require single-tenant IdPs should opt for SAML. diff --git a/docs/manifest.json b/docs/manifest.json index 89b2f99a8c..678b5255ab 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -579,6 +579,17 @@ } ] ] + }, + { + "title": "OIDC", + "items": [ + [ + { + "title": "Custom provider", + "href": "/docs/authentication/enterprise-connections/oidc/custom-provider" + } + ] + ] } ] ] From b340a992d3533500344a9b7fd91b15875dce828c Mon Sep 17 00:00:00 2001 From: victoria Date: Thu, 5 Dec 2024 18:01:49 -0500 Subject: [PATCH 02/16] Apply suggestions from code review --- .../oidc/custom-provider.mdx | 34 +++++++++++-------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index a2f992ff7a..53177ab57d 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -1,5 +1,5 @@ --- -title: Add a custom OIDC Provider as an Enterprise Connection +title: Add a custom OIDC Provider as an enterprise connection description: Learn how to integrate a custom OIDC provider with Clerk for Enterprise SSO. --- @@ -19,11 +19,12 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp > - Use a custom OIDC provider to authenticate users with Enterprise SSO +This guide explains how to use a custom OIDC provider to authenticate users via Enterprise SSO. +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 your Identity Provider (IdP). - ### Set up an Enterprise Connection in Clerk + ### Set up an enterprise connection in Clerk - To create an Enterprise 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**. @@ -35,27 +36,32 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them. - ### Configure your Identity Provider + ### Configure your Identity Provider (IdP) - If needed, create a new application in your IdP. Then, copy the **Authorized redirect URLs** from the connection's configuration page and add them to your IdP's whitelisted URLs. + 1. If necessary, create a new app in your IdP. + 1. In the connection's configuration page in the Clerk Dashboard, copy the **Authorized redirect URI**. + 1. Add the value to your IdP's whitelisted URLs. - ### Configure the connection + ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk - Locate your application's Client ID, Client Secret, and discovery endpoint in your IdP's settings. Copy these values to the **Identity Provider Configuration** section on the connection's configuration page. + 1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. + 1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields. + 1. Add the minimum required scopes based on the IdP's documentation. Common OIDC scopes include `openid`, `email`, and `profile`. + 1. Select **Save**. - Finally set up the minimum required scopes according to the provider's documentation. The most commonly used OIDC scopes are `openid`, `email`, and `profile`. + ### Configure attribute mapping (optional) - ### Attribute mapping (optional) - - If your provider returns claims in a non-standard format, under **Attribute mapping**, configure the mapping to match your provider's claim format. + If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. > [!CAUTION] - > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. For providers that don't return this claim, you can set a default value of true - but ensure you fully trust the Identity Provider before doing so to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). + > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). ### Enable the connection for Clerk To make the connection available for your users to authenticate with: - 1. In the Clerk Dashboard, 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. Toggle on **Enable connection** and select **Save**. + 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. + 1. Select the OIDC connection. + 1. Toggle on **Enable connection**. + 1. Select **Save**. From 42c1e833be24fa8c7c4be0e750b4461b56c7f0f1 Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Fri, 6 Dec 2024 13:43:14 +0200 Subject: [PATCH 03/16] Fix linter complaint --- .../enterprise-connections/oidc/custom-provider.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 53177ab57d..cff0714587 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -19,13 +19,14 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp > - Use a custom OIDC provider to authenticate users with Enterprise SSO + This guide explains how to use a custom OIDC provider to authenticate users via Enterprise SSO. 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 your Identity Provider (IdP). + ### Set up an enterprise 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**. 1. Under **Third party**, select **OIDC**. From 3f9119b0dba290131258971c38bc8d08c33a376d Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 6 Dec 2024 11:17:58 -0500 Subject: [PATCH 04/16] add test connection section; add suggestions for important clerk attributes --- .../oidc/custom-provider.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index cff0714587..2a8709aae6 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -32,7 +32,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Under **Third party**, select **OIDC**. 1. Add the **Name** of the connection. 1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation). - 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application. + 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. You will be redirected to the connection's configuration page. The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them. @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Configure attribute mapping (optional) - If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. + If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. Important Clerk user properties include `email`, `firstName`, and `lastName`. > [!CAUTION] > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). @@ -65,4 +65,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select the OIDC connection. 1. Toggle on **Enable connection**. 1. Select **Save**. + + ### Test your connection + + The simplest way to test your enterprise connection is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box. + + 1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page. + 1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble: + - **For development** – `https://your-domain.accounts.dev/sign-in` + - **For production** – `https://accounts.your-domain.com/sign-in` + 1. Sign in with your IdP account. From f8e51db3493e03c993af9edd8d6ba34212cb6050 Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 13:04:26 -0500 Subject: [PATCH 05/16] delevel heading for reading clarity --- docs/authentication/enterprise-connections/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 1d2563f889..a6854b3d07 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -9,7 +9,7 @@ With Enterprise SSO, users can sign in seamlessly using their Identity Provider' Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an IdP. The following IdPs are supported: [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta). However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. -### Allow subdomains +#### Allow subdomains Authenticating via SAML SSO requires the user's email address domain to match the exact domain the SAML connection has been configured with. By default, subdomains are not supported. For example, a user with the email address `john@sales.example.com` wouldn't be able to use a SAML connection with the `example.com` domain to authenticate. From d4effe8368ff7838ac4c520a5b206bb8f456868a Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 13:29:26 -0500 Subject: [PATCH 06/16] add sentence about different protocols --- docs/authentication/enterprise-connections/overview.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index a6854b3d07..4c90f5c5d9 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -1,9 +1,10 @@ --- -title: Enterprise SSO +title: Enterprise Single Sign-On (SSO) description: Clerk provides Enterprise SSO to authenticate users via federated Identity Providers such such as Azure AD, Okta, Google Workspace and more. --- -With Enterprise SSO, users can sign in seamlessly using their Identity Provider's (IdP) credentials and have their user data synchronized with Clerk. You can learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). +Enterprise Single Sign-On (SSO) allows users to sign in seamlessly using their Identity Provider (IdP) credentials (e.g.,Azure AD, Okta, or Google Workspace) and have their user data synchronized with Clerk. Clerk supports multiple protocols for implementing Enterprise SSO, including SAML and OIDC. Learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). + ## SAML From fcc2bcbdf2f7f7e00d8a2b0134eee1b57e26c47b Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 13:32:48 -0500 Subject: [PATCH 07/16] format --- docs/authentication/enterprise-connections/overview.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 6e1b7b7d72..6367c415b1 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -5,7 +5,6 @@ description: Clerk provides Enterprise SSO to authenticate users via federated I Enterprise Single Sign-On (SSO) allows users to sign in seamlessly using their Identity Provider (IdP) credentials (e.g.,Azure AD, Okta, or Google Workspace) and have their user data synchronized with Clerk. Clerk supports multiple protocols for implementing Enterprise SSO, including SAML and OIDC. Learn more about the process in the guides on [authentication flows](/docs/authentication/enterprise-connections/authentication-flows) and [account linking](/docs/authentication/enterprise-connections/account-linking). - ## SAML Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an IdP. The following IdPs are supported: [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta). However, you can also [integrate with any other IdP](/docs/authentication/enterprise-connections/saml/custom-provider) that supports the SAML protocol. From ca4b41f3c01b50c6b1c3fdcd9785af31214079bf Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 13:39:55 -0500 Subject: [PATCH 08/16] fix terms and add link to OIDC --- .../enterprise-connections/oidc/custom-provider.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 2a8709aae6..dc4a1482cd 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -1,5 +1,5 @@ --- -title: Add a custom OIDC Provider as an enterprise connection +title: Add a custom OpenID Connect (OIDC) Provider as an enterprise connection description: Learn how to integrate a custom OIDC provider with Clerk for Enterprise SSO. --- @@ -20,7 +20,7 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp - Use a custom OIDC provider to authenticate users with Enterprise SSO -This guide explains how to use a custom OIDC provider to authenticate users via Enterprise SSO. +This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works) provider to authenticate users via Enterprise SSO. 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 your Identity Provider (IdP). From 641d747b058cdef2d18fb2c1859f8e1ecf3fa30b Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 13:45:37 -0500 Subject: [PATCH 09/16] use IdP abbreviation --- .../enterprise-connections/oidc/custom-provider.mdx | 4 ++-- docs/authentication/enterprise-connections/overview.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index dc4a1482cd..858532c1c2 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -35,9 +35,9 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. You will be redirected to the connection's configuration page. - The next steps involve configuring both your Identity Provider (IdP) and Clerk. Keep both dashboards open as you'll need to reference them. + The next steps involve configuring both your IdP and Clerk. Keep both dashboards open as you'll need to reference them. - ### Configure your Identity Provider (IdP) + ### Configure your IdP 1. If necessary, create a new app in your IdP. 1. In the connection's configuration page in the Clerk Dashboard, copy the **Authorized redirect URI**. diff --git a/docs/authentication/enterprise-connections/overview.mdx b/docs/authentication/enterprise-connections/overview.mdx index 6367c415b1..5a8df7cb68 100644 --- a/docs/authentication/enterprise-connections/overview.mdx +++ b/docs/authentication/enterprise-connections/overview.mdx @@ -26,7 +26,7 @@ To configure subdomains for a SAML connection: ## OIDC -Clerk also supports Enterprise SSO via the OpenID Connect (OIDC) protocol, either through [EASIE](#easie) or by [integrating with any OIDC-compatible provider](/docs/authentication/enterprise-connections/oidc/custom-provider). +Clerk supports Enterprise SSO via the OpenID Connect (OIDC) protocol, either through [EASIE](#easie) or by [integrating with any OIDC-compatible provider](/docs/authentication/enterprise-connections/oidc/custom-provider). ### EASIE From a768763b683adb3b1a234c7fad56a67f08711752 Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 14:02:31 -0500 Subject: [PATCH 10/16] update instructions to allow additional identifiers --- .../enterprise-connections/oidc/custom-provider.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 858532c1c2..58dce06a47 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -57,6 +57,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!CAUTION] > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). + ### Allow additional identifiers (optional) + + User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles: + + 1. Navigate to the **Advanced** tab of the connection's configuration page. + 1. Enable **Allow additional identifiers**. + 1. Select **Save**. + ### Enable the connection for Clerk To make the connection available for your users to authenticate with: From 2277b8c5919867f59c19cde84a932030b8782af1 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 9 Dec 2024 15:45:02 -0500 Subject: [PATCH 11/16] Update docs/authentication/enterprise-connections/oidc/custom-provider.mdx --- .../enterprise-connections/oidc/custom-provider.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 58dce06a47..faa4aba0ca 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -69,10 +69,10 @@ To make the setup process easier, it's recommended to keep two browser tabs open To make the connection available for your users to authenticate with: - 1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. - 1. Select the OIDC connection. - 1. Toggle on **Enable connection**. - 1. Select **Save**. + To make the connection available for your 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**. ### Test your connection From 29d565c69262cec8690c0c2d27b947be0bfbd95e Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 15:48:19 -0500 Subject: [PATCH 12/16] update sections --- .../oidc/custom-provider.mdx | 37 +++++++++++++------ 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index faa4aba0ca..87781c0784 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -17,7 +17,7 @@ description: Learn how to integrate a custom OIDC provider with Clerk for Enterp }, ]} > - - Use a custom OIDC provider to authenticate users with Enterprise SSO + - Add a custom OIDC provider to authenticate users with Enterprise SSO This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works) provider to authenticate users via Enterprise SSO. @@ -29,33 +29,48 @@ To make the setup process easier, it's recommended to keep two browser tabs open 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**. - 1. Under **Third party**, select **OIDC**. + 1. Under **Third party**, select **OpenID Connect (OIDC)**. 1. Add the **Name** of the connection. 1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation). 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. 1. Select **Add connection**. You will be redirected to the connection's configuration page. - The next steps involve configuring both your IdP and Clerk. Keep both dashboards open as you'll need to reference them. - ### Configure your IdP 1. If necessary, create a new app in your IdP. - 1. In the connection's configuration page in the Clerk Dashboard, copy the **Authorized redirect URI**. + 1. In the Clerk Dashboard, navigate to the connection's settings page. + 1. Copy the **Authorized redirect URI**. 1. Add the value to your IdP's whitelisted URLs. ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk - 1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. - 1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields. - 1. Add the minimum required scopes based on the IdP's documentation. Common OIDC scopes include `openid`, `email`, and `profile`. + Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection. + + 1. In the Clerk Dashboard, navigate to the connection's settings page. + 1. Copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. + 1. In the connection's settings page in the Clerk Dashboard, under **Identity Provider Configuration**, paste the values in their respective fields. + 1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`. 1. Select **Save**. ### Configure attribute mapping (optional) - If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. Important Clerk user properties include `email`, `firstName`, and `lastName`. + Attribute mapping allows you to map the IdP's claims with Clerk's user properties such as the `email_verified`. OIDC Enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format. + + To enable attribute mapping: + + 1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page. + 1. In the **Attribute Mapping** section, under the **Email address verified** field: + + - If the IdPs that provide the value, enter `email_verified`. + - For IdPs that do not provide the value, enter `xms_edov`. + + 1. Set **Default value** to **True**. + 1. Select **Save**. - > [!CAUTION] - > OIDC Enterprise connections require the `email_verified` claim to verify email ownership. If the IdP doesn't return this claim, you can set its default value of `true`. However, ensure you fully trust the IdP to prevent exploits like [nOAuth](https://www.descope.com/blog/post/noauth). + > [!WARNING] + > If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). + > + > For Microsoft Azure Active Directory connections: Use the [`xms_edov` claim](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) to verify email ownership, as Microsoft might not return the standard `email_verified` claim. ### Allow additional identifiers (optional) From aa8da0c50768344685e3956818aa13a0072b48c4 Mon Sep 17 00:00:00 2001 From: vi Date: Mon, 9 Dec 2024 15:52:39 -0500 Subject: [PATCH 13/16] fix link --- .../enterprise-connections/oidc/custom-provider.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 87781c0784..6047a93772 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -70,7 +70,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open > [!WARNING] > If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). > - > For Microsoft Azure Active Directory connections: Use the [`xms_edov` claim](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) to verify email ownership, as Microsoft might not return the standard `email_verified` claim. + > For Microsoft Azure Active Directory connections: Use the [`xms_edov`](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) claim to verify email ownership, as Microsoft might not return the standard `email_verified` claim. ### Allow additional identifiers (optional) From 07e1f1a0f8db3b9c07d2bee928f3d460e8da362c Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Tue, 10 Dec 2024 10:57:29 +0200 Subject: [PATCH 14/16] Update attribute mapping section --- .../oidc/custom-provider.mdx | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index 6047a93772..e7fd2ca007 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -54,23 +54,12 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Configure attribute mapping (optional) - Attribute mapping allows you to map the IdP's claims with Clerk's user properties such as the `email_verified`. OIDC Enterprise connections require the [`email_verified` claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format. - - To enable attribute mapping: - - 1. In the Clerk Dashboard, navigate to the **Connection** tab of the connection's settings page. - 1. In the **Attribute Mapping** section, under the **Email address verified** field: - - - If the IdPs that provide the value, enter `email_verified`. - - For IdPs that do not provide the value, enter `xms_edov`. - - 1. Set **Default value** to **True**. - 1. Select **Save**. + Clerk expects the claims returned to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. > [!WARNING] - > If the IdP doesn't return this claim, you can either leave the **Email address verified** field blank or set the **Default value** to `True`. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). + > OIDC Enterprise connections require the [`email_verified`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) claim to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format. > - > For Microsoft Azure Active Directory connections: Use the [`xms_edov`](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization#using-the-xms_edov-optional-claim-to-determine-email-verification-status-and-migrate-users) claim to verify email ownership, as Microsoft might not return the standard `email_verified` claim. + > If the IdP doesn't return this claim, you can leave the **Email address verified** field blank and set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth). ### Allow additional identifiers (optional) @@ -84,8 +73,6 @@ To make the setup process easier, it's recommended to keep two browser tabs open To make the connection available for your users to authenticate with: - To make the connection available for your 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 8f754cb899860a704a7135fa42d30fabd05a7315 Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Tue, 10 Dec 2024 13:37:51 +0200 Subject: [PATCH 15/16] Adjust steps to be grouped by the settings page --- .../enterprise-connections/oidc/custom-provider.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index e7fd2ca007..aabd76dd7a 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -37,21 +37,21 @@ To make the setup process easier, it's recommended to keep two browser tabs open ### Configure your IdP - 1. If necessary, create a new app in your IdP. 1. In the Clerk Dashboard, navigate to the connection's settings page. 1. Copy the **Authorized redirect URI**. + 1. Navigate to your IdP's configuration page and if necessary create a new application. 1. Add the value to your IdP's whitelisted URLs. + 1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them. ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk - Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection. - - 1. In the Clerk Dashboard, navigate to the connection's settings page. - 1. Copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. - 1. In the connection's settings page in the Clerk Dashboard, under **Identity Provider Configuration**, paste the values in their respective fields. + 1. In the connection's settings page in the Clerk Dashboard, under **Identity Provider Configuration**, paste the values copied in the previous step, in their respective fields. 1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`. 1. Select **Save**. + > [!NOTE] + > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection. + ### Configure attribute mapping (optional) Clerk expects the claims returned to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. From 6f2718ea2d974739c622d08a492fe3cb246da3e8 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 10 Dec 2024 10:55:59 -0500 Subject: [PATCH 16/16] clean up instructions --- .../oidc/custom-provider.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx index aabd76dd7a..3ae5b0ce3f 100644 --- a/docs/authentication/enterprise-connections/oidc/custom-provider.mdx +++ b/docs/authentication/enterprise-connections/oidc/custom-provider.mdx @@ -33,28 +33,28 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Add the **Name** of the connection. 1. Add the **Key** of the provider. This is the provider's unique identifier (cannot be changed after creation). 1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app. - 1. Select **Add connection**. You will be redirected to the connection's configuration page. + 1. Select **Add connection**. You will be redirected to the connection's configuration page. Keep this page open. ### Configure your IdP - 1. In the Clerk Dashboard, navigate to the connection's settings page. - 1. Copy the **Authorized redirect URI**. - 1. Navigate to your IdP's configuration page and if necessary create a new application. + 1. If necessary, create a new application in your IdP. + 1. In the connection's configuration page of the Clerk Dashboard, copy the **Authorized redirect URI**. 1. Add the value to your IdP's whitelisted URLs. 1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them. ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk - 1. In the connection's settings page in the Clerk Dashboard, under **Identity Provider Configuration**, paste the values copied in the previous step, in their respective fields. + 1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**. + 1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields. 1. Under **Scopes**, add the minimum required scopes based on the IdP's documentation if needed. Common OIDC scopes include `openid`, `email`, and `profile`. 1. Select **Save**. > [!NOTE] - > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, select **Use Manual Configuration** in the **Identity Provider Configuration** section to manually configure the connection. + > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, in the connection's configuration page in the Clerk Dashboard, find the **Identity Provider Configuration** section and select **Use Manual Configuration** to manually configure the connection. ### Configure attribute mapping (optional) - Clerk expects the claims returned to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. + Clerk expects the claims returned by your IdP to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes. > [!WARNING] > OIDC Enterprise connections require the [`email_verified`](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:~:text=Section%C2%A05.7.-,email_verified,-boolean) claim to verify email ownership. However, some IdPs, such as Microsoft Azure Active Directory, might not return this claim or use a non-standard format. @@ -65,7 +65,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles: - 1. Navigate to the **Advanced** tab of the connection's configuration page. + 1. In the connection's configuration page of the Clerk Dashboard, navigate to the **Advanced** tab. 1. Enable **Allow additional identifiers**. 1. Select **Save**.