Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Add docs for third party OIDC providers #1769

Merged
merged 19 commits into from
Dec 11, 2024
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions docs/authentication/enterprise-connections/oidc/custom-provider.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
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.
---

<TutorialHero
beforeYouStart={[
{
title: "Add the Enhanced Authentication add-on to your Pro plan",
link: "/pricing",
icon: "plus-circle",
},
{
title: "Enable email address as an identifier for your app",
link: "/docs/authentication/configuration/sign-up-sign-in-options#identifiers",
icon: "key",
},
]}
>
- Add a custom OIDC provider to authenticate users with Enterprise SSO
</TutorialHero>

victoriaxyz marked this conversation as resolved.
Show resolved Hide resolved
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).

<Steps>
### 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 **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.

### 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they should already be there according to the last step in the previous step. so the copy before was correct

Copy link
Member Author

@Nikpolik Nikpolik Dec 10, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adjusted steps 1 and 2 to make this a bit more clear 8f754cb.

Also moved the discovery endpoint explanation to a Note so we can have all the required steps uninterrupted.

WDYT?

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

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You wouldn't get the client ID and client secret in the clerk dashboard. you would get those from your IdP and then paste them in the clerk dashboard. so i believe the copy before was correct

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)

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Attribute mapping allows you to map the IdP's claims with Clerk's user properties. 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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed this section to be more similar to it's previous form 07e1f1a

It's not required for most users so I think keeping it brief is better to avoid confusion 🙂


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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
1. In the connection's settings page in the Clerk Dashboard, under **Attribute Mapping**, for the **Email address verified* field:


- If the IdPs that provide the value, enter `email_verified`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- If the IdPs that provide the value, enter `email_verified`.
- If the IdP provides the value, enter `email_verified`.

- For IdPs that do not provide the value, enter `xms_edov`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's use the same syntax as the sentence before, and use a contraction!

Suggested change
- For IdPs that do not provide the value, enter `xms_edov`.
- If the IdP doesn't provide the value, enter `xms_edov`.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it's ok, I removed this part as it is to specific to Microsoft!


1. Set **Default value** to **True**.
1. Select **Save**.

> [!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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this step mentions that the user should set the default value to true whether the idp returns the claim or not. but then this callout says the user should only do it if the idp doesn't return the claim. which is the correct case so we can update accordingly?

Suggested change
> 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).
> 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).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, the way you've rewritten it makes a lot more sense!

>
> 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)

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:

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

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.
</Steps>
16 changes: 10 additions & 6 deletions docs/authentication/enterprise-connections/overview.mdx
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
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

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 `[email protected]` wouldn't be able to use a SAML connection with the `example.com` domain to authenticate.

Expand All @@ -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 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.

Expand All @@ -33,15 +37,15 @@ The following IdPs are supported: Google Workspace and Microsoft Entra ID. For _
- [Google](/docs/authentication/social-connections/google)
- [Microsoft](/docs/authentication/social-connections/microsoft)

### Automatic deprovisioning
#### Automatic deprovisioning

Clerk prevents users linked to deprovisioned accounts in the OpenID provider from accessing the app.

Within 10 minutes of a user being removed from the OpenID provider (e.g. [suspendeded](https://support.google.com/a/answer/33312?hl=en) or [deleted](https://support.google.com/a/answer/33314?hl=en) via Google Workspace, or [deleted](https://learn.microsoft.com/en-us/entra/fundamentals/how-to-create-delete-users#delete-a-user) via Microsoft Entra), Clerk will recognize that the user has been deprovisioned and will revoke that user's existing sessions.

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.

Expand Down
11 changes: 11 additions & 0 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -579,6 +579,17 @@
}
]
]
},
{
"title": "OIDC",
"items": [
[
{
"title": "Custom provider",
"href": "/docs/authentication/enterprise-connections/oidc/custom-provider"
}
]
]
}
]
]
Expand Down
Loading