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..4b32b349bb --- /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 third-party 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" + } + ] + ] } ] ]