Skip to content

Commit

Permalink
(chore) steps component now accepts h2s (#1801)
Browse files Browse the repository at this point in the history
  • Loading branch information
alexisintech authored and royanger committed Dec 16, 2024
1 parent 276b09f commit 45a579e
Show file tree
Hide file tree
Showing 63 changed files with 371 additions and 393 deletions.
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -439,18 +439,18 @@ console.log('ignored')
### `<Steps />`

The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h3` headings.
The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h2` and `h3` headings.

```mdx
<Steps>

### Step 1
## Step 1

Do these actions to complete Step 1.

### Another step
## Another step

#### A heading inside a step
### A heading inside a step

Do these actions to complete Step 2.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.n
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
## 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**.
Expand All @@ -35,14 +35,14 @@ 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. Keep this page open.

### Configure your IdP
## Configure your IdP

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
## 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.
Expand All @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
> [!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, 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)
## Configure attribute mapping (optional)

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.

Expand All @@ -61,22 +61,22 @@ To make the setup process easier, it's recommended to keep two browser tabs open
>
> 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)
## 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. In the connection's configuration page of the Clerk Dashboard, navigate to the **Advanced** tab.
1. Enable **Allow additional identifiers**.
1. Select **Save**.

### Enable the connection for Clerk
## Enable the connection for Clerk

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

Expand Down
16 changes: 8 additions & 8 deletions docs/authentication/enterprise-connections/saml/azure.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Enabling single sign-on (SSO) with **Microsoft Azure Entra ID** (formerly [Activ
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 [Microsoft Azure portal](https://portal.azure.com).

<Steps>
### Set up an enterprise connection in Clerk
## Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

Expand All @@ -38,7 +38,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
1. Find the **Service Provider Configuration** section.
1. Save the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. Leave this page open.

### Create a new enterprise app in Microsoft
## Create a new enterprise app in Microsoft

To create a new enterprise app in Microsoft:

Expand All @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
- Ensure the option **Integrate any other application you don't find in the gallery (Non-gallery)** is selected.
- Select **Create**.

### Assign selected user or group in Microsoft
## Assign selected user or group in Microsoft

Now that you have created the enterprise app, you need to assign users or groups to the app. For example, if you were part of the Clerk organization, you would have access to users and groups within the Clerk organization. In this case, you could assign individual users or entire groups to the enterprise app you just created.

Expand All @@ -63,14 +63,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open
1. Select **Select** at the bottom of the page. You'll be redirected to the **Add Assignment** page.
1. Select **Assign** at the bottom of the page.

### Configure SSO in Microsoft
## Configure SSO in Microsoft

After assigning the user or group to the enterprise app, you need to configure the SSO settings to enable SAML SSO.

1. In the navigation sidebar, open the **Manage** dropdown and select **Single sign-on**.
1. In the **Select a single sign-on method** section, select **SAML**.

### Configure your service provider
## Configure your service provider

To configure Clerk as your service provider, add these two fields to your IdP's application:

Expand All @@ -84,7 +84,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
1. Paste the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values you saved earlier into their respective fields. These values will be saved automatically.
1. Select **Save** at the top of the panel. Close the panel.

### Configure your identity provider
## Configure your identity provider

To configure Microsoft Entra ID as your identity provider, add the following fields to your app:

Expand All @@ -93,7 +93,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
1. Navigate back to the **Clerk Dashboard**. In the **Identity Provider Configuration** section, under **App Federation Metadata Url**, paste the **App Federation Metadata URL**.
1. Select **Fetch & save**.

### Map Microsoft claims to Clerk attributes
## Map Microsoft claims to Clerk attributes

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.

Expand All @@ -112,7 +112,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
1. Next to **Source attribute**, search for and select `user.userprincipalname` in the dropdown.
1. Select **Save** at the top of the page.

### Enable the connection for Clerk
## Enable the connection for Clerk

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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,8 @@ description: Learn how to integrate an Identity Provider with Clerk using SAML S

Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [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) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk.

## Tutorial

<Steps>
### Set up an enterprise connection in Clerk
## Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

Expand All @@ -36,23 +34,23 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth
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.

### Create a new enterprise application in your IdP
## Create a new enterprise application in your IdP

Create a new application in your IdP. In the next steps, you'll configure your IdP with the settings provided by your Service Provider (Clerk), and configure Clerk with the settings provided by your IdP. Keep both the IdP and Clerk Dashboard open.

### Configure your Identity Provider
## Configure your Identity Provider

There are two options for configuring your IdP:

- [**Metadata configuration**](#metadata-configuration) - This is where you can download your IdP's metadata file or input the metadata URL that you got from your IdP. This is the recommended way to configure your IdP, but not all IdPs support this method.
- [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP.

#### Metadata configuration
### Metadata configuration

1. In your IdP dashboard, find where you can download the metadata file or copy the metadata URL.
1. In the Clerk Dashboard on the connection's configuration page, under **Identity Provider Configuration**,select **Add via metadata**. Input the metadata URL or upload the metadata file that you got from your IdP.

#### Custom configuration
### Custom configuration

If you choose to manually input the configuration settings for your IdP, you will need to fill these three fields in the Clerk Dashboard:

Expand Down
22 changes: 10 additions & 12 deletions docs/authentication/enterprise-connections/saml/google.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,8 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
- Use Google Workspace to enable single sign-on (SSO) via SAML for your Clerk application.
</TutorialHero>

## Tutorial

<Steps>
### Set up an enterprise connection in Clerk
## Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

Expand All @@ -34,7 +32,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
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'll be redirected to the connection's configuration page.

### Create a new enterprise application in Google
## Create a new enterprise application in Google

To create a new enterprise application in Google:

Expand All @@ -45,20 +43,20 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
1. In the **App details** section, an **App name** is required.
1. Select the **Continue** button.

### Configure your identity provider
## Configure your identity provider

There are two options for configuring your IdP:

- [**Metadata configuration**](#metadata-configuration) - This is where you can input the URL to your IdP's metadata file. This is the recommended way to configure your IdP.
- [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP.

#### Metadata configuration
### Metadata configuration

1. In the Google Admin Console, under **Option 1: Download IdP Metadata**, select the **Download Metadata** button.
1. Navigate back to the Clerk Dashboard and in the **Identity Provider Configuration** section, select the **Upload file** button.
1. Upload the metadata file you downloaded from Google.

#### Custom configuration
### Custom configuration

If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings:

Expand All @@ -71,7 +69,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
1. Fill in the **SSO URL**, **Entity ID**, and upload the **Certificate**. Don't forget to select **Save**.
1. In the Google Admin Console, select the **Continue** button.

### Configure your service provider
## Configure your service provider

To configure your service provider (Clerk), you will need to add these two fields to your IdP's application:

Expand All @@ -85,7 +83,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
1. In the Google Admin Console, paste these values into their respective fields.
1. Under the **Name ID** section, select the dropdown for **Name ID format** and select **Email**.

### Map Google claims to Clerk attributes
## Map Google claims to Clerk attributes

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.

Expand All @@ -103,7 +101,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
1. Enter `mail` in the field.
1. If you have additional claims that you would like to map to Clerk, you can do so by following the steps in the [Map other claims](#map-other-claims-optional) section. Otherwise, select the **Finish** button.

#### Map other claims (optional)
### Map other claims (optional)

In Clerk, the [`User`](/docs/users/overview#user-object) object has a `publicMetadata` property that you can use to store additional information about your users.

Expand All @@ -121,15 +119,15 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.

Learn more about [how to access the metadata from our APIs](/docs/users/metadata).

### Enable the connection on Google
## Enable the connection on Google

Once the configuration is complete, you will be redirected to the app details page.

1. In the **User access** section, select **View details**.
1. In the **Service status** section, select **ON for everyone**.
1. Select the **Save** button.

### Enable the connection for Clerk
## Enable the connection for Clerk

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

Expand Down
16 changes: 7 additions & 9 deletions docs/authentication/enterprise-connections/saml/okta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,8 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
- Use Okta Workforce to enable single sign-on (SSO) via SAML for your Clerk application.
</TutorialHero>

## Tutorial

<Steps>
### Set up an enterprise connection in Clerk
## Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

Expand All @@ -37,7 +35,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
1. Save the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
1. Leave this page open.

### Create a new enterprise application in Okta
## Create a new enterprise application in Okta

To create a new enterprise application in Okta:

Expand All @@ -49,7 +47,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
1. Once redirected to the **Create SAML Integration** page, fill in the **General Settings** fields. An **App name** is required.
1. Select the **Next** button to continue.

### Configure your service provider
## Configure your service provider

Once you have moved forward from the **General Settings** instructions, you will be presented with the **Configure SAML** page.

Expand All @@ -62,7 +60,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.

1. Paste the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values that you saved earlier into their respective fields.

### Map Okta claims to Clerk attributes
## Map Okta claims to Clerk attributes

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.

Expand All @@ -84,7 +82,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
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.

### Assign selected user or group in Okta
## Assign selected user or group 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.

Expand All @@ -94,7 +92,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
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.

### Configure your identity provider
## Configure your identity provider

Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected.

Expand All @@ -103,7 +101,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
1. Under the **Metadata configuration** option, paste the **Metadata URL**.
1. Select the **Fetch & save** button to complete the setup.

### Enable the connection for Clerk
## Enable the connection for Clerk

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

Expand Down
Loading

0 comments on commit 45a579e

Please sign in to comment.