diff --git a/docs/authentication/configuration/sign-up-sign-in-options.mdx b/docs/authentication/configuration/sign-up-sign-in-options.mdx index 12c8d08fcd..dc580868e2 100644 --- a/docs/authentication/configuration/sign-up-sign-in-options.mdx +++ b/docs/authentication/configuration/sign-up-sign-in-options.mdx @@ -144,7 +144,7 @@ To configure verification methods: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) and select your application. 1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. -1. Select the settings cog icon next to the identifier, such as **Email address** or **Phone number**, to open the configuration settings. +1. Select the settings icon next to the identifier, such as **Email address** or **Phone number**, to open the configuration settings. 1. Under the **Verification methods** section, toggle on the verification methods you would like to enable. 1. Select **Continue** to save your changes. diff --git a/docs/authentication/saml/account-linking.mdx b/docs/authentication/saml/account-linking.mdx index 694a000115..69bbce1b04 100644 --- a/docs/authentication/saml/account-linking.mdx +++ b/docs/authentication/saml/account-linking.mdx @@ -28,7 +28,7 @@ To allow unverified email addresses for your instance: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) 1. In the navigation sidebar, select **Email, Phone, Username**. -1. Next to **Email address**, select the settings cog icon and uncheck the **Verify at sign-up** toggle. +1. Next to **Email address**, select the settings icon and uncheck the **Verify at sign-up** toggle. When a user signs into your app using a SAML provider, Clerk links the SAML account to the existing account by also verifying the existing email address and signs the user in. This even applies to password-protected accounts, as the SAML sign-in process automatically bypasses password verification. diff --git a/docs/authentication/saml/authentication-flows.mdx b/docs/authentication/saml/authentication-flows.mdx index 754e0d1be4..78a6d58927 100644 --- a/docs/authentication/saml/authentication-flows.mdx +++ b/docs/authentication/saml/authentication-flows.mdx @@ -3,63 +3,61 @@ title: SAML SSO authentication flows description: Learn about the SAML SSO authentication flows. --- -The SAML protocol supports two different methods in order to start an SSO flow: SP-initiated and IdP-initiated. This guide will explore the differences between the two. +The SAML protocol supports two methods to start an SSO flow: Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated). -## SP-initiated flow (recommended) +## Service Provider-initiated flow (recommended) In an SP-initiated flow: -- The user starts the authentication flow from your application (SP), by providing the email address. -- The user is redirected to the SAML provider (IdP) where they must authenticate themselves. +- The user starts the authentication process from your application (Service Provider, or SP), by providing their email address. +- The user is redirected to the SAML provider (Identity Provider, or IdP) where they must authenticate. - After successful authentication, the user is redirected back to your application, gaining access to their account. -## IdP-initiated flow +## Identity Provider-initiated flow In an IdP-initiated flow: -- The user starts the authentication flow from the SAML provider (IdP), by selecting which application (SP) they would like to access. +- The user starts the authentication flow from the SAML provider (IdP) by selecting which application (SP) they want to access. - The user is redirected to the application of their choice, gaining access to their account. > [!NOTE] -> IdP-Initiated flow carries [a security risk](#risks-of-id-p-initiated-flow). We recommend using a SP-Initiated flow whenever possible. +> IdP-Initiated flow carries a [security risk](#risks-of-id-p-initiated-flow). It is recommended to use an SP-Initiated flow whenever possible. -To allow IdP-initiated flows for your SAML Connection: +To allow IdP-initiated flows for your SAML connection: -1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). -1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. -1. Select the SAML connection you want to enable IdP-initiated flow for. +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. Select your **Identity Provider**. Complete the fields and select **Add connection**. You'll be redirected to the SAML connection's configuration page. 1. Select the **Advanced** tab. -1. Toggle on **Allow IdP-Initiated flow**. +1. In **Advanced Settings**, enable **Allow IdP-Initiated flow**. A modal will open. Select **Enable** to confirm. +1. Select **Save**. ### Risks of IdP-initiated flow -While IdP-initiated flows may offer a layer of convenience for your users, it is also potentially susceptible to MITM (meddler-in-the-middle) attacks in which a bad actor may be able to hijack the IdP response and uses it to gain access to a compromised account. +While IdP-initiated flows might offer convenience, they are also susceptible to security risks, such as [meddler-in-the-middle (MITM) attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). A bad actor might hijack the IdP response to gain access to a compromised account. -By enabling an IdP-Initiated flow, it's possible for Clerk to receive unsolicited authentication requests and neither the Service Provider nor the Identity Provider will be able to verify that the flow was initiated by the specified user. +When enabling an IdP-initiated flow, it is possible for Clerk to receive unsolicited authentication requests, which neither the SP nor IdP can verify were initiated by the specified user. Additionally, a bad actor could intercept the IdP response and replace it, performing a CSRF attack to sign in as the attacker. -A bad actor could also can intercept the IdP response and replace it with another to make the target user sign in as the attacker, performing a Login CSRF attack. +### Clerk's security measures -To this end, Clerk recommends using the [SP-initiated flow](#sp-initiated-flow-recommended). - -That said, in order to protect and offer the best possible security for your application and users, Clerk mitigates these risks by implementing several security measures: +To mitigate the risks associated with IdP-initiated flows, Clerk implements several security measures: #### Unsolicited `InResponseTo` attribute -In accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf), Clerk ensures that an unsolicited response does not contain an `InResponseTo` attribute. - -This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow. +Clerk ensures that unsolicited responses don't contain an `InResponseTo` attribute, in accordance with the [SAML 2.0 profiles specification](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf). This prevents bad actors from stealing a response used in an SP-initiated flow and using it in an IdP-initiated flow. #### Replay detection -Clerk prevents responses from being re-used by consuming them and remembering which have already been used. -This prevents bad actors from stealing and reusing a response to gain access to a user's account. +Clerk consumes and remembers each response to prevent re-use. This ensures that bad actors cannot steal and reuse a response to gain access to a user's account. #### Multi-factor authentication -Multi-factor authentication (MFA) is a security mechanism that requires users to provide two or more forms of verification before gaining access to their account. By enforcing two different types of verifications, you can drastically improve your user's security. - -Clerk supports MFA for a SAML IdP-initiated flow. +Clerk supports [multi-factor authentication (MFA)](/docs/authentication/configuration/sign-up-sign-in-options#multi-factor-authentication) for SAML IdP-initiated flows. MFA requires users to provide two or more forms of verification, which significantly enhances security by reducing the risk of unauthorized access. #### Use small validation periods -Each SAML response defines when they were issued and when they will expire. As an IdP-initiated flow is expected to be completed within a time frame of seconds, you must ensure that these validation periods are as small as possible to prevent attacks. Common providers, such as Azure, Google, and Okta, handle this. However, if you are using a custom IdP, you must ensure that the validation periods are set correctly. +Each SAML response contains a timestamp indicating when it was issued and when it will expire. Since IdP-initiated flows are expected to be completed within seconds, validation periods must be as small as possible to prevent attacks. Common IdP providers such as Azure, Google, and Okta handle this by default. However, if you are using a custom IdP, you must ensure that the validation periods are set correctly. + +### Conclusion + +For the best security practices, Clerk recommends using the SP-initiated flow wherever possible. If you decide to enable IdP-initiated flows, ensure that proper security measures—such as MFA, replay detection, and short validation periods—are in place to mitigate the associated risks. diff --git a/docs/authentication/saml/custom-provider.mdx b/docs/authentication/saml/custom-provider.mdx index ee3a124f3e..cc64295782 100644 --- a/docs/authentication/saml/custom-provider.mdx +++ b/docs/authentication/saml/custom-provider.mdx @@ -81,7 +81,7 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth 1. In your IdP dashboard, paste the values in the appropriate fields. > [!TIP] - > If you closed your connection's configuration page in the Clerk Dashboard, you can find it by navigating to the [SSO Connections](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and selecting the settings cog icon next to the connection you want to configure. + > If you closed your connection's configuration page in the Clerk Dashboard, you can find it by navigating to the [SSO Connections](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and selecting the settings icon next to the connection you want to configure. ### Map your IdP's claims to Clerk fields diff --git a/docs/authentication/saml/overview.mdx b/docs/authentication/saml/overview.mdx index a46ada290c..84d9ab5ead 100644 --- a/docs/authentication/saml/overview.mdx +++ b/docs/authentication/saml/overview.mdx @@ -40,7 +40,7 @@ The users will not be deleted, so your application will not break. However, they ### Does Clerk support IdP-initiated SSO? -Yes, Clerk supports both SP-initiated and IdP-initiated SSO flows. +Yes, Clerk supports both Service Provider-initiated (SP-initiated) and Identity Provider-initiated (IdP-initiated) SSO flows. [Learn more](/docs/authentication/saml/authentication-flows). ### How much does it cost? diff --git a/docs/authentication/social-connections/account-linking.mdx b/docs/authentication/social-connections/account-linking.mdx index 0768821d7c..d618b8d6b3 100644 --- a/docs/authentication/social-connections/account-linking.mdx +++ b/docs/authentication/social-connections/account-linking.mdx @@ -25,7 +25,7 @@ In this scenario, when a user with a verified email address at Clerk signs in us For instances that allow account creation without email verification at sign-up, there is a possibility that an account may be created using an unverified email address, either through OAuth or other methods like username/password. -To allow unverified email addresses for your instance, navigate to the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page in the Clerk Dashboard. Click on the settings cog icon next to "Email address" and uncheck the "Verify at sign-up" toggle. +To allow unverified email addresses for your instance, navigate to the [Email, Phone, Username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page in the Clerk Dashboard. Click on the settings icon next to "Email address" and uncheck the "Verify at sign-up" toggle. ![Verify at sign-up toggle in the Clerk Dashboard](/docs/images/authentication/account-linking-verify-at-sign-up.webp) diff --git a/docs/authentication/social-connections/atlassian.mdx b/docs/authentication/social-connections/atlassian.mdx index 035c04c5c7..4817c83d1f 100644 --- a/docs/authentication/social-connections/atlassian.mdx +++ b/docs/authentication/social-connections/atlassian.mdx @@ -7,7 +7,7 @@ How to set up social connection with Atlassian ## Overview -Adding social connection with Atlassian to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Atlassian to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -49,7 +49,7 @@ This is done by navigating to the Authorization section and clicking on Add. ![Atlassian OAuth 2.0 Authorization page](/docs/images/authentication-providers/atlassian/3d60a54bb48c03257afbf769f1f50cf45f18871c-3456x1730.png) -In this section, you will need to paste the Authorized redirect URI that Clerk has provided for you. +In this section, you will need to paste the Redirect URI that Clerk has provided for you. ![Atlassian OAuth 2.0 App callback URL settings](/docs/images/authentication-providers/atlassian/a6dc9bd0902359cad9c94de1bdcbd4c9112bff1d-3456x1730.png) diff --git a/docs/authentication/social-connections/bitbucket.mdx b/docs/authentication/social-connections/bitbucket.mdx index 19b79664d2..5b364d165e 100644 --- a/docs/authentication/social-connections/bitbucket.mdx +++ b/docs/authentication/social-connections/bitbucket.mdx @@ -7,7 +7,7 @@ How to set up social connection with Bitbucket ## Overview -Adding social connection with Bitbucket to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Bitbucket to your app with Clerk is done in a few steps - you will need to populate the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -37,7 +37,7 @@ From there, click on the desired existing workspace or create a new one, then na You will need to create a consumer if you don't have one already. -The first important setting for the connection to work is the **Callback URL**. Paste the **Authorized redirect URI** from your Clerk Bitbucket settings in this field: +The first important setting for the connection to work is the **Callback URL**. Paste the **Redirect URI** from your Clerk Bitbucket settings in this field: ![OAuth consumer creation](/docs/images/authentication-providers/bitbucket/3c3f5f49188f740839a9e0f348ffe4d34a5300c3-3360x1782.png) diff --git a/docs/authentication/social-connections/box.mdx b/docs/authentication/social-connections/box.mdx index 228342cfd5..c5d0893370 100644 --- a/docs/authentication/social-connections/box.mdx +++ b/docs/authentication/social-connections/box.mdx @@ -7,7 +7,7 @@ How to set up social connection with Box ## Overview -Adding social connection with Box to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Box to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. diff --git a/docs/authentication/social-connections/coinbase.mdx b/docs/authentication/social-connections/coinbase.mdx index eb01597223..240f472cb6 100644 --- a/docs/authentication/social-connections/coinbase.mdx +++ b/docs/authentication/social-connections/coinbase.mdx @@ -7,7 +7,7 @@ How to set up social connection with Coinbase ## Overview -Adding social connection with Coinbase to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Coinbase to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -29,7 +29,7 @@ You need to set all the required fields and the corresponding **Permitted Redire ![Creating application](/docs/images/authentication-providers/coinbase/creating-application.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Coinbase**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Coinbase**. Toggle on **Use custom credentials** and copy **Redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. ![Copying the Client ID and Client Secret from the Box dashboard](/docs/images/authentication-providers/coinbase/copying-values-from-box-dashboard.jpg) diff --git a/docs/authentication/social-connections/discord.mdx b/docs/authentication/social-connections/discord.mdx index 4fe4f13d70..f7eb5d2366 100644 --- a/docs/authentication/social-connections/discord.mdx +++ b/docs/authentication/social-connections/discord.mdx @@ -44,7 +44,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Discord**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized redirect URI** somewhere secure. Keep the modal and page open. + 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. ### Create a Discord Developer app @@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the top-right, select **New Application**. 1. Complete the required fields and select **Create**. You'll be redirected to the **General Information** page. 1. In the sidebar, select **OAuth2**. - 1. Under **Redirects**, select **Add Redirect**. Paste the **Authorized Redirect URI** you saved from the Clerk Dashboard. + 1. Under **Redirects**, select **Add Redirect**. Paste the **Redirect URI** you saved from the Clerk Dashboard. 1. Select **Save Changes**. You may need to tap anywhere on the screen for the button to show. Keep this page open. ### Set the Client ID and Client Secret in your Clerk Dashboard diff --git a/docs/authentication/social-connections/dropbox.mdx b/docs/authentication/social-connections/dropbox.mdx index e2eb20d87e..1de4dd325f 100644 --- a/docs/authentication/social-connections/dropbox.mdx +++ b/docs/authentication/social-connections/dropbox.mdx @@ -7,7 +7,7 @@ How to set up social connection with Dropbox ## Overview -Adding social connection with Dropbox to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Dropbox to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -29,7 +29,7 @@ First, you need to register a new OAuth Dropbox app at the [Dropbox App Console] First you need to choose the API type, the App's type of access and to set a name for your new application. You also need to add the **OAuth Redirect URLs.** -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Dropbox**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste the value into the **OAuth Redirect URIs** input and click create. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Dropbox**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URIs** input and click create. Once all the above are complete, copy the **Client ID** and **Client Secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/facebook.mdx b/docs/authentication/social-connections/facebook.mdx index 712951a2ed..ee49fd4692 100644 --- a/docs/authentication/social-connections/facebook.mdx +++ b/docs/authentication/social-connections/facebook.mdx @@ -7,7 +7,7 @@ How to set up social connection with Facebook ## Overview -Adding social connection with Facebook to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Facebook to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -39,6 +39,6 @@ Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=u ![Adding the valid OAuth Redirect URI](/docs/images/authentication-providers/facebook/c0be80ce8fed2b4d14d04fcbf56318b80295093d-1467x989.png) -Before you close the modal, copy the **Authorized redirect URI**. Go back to the Facebook dashboard, open the **Facebook Login** menu (sidebar) and click **Settings**. Paste the URI you copied before into the **Valid OAuth Redirect URIs** field. Hit **Save Changes**. +Before you close the modal, copy the **Redirect URI**. Go back to the Facebook dashboard, open the **Facebook Login** menu (sidebar) and click **Settings**. Paste the URI you copied before into the **Valid OAuth Redirect URIs** field. Hit **Save Changes**. Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with Facebook is now configured for your instance. diff --git a/docs/authentication/social-connections/github.mdx b/docs/authentication/social-connections/github.mdx index d9fd793902..05144f92f3 100644 --- a/docs/authentication/social-connections/github.mdx +++ b/docs/authentication/social-connections/github.mdx @@ -1,36 +1,78 @@ --- title: Add GitHub as a social connection -description: Learn how to set up social connection with GitHub. +description: Learn how to allow users to sign up and sign in to your Clerk app with their GitHub account using OAuth. + --- -How to set up social connection with GitHub + + - Use GitHub to authenticate users with OAuth + + +Enabling OAuth with [GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) allows your users to sign up and sign in to your Clerk app with their GitHub account. + +## Configure for your development instance + +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. + +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 choose **For all users**. +1. In the **Choose provider** dropdown, select **GitHub**. +1. Select **Add connection**. + +## Configure for your production instance -## Overview +For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your GitHub account. -Adding social connection with GitHub to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [GitHub Developers](https://GitHub.com/developers/applications) page. -To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. + + ### Enable GitHub as a social connection in Clerk -For production instances, you will need to generate your own Client ID and Client secret using your GitHub account. + 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 choose **For all users**. + 1. In the **Choose provider** dropdown, select **GitHub**. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. + 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. -> [!NOTE] -> The purpose of this guide is to help you create a GitHub account and a GitHub OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth). + ### Create a GitHub app -## Before you start + 1. On a separate page, go to [GitHub's Developer Settings](https://github.com/settings/apps). + 1. In the sidebar, select **OAuth Apps**, then select [**New OAuth app**](https://github.com/settings/applications/new). You'll be redirected to the **Register a new OAuth app** form. + 1. Enter your **Application name** and **Homepage URL**. + 1. In **Authorization callback URL**, paste the **Redirect URI** you saved from the Clerk Dashboard. + 1. Select **Register application**. You'll be redirected to your GitHub app's **General** page. -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). -- You need to have a GitHub account. To create one, [click here](https://github.com/signup). + ### Set the Client ID and Client Secret in your Clerk Dashboard -## Configuring GitHub social connection + 1. In the GitHub app's **General** page, select **Generate a new client secret**. Save your **Client ID** and **Client secret** somewhere secure. + 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Select **Add connection**. -First, you need to register a new OAuth GitHub app. Follow the official GitHub instructions on [how to create an OAuth app](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app). + > [!NOTE] + > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the GitHub connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. -![Registering an OAuth GitHub app](/docs/images/authentication-providers/github/ff83ad81ca491cf17e5a755376fae9c88148ce7c-1395x799.png) + ### Test your OAuth -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitHub**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Go back to the GitHub panel, paste the value into the **Authorization callback URL** field and complete the registration. + The simplest way to test your OAuth 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. -Once registration is complete, you'll get redirected to project's admin panel. Click the **Generate a new client secret** button to get your new client secret. Then, copy the **Client ID** and **Client secret.** Go back to the Clerk Dashboard and paste them into the respective fields. + 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: -![Obtaining the Client ID and Client secret](/docs/images/authentication-providers/github/3b1f58462fab3cc238c1a59994d1e2eb98f46b73-1489x964.png) + - **For development** – `https://your-domain.accounts.dev/sign-in` + - **For production** – `https://accounts.your-domain.com/sign-in` -Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with GitHub is now configured for your instance. + 1. Sign in with your GitHub account. + diff --git a/docs/authentication/social-connections/gitlab.mdx b/docs/authentication/social-connections/gitlab.mdx index cf8f57ef09..c8dfb269ff 100644 --- a/docs/authentication/social-connections/gitlab.mdx +++ b/docs/authentication/social-connections/gitlab.mdx @@ -7,7 +7,7 @@ How to set up social connection with GitLab ## Overview -Adding social connection with GitLab to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with GitLab to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -27,7 +27,7 @@ First, you need to register a new OAuth GitLab app. Follow the official GitLab i ![Creating an OAuth GitLab app](/docs/images/authentication-providers/gitlab/7e67b1cb88c1df509cac722d6a6b2d7c624686f8-1919x840.png) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitLab**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Go back to the GitLab panel, paste the value into the **Redirect URI**, select any scopes that would you like your users to provide and save the application. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **GitLab**. Toggle on **Use custom credentials** and copy **Redirect URI**. Go back to the GitLab panel, paste the value into the **Redirect URI**, select any scopes that would you like your users to provide and save the application. Once creation is complete, you'll get redirected to application's panel. Copy the **Application ID** and **Secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/google.mdx b/docs/authentication/social-connections/google.mdx index b34d5c3a0d..f6bb5d308e 100644 --- a/docs/authentication/social-connections/google.mdx +++ b/docs/authentication/social-connections/google.mdx @@ -22,6 +22,9 @@ description: Learn how to allow users to sign up and sign in to your Clerk app w Enabling OAuth with Google allows your users to sign up and sign in to your Clerk application with their Google account. +> [!WARNING] +> Google sign-in [**does not** allow users to sign in via in-app browsers](https://developers.googleblog.com/en/modernizing-oauth-interactions-in-native-apps-for-better-usability-and-security/). + ## Configure for your development instance For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. @@ -33,7 +36,7 @@ For _development instances_, Clerk uses preconfigured shared OAuth credentials a ## Configure for your production instance -In _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. +For _production instances_, you must provide custom credentials, which involves generating your own **Client ID** and **Client Secret** using your Google Developer account. To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Google Cloud Console](https://console.cloud.google.com/). @@ -44,7 +47,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Google**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized redirect URI** somewhere secure. Keep this modal and page open. + 1. Save the **Redirect URI** somewhere secure. Keep this modal and page open. ### Create a Google Developer project @@ -54,7 +57,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. In the menu on the left, select **Credentials**. 1. Select **Create Credentials**. Then, select **OAuth client ID.** You may need to [configure your OAuth consent screen](https://support.google.com/cloud/answer/6158849?hl=en#userconsent\&zippy=%2Cuser-consent). 1. Select the appropriate application type for your project. Most likely, you will choose **Web application**. - 1. In the **Authorized redirect URIs** setting, add the **Authorized redirect URI** value you saved from the Clerk Dashboard. + 1. In the **Authorized Redirect URIs** setting, paste the **Redirect URI** value you saved from the Clerk Dashboard. 1. Select **Create**. Keep this page open. ### Set the Client ID and Client Secret in your Clerk Dashboard @@ -75,6 +78,9 @@ To make the setup process easier, it's recommended to keep two browser tabs open - **For development** – `https://your-domain.accounts.dev/sign-in` - **For production** – `https://accounts.your-domain.com/sign-in` 1. Sign in with your Google account. + + > [!WARNING] + > Google sign-in [**does not** allow users to sign in via in-app browsers](https://developers.googleblog.com/en/modernizing-oauth-interactions-in-native-apps-for-better-usability-and-security/). ### Important note about switching to production diff --git a/docs/authentication/social-connections/hubspot.mdx b/docs/authentication/social-connections/hubspot.mdx index af3fd3fef8..dc810ef48c 100644 --- a/docs/authentication/social-connections/hubspot.mdx +++ b/docs/authentication/social-connections/hubspot.mdx @@ -7,7 +7,7 @@ How to set up social connection with HubSpot ## Overview -Adding social connection with HubSpot to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with HubSpot to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -31,6 +31,6 @@ Once your app is created, click on the **Auth** tab and copy the **App Id** and Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **HubSpot**. Toggle on **Use custom credentials** and paste the values you obtained during the previous step. -Before you close the modal, copy the **Authorized redirect URI**. Go back to the HubSpot panel and paste it into the **Redirect URL** field and click **Save**. +Before you close the modal, copy the **Redirect URI**. Go back to the HubSpot panel and paste it into the **Redirect URL** field and click **Save**. Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with HubSpot is now configured for your instance. diff --git a/docs/authentication/social-connections/huggingface.mdx b/docs/authentication/social-connections/huggingface.mdx index 503a892fe9..95a4202f4e 100644 --- a/docs/authentication/social-connections/huggingface.mdx +++ b/docs/authentication/social-connections/huggingface.mdx @@ -53,7 +53,7 @@ To configure your production instance, follow these steps: - **Logo URL**: Enter the URL of the logo for your application. - **Token Expiration**: Set the duration for which the token will be valid. - **Scopes**: Select the scopes that your application requires. Ensure that **openid**, **profile**, and **email** are included. - - **Redirect URLs**: You will need to add the **Authorized redirect URI** from Clerk. See the next step. + - **Redirect URLs**: You will need to add the **Redirect URI** from Clerk. See the next step. ### Get your Redirect URI from Clerk @@ -61,8 +61,8 @@ To configure your production instance, follow these steps: 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **Hugging Face**. - 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then, copy the **Authorized redirect URI**. - 1. Navigate back to Hugging Face and paste the **Authorized redirect URI** into the **Redirect URLs** field. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then, copy the **Redirect URI**. + 1. Navigate back to Hugging Face and paste the **Redirect URI** into the **Redirect URLs** field. 1. Select **Create application**. ### Set the Client ID and Client Secret in Clerk diff --git a/docs/authentication/social-connections/line.mdx b/docs/authentication/social-connections/line.mdx index 4fca7ef2ef..515e099771 100644 --- a/docs/authentication/social-connections/line.mdx +++ b/docs/authentication/social-connections/line.mdx @@ -7,7 +7,7 @@ How to set up social connection with LINE ## Overview -Adding social connection with LINE to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with LINE to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -34,7 +34,7 @@ The next step is to create a new **LINE Login channel**. You will have to select In the next screen, after the app has been created, you will find the **Basic settings** of the application. If you want to also make email address available for your application, you will have to apply for **Email address permission** in the bottom of your app's **Basic settings**. -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LINE**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste the value into the **LINE login → Callback URL** input. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LINE**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **LINE login → Callback URL** input. Once all the above are complete, copy the **Channel ID** and **Channel secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/linear.mdx b/docs/authentication/social-connections/linear.mdx index 5ac3a69c46..b20f4e6db2 100644 --- a/docs/authentication/social-connections/linear.mdx +++ b/docs/authentication/social-connections/linear.mdx @@ -1,38 +1,79 @@ --- title: Add Linear as a social connection -description: Learn how to set up social connection with Linear. +description: Learn how to allow users to sign up and sign in to your Clerk app with their Linear account using OAuth. --- -How to set up social connection with Linear + + - Use Linear to authenticate users with OAuth + -## Overview +Enabling OAuth with [Linear](https://developers.linear.app/docs/oauth/authentication) allows your users to sign up and sign in to your Clerk app with their Linear account. -Adding social connection with Linear to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URL** in your instance settings. +> [!IMPORTANT] +> You must be a workspace admin to create and manage OAuth apps in Linear. -To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. +## Configure for your development instance -For production instances, you will need to generate your own Client ID and Client secret using your Linear account. +For _development instances_, Clerk uses preconfigured shared OAuth credentials and redirect URIs—no other configuration is needed. -> [!NOTE] -> The purpose of this guide is to help you create a Linear OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth). +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 all users**. +1. In the **Choose provider** dropdown, select **Linear**. +1. Select **Add connection**. -## Before you start +## Configure for your production instance -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). -- You need to have a Linear account. To create one, [click here](https://linear.app). +For _production instances_, you must provide custom credentials which involves generating your own **Client ID** and **Client Secret** using your Linear account. -## Configuring Linear social connection +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Linear's API settings](https://linear.app/clerk/settings/api) page. -First, you need to create a new OAuth Linear app. Navigate on your **Settings > Account > API > OAuth applications** and click on **Create new**. On the modal that pops up, enter all the necessary info for your new app such as the name, the logo etc. + + ### Enable Linear as a social connection in Clerk -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Linear**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste this value in the Callback URLs field of your Linear application. + 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 all users**. + 1. In the **Choose provider** dropdown, select **Linear**. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. + 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. -![Creating a new application](/docs/images/authentication-providers/linear/creating-new-application.jpg) -When you have filled all the necessary info, click **Create**. Congratulations, you have successfully created your Linear OAuth application. + ### Create a Linear app -![Copying values from the Linear dashboard](/docs/images/authentication-providers/linear/copying-values-from-linear-dashboard.jpg) + 1. In the top-left of [Linear](https://linear.app/), select your workspace, then select **Preferences**. + 1. In the sidebar, under **My Account**, select **API**. Scroll down to **OAuth Applications** and select **Create new OAuth Application**. You'll be navigated to the [**Create new application**](https://linear.app/clerk/settings/api/applications/new) page. + 1. Complete the required fields. In **Callback URLs**, paste the **Redirect URI** you saved from the Clerk Dashboard. + 1. Select **Save**. The page will refresh and you should the **Client ID** and **Client Secret** at the top. Save both values somewhere secure. Keep this page open. -Copy the **Client ID** and **Client secret** as shown in the above image from the **Basic Information** menu of your app. Go back to the Clerk Dashboard and paste them into the respective fields. + ### Set the Client ID and Client Secret in your Clerk Dashboard -Don't forget to click **Apply** in the Clerk dashboard. Congratulations! Social connection with Linear is now configured for your instance. + 1. Navigate back to your Clerk Dashboard where the modal should still be open. Paste these values into the respective fields. + 1. Select **Add connection**. + + > [!NOTE] + > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the Linear connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + + ### Test your OAuth + + The simplest way to test your OAuth 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 Linear account. + diff --git a/docs/authentication/social-connections/linkedin-oidc.mdx b/docs/authentication/social-connections/linkedin-oidc.mdx index 9b544bddd2..eeb2aee1c0 100644 --- a/docs/authentication/social-connections/linkedin-oidc.mdx +++ b/docs/authentication/social-connections/linkedin-oidc.mdx @@ -69,14 +69,14 @@ To configure your production instance, follow these steps: 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then: 1. Under **Client ID**, add the value you copied from **Client ID** in the LinkedIn dashboard. 1. Under **Client Secret**, add the value you copied from **Primary Client Secret** in the LinkedIn dashboard. - 1. Copy the **Authorized redirect URI**. You need it to configure your LinkedIn app. + 1. Copy the **Redirect URI**. You need it to configure your LinkedIn app. 1. Select **Add connection**. - ### Set the Authorized Redirect URI for your LinkedIn application + ### Set the Redirect URI for your LinkedIn application 1. Navigate back to the LinkedIn Developer Portal and go to the **Auth** tab. 1. Under the **OAuth 2.0 settings** section, next to **Authorized redirect URLs for your app**, select the **Edit** icon. - 1. Select **Add redirect URL** and add the **Authorized redirect URI** you copied from the Clerk Dashboard. + 1. Select **Add redirect URL** and add the **Redirect URI** you copied from the Clerk Dashboard. ### Enable OpenID Connect in your LinkedIn application diff --git a/docs/authentication/social-connections/linkedin.mdx b/docs/authentication/social-connections/linkedin.mdx index a8dba9f4dd..c9d0a20c17 100644 --- a/docs/authentication/social-connections/linkedin.mdx +++ b/docs/authentication/social-connections/linkedin.mdx @@ -8,7 +8,7 @@ description: Learn how to set up social connection with LinkedIn. ## Overview -Adding social connection with LinkedIn to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with LinkedIn to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -32,7 +32,7 @@ You need to set a name, associate a LinkedIn page with it, and upload a logo for Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **LinkedIn**. -Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste the value into the **Redirect URL** of your LinkedIn app, as shown below. +Toggle on **Use custom credentials** and copy **Authorized Redirect URI**. Paste the value into the **Redirect URL** of your LinkedIn app, as shown below. ![Obtaining the Application ID and Client secret](/docs/images/authentication-providers/linkedin/c3532a2089d98362370241bc43355e95035555da-1089x837.png) diff --git a/docs/authentication/social-connections/microsoft.mdx b/docs/authentication/social-connections/microsoft.mdx index ce5e06d583..0b0ed582e7 100644 --- a/docs/authentication/social-connections/microsoft.mdx +++ b/docs/authentication/social-connections/microsoft.mdx @@ -72,18 +72,18 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Then: - Under **Client ID**, paste the value you copied from **Application (client) ID** in the Microsoft Azure portal. - Under **Client Secret**, paste the client secret value you generated. - - Save the **Authorized redirect URI** somewhere secure. + - Save the **Redirect URI** somewhere secure. - Select **Add connection**. ### Enable OpenID - To connect your Clerk app to your Microsoft app, set the **Authorized redirect URI** in your Microsoft Azure portal. + To connect your Clerk app to your Microsoft app, set the **Redirect URI** in your Microsoft Azure portal. 1. Navigate back to the Microsoft Azure portal. 1. In the sidebar, open the **Manage** dropdown and select **Authentication**. 1. Select **Add a platform**. 1. Select **Web**. - 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste the **Authorized redirect URI** you copied from the Clerk Dashboard. + 1. In the **Redirect URIs** field and the **Front-channel logout URL** field, paste the **Redirect URI** you copied from the Clerk Dashboard. 1. Under **Implicit grant and hybrid flows**, check both **Access tokens** and **ID tokens**. 1. Select **Configure** to save the changes. diff --git a/docs/authentication/social-connections/notion.mdx b/docs/authentication/social-connections/notion.mdx index da493e489d..730a441ea3 100644 --- a/docs/authentication/social-connections/notion.mdx +++ b/docs/authentication/social-connections/notion.mdx @@ -7,7 +7,7 @@ How to set up social connection with Notion ## Overview -Adding social connection with Notion to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Notion to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -31,7 +31,7 @@ You need to set a name, a logo, and associate a Notion workspace with it. Make s ![Configuring integration](/docs/images/authentication-providers/notion/configuring-integration.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Notion**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste the value into the **Redirect URIs**, as shown below, after changing the integration type to **Public**. Fill any other information required from Notion and click Submit. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Notion**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **Redirect URIs**, as shown below, after changing the integration type to **Public**. Fill any other information required from Notion and click Submit. ![Copying values from the Notion dashboard](/docs/images/authentication-providers/notion/copying-values-from-notion-dashboard.jpg) diff --git a/docs/authentication/social-connections/oauth.mdx b/docs/authentication/social-connections/oauth.mdx index 52a17a852e..74bd8bd780 100644 --- a/docs/authentication/social-connections/oauth.mdx +++ b/docs/authentication/social-connections/oauth.mdx @@ -99,7 +99,11 @@ export async function GET() { const clerkResponse = await clerkClient().users.getUserOauthAccessToken(userId, provider) - const accessToken = clerkResponse[0].token + const accessToken = clerkResponse[0].token || '' + + if (!accessToken) { + return NextResponse.json({ message: 'Access token not found' }, { status: 401 }) + } // Fetch the user data from the Notion API // This endpoint fetches a list of users diff --git a/docs/authentication/social-connections/slack.mdx b/docs/authentication/social-connections/slack.mdx index 66ab7734e0..7ae143a044 100644 --- a/docs/authentication/social-connections/slack.mdx +++ b/docs/authentication/social-connections/slack.mdx @@ -30,7 +30,7 @@ First, you need to create a new OAuth Slack app. On the main [Slack apps page](h ![Creating a new application](/docs/images/authentication-providers/slack/creating-new-application.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Slack**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Navigate to **OAuth & Permissions > Redirect URLs** and paste the value to add a new record. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Slack**. Toggle on **Use custom credentials** and copy **Redirect URI**. Navigate to **OAuth & Permissions > Redirect URLs** and paste the value to add a new record. ![Copying values from the Slack dashboard](/docs/images/authentication-providers/slack/copying-values-from-slack-dashboard.jpg) diff --git a/docs/authentication/social-connections/spotify.mdx b/docs/authentication/social-connections/spotify.mdx index a568e3383a..c424978abc 100644 --- a/docs/authentication/social-connections/spotify.mdx +++ b/docs/authentication/social-connections/spotify.mdx @@ -34,14 +34,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open 1. Select **Add connection** and select **For all users**. 1. In the **Choose provider** dropdown, select **Spotify**. 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. - 1. Save the **Authorized redirect URI** somewhere secure. Keep the modal and page open. + 1. Save the **Redirect URI** somewhere secure. Keep the modal and page open. ### Create your app in Spotify 1. On a separate page, go to the [Spotify Developer Dashboard](https://developer.spotify.com/) and sign in. 1. In the top-right, select your profile button and select [**Dashboard**](https://developer.spotify.com/dashboard). 1. Select [**Create app**](https://developer.spotify.com/dashboard/create). - 1. Complete the required fields. For **Redirect URIs**, add the **Authorized Redirect URI** that you saved from Clerk Dashboard. + 1. Complete the required fields. For **Redirect URIs**, add the **Redirect URI** that you saved from Clerk Dashboard. 1. Select **Save**. 1. On your app page, select **Settings**. Keep this page open. diff --git a/docs/authentication/social-connections/tiktok.mdx b/docs/authentication/social-connections/tiktok.mdx index 29c863f721..22ebd030bf 100644 --- a/docs/authentication/social-connections/tiktok.mdx +++ b/docs/authentication/social-connections/tiktok.mdx @@ -1,47 +1,83 @@ --- title: Add TikTok as a social connection -description: Learn how to set up social connection with TikTok. +description: Learn how to allow users to sign up and sign in to your Clerk app with their TikTok account using OAuth. --- -How to set up social connection with TikTok + + - Use TikTok ID to authenticate users with OAuth. + -## Overview +Enabling OAuth with [TikTok](https://developers.tiktok.com/doc/login-kit-manage-user-access-tokens) allows your users to sign up and sign in to your Clerk app with their TikTok account. -Adding social connection with TikTok to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +## Configure for your development instance -To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. +Due to TikTok's requirement to verify URL ownership for all redirect URLs, **TikTok cannot be used with shared credentials in development environments.** This is because individual users can't verify ownership of the Clerk development URL (`accounts.dev`). -For production instances, you will need to create your own developer account with **TikTok** and generate your own Client ID and Client secret. +However, TikTok can still be used in development environments if you create a sandbox app and configure custom credentials. In this case, there is no need to verify redirect URLs in the [sandbox environment](https://developers.tiktok.com/blog/introducing-sandbox). Instead, you can invite users who are allowed to sign in. -> [!NOTE] -> The purpose of this guide is to help you set up a TikTok developer account and a TikTok OAuth app - if you're looking for step-by-step instructions using Clerk to add social connection (OAuth) to your application, follow the [Social connection (OAuth) guide](/docs/authentication/social-connections/oauth). +It is recommended to test this integration in a staging or preview environment, as shared credentials require URL verification to function properly. -## Before you start +## Configure for your production instance -- You need to create a Clerk Application in your [Clerk Dashboard](https://dashboard.clerk.com/). For more information, check out our [Set up your application guide](/docs/quickstarts/setup-clerk). -- You need to have a TikTok Developer account. To create one, visit the [TikTok for developers](https://developers.tiktok.com/) page and click on Login ➜ Sign Up +To make the setup process easier, it's recommended to keep two browser tabs open: one for your [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [TikTok Developer Portal](https://developers.tiktok.com/). -## Configuring TikTok social connection + + ### Enable TikTok as a social connection in Clerk -First, you need to create a new TikTok app. Go to the [TikTok for developers](https://developers.tiktok.com/) page, login with your developer account and create a new app by clicking on the **My Apps** ➜ **Connect a new app** and following the on screen wizard. + 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 all users**. + 1. In the **Choose provider** dropdown, select **TikTok**. + 1. Ensure that both **Enable for sign-up and sign-in** and **Use custom credentials** are toggled on. Keep the modal and page open. -![Creating a new TikTok app](/docs/images/authentication-providers/tiktok/9a5749a9bf3f282c54af2a2b539ba372e4706574-1489x964.png) + ### Create your app in TikTok -Add an icon and a name for your new project and hit **Start**. + > [!TIP] + > If you're creating an app as an organization rather than as an individual developer, you must first [create an organization](https://developers.tiktok.com/organizations). For guidance on which option to choose, refer to [TikTok's guide on working with organizations](https://developers.tiktok.com/doc/working-with-organizations/)**.** -You'll get redirected to the app creation form. Notice that you need to fill the **Callback URL** and **Redirect domain** fields. + 1. On a separate page, go to the [TikTok Developer Portal](https://developers.tiktok.com/) and sign in. + 1. In the top-right, select [**Developer Portal**](https://developers.tiktok.com/apps), then select **Manage apps**. You'll be redirected to the **Manage apps** page. + 1. Select **Connect an app**. Complete the form then select **Confirm**. You'll be redirected to your **App details** page. + 1. In the **Basic information** section, complete the form. + 1. Select the **Verify URL properties** under any of the URL fields to verify your app URL. A modal will open. + 1. Select **Verify properties**. For the property type, select either **Domain** to verify ownership of the enter website, including subdomains, or **URL prefix** to verify ownership of a specific part of the website (e.g., `example.com/shop/`). See [the TikTok guide](https://developers.tiktok.com/doc/getting-started-create-an-app#verify_url_ownership) for more information. + 1. Enter your website and select **Verify**. + 1. Follow the instructions in the modal to verify your domain with your host provider. After entering the necessary information in your hosting provider's DNS settings, select **Verified**. Once your property is verified, select **Ok**. + 1. Select **Submit for review**. Keep this page open. -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **TikTok**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. + > [!NOTE] + > Your app needs to be reviewed by TikTok before the registration completes. This process may take a few days. -![Filling in the Callback URL and Redirect Domain fields](/docs/images/authentication-providers/tiktok/135491407e1afeea187644e4450fb77bb659d907-1489x964.png) + ### Set the Client ID and Client Secret in your Clerk Dashboard -Go back to the TikTok panel, paste the value into the **Callback URL** field. Copy the `clerk.[your-domain].com` part of the URL and paste it in the **Redirect domain** field. Hit **Apply** to compete the registration. + 1. In your TikTok app's **App details** page, select the icons next to the **Client key** and **Client secret** to reveal them. Copy these values. + 1. Navigate back to your Clerk Dashboard where the modal should still be open and paste these values into the respective fields. + 1. Select **Add connection**. -> [!NOTE] -> Your app needs to be reviewed by TikTok before the registration completes. Note that this might take a couple of days. + > [!NOTE] + > If the modal or page is not still open, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page in the Clerk Dashboard. Select the **TikTok** connection. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. -Once your app is approved, simply copy the **Client Key** and **Client Secret** from the TikTok panel, go back to the Clerk dashboard, open the **Manage credentials** modal for the TikTok provider, and paste them into the respective fields. + ### Test your OAuth -![Obtaining the Client Key and Client Secret](/docs/images/authentication-providers/tiktok/12885db4568578459fb4b9beab31838c929cf9d5-1382x833.png) + The simplest way to test your OAuth 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. -Finally, select **Add connection** so that the settings are applied. Congratulations! Social connection with TikTok is now configured for your instance. + 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 TikTok account. + diff --git a/docs/authentication/social-connections/twitch.mdx b/docs/authentication/social-connections/twitch.mdx index 580cea16eb..d08bd2897a 100644 --- a/docs/authentication/social-connections/twitch.mdx +++ b/docs/authentication/social-connections/twitch.mdx @@ -7,7 +7,7 @@ How to set up social connection with Twitch ## Overview -Adding social connection with Twitch to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Twitch to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -31,7 +31,7 @@ First, you need to register a new OAuth Twitch app at the [Twitch Developers Con Set a name and a category for your new application. You also need to add the **OAuth Redirect URLs.** -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitch**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Paste the value into the **OAuth Redirect URLs** input and click create. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitch**. Toggle on **Use custom credentials** and copy **Redirect URI**. Paste the value into the **OAuth Redirect URLs** input and click create. Once all the above are complete, copy the **Client ID** and **Client Secret.** Go back to the Clerk Dashboard and paste them into the respective fields. diff --git a/docs/authentication/social-connections/twitter.mdx b/docs/authentication/social-connections/twitter.mdx index 60cf63768d..54449ced7b 100644 --- a/docs/authentication/social-connections/twitter.mdx +++ b/docs/authentication/social-connections/twitter.mdx @@ -10,7 +10,7 @@ How to set up social connection with Twitter v1 ## Overview -Adding social connection with Twitter to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Twitter to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. Clerk does not currently support preconfigured shared OAuth credentials for Twitter on development instances. You will have to provide custom credentials for both development _and_ production instances, which includes generating your own Client ID and Client Secret using your Twitter Developer account. Don't worry, this guide will walk you through that process in just a few simple steps. @@ -31,7 +31,7 @@ To do so, go to "[Projects & Apps](https://developer.twitter.com/en/portal/proje > [!NOTE] > You will need your application to be approved for elevated status to be able to use it with Clerk. You can apply for the status in [Twitter developer dashboard](https://developer.twitter.com/en/portal/products/elevated) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitter**. Toggle on **Use custom credentials** and paste the **API Key** and **API Secret** values which you copied in the previous step. Then, copy the **Authorized redirect URI**. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Twitter**. Toggle on **Use custom credentials** and paste the **API Key** and **API Secret** values which you copied in the previous step. Then, copy the **Authorized Redirect URI**. Navigate to your application settings screen and scroll down to the **User authentication settings** section and click **Set up**. diff --git a/docs/authentication/social-connections/x-twitter.mdx b/docs/authentication/social-connections/x-twitter.mdx index a7c0f331e0..ed7aef095e 100644 --- a/docs/authentication/social-connections/x-twitter.mdx +++ b/docs/authentication/social-connections/x-twitter.mdx @@ -19,7 +19,7 @@ description: Learn how to set up a social connection with X/Twitter v2 in your C > - Create an X/Twitter application - Enable X/Twitter as a social connection - - Set Clerk's **Authorized Redirect URI** in your X/Twitter application + - Set Clerk's **Redirect URI** in your X/Twitter application - Set X/Twitter's **Client ID** and **Client Secret** in your Clerk Dashboard @@ -48,15 +48,15 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw 1. In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. 1. Select the **Add connection** button, and select **For all users**. 1. In the **Choose provider** dropdown, select **X/Twitter**. - 1. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Keep this modal and page open. + 1. Toggle on **Use custom credentials** and copy **Redirect URI**. Keep this modal and page open. - ### Set the Authorized Redirect URI in your X/Twitter application + ### Set the Redirect URI in your X/Twitter application 1. Navigate back to the X/Twitter Developer portal. 1. On the application settings screen, scroll down to the **User authentication settings** section and select **Set up**. You'll be presented with the **User authentication settings** page. 1. Under **App permissions**, you can choose the permissions you want to request from the user. For this tutorial, select the **Read** permission. 1. Under **Type of App**, select **Web App, Automated App or Bot**. - 1. Under **App info**, in the **Callback URI / Redirect URL** input, paste the **Authorized Redirect URI** value you copied from the Clerk Dashboard. + 1. Under **App info**, in the **Callback URI / Redirect URL** input, paste the **Redirect URI** value you copied from the Clerk Dashboard. 1. Fill any other required fields, such as the **Website URL**, and select **Save**. ### Set the Client ID and Client Secret in your Clerk Dashboard @@ -66,7 +66,7 @@ Clerk does not currently support preconfigured shared OAuth credentials for X/Tw Go back to the Clerk Dashboard, where the modal should still be open, and paste these values into the respective fields. > [!NOTE] - > If the modal or page is not still open, navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Next to **X/Twitter**, select the settings cog icon. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. + > If the modal or page is not still open, navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Next to **X/Twitter**, select the settings icon. Under **Use custom credentials**, you can paste the **Client ID** and **Client Secret** into their respective fields. ### Test your OAuth diff --git a/docs/authentication/social-connections/xero.mdx b/docs/authentication/social-connections/xero.mdx index b47fd1261c..385173ffdf 100644 --- a/docs/authentication/social-connections/xero.mdx +++ b/docs/authentication/social-connections/xero.mdx @@ -7,7 +7,7 @@ How to set up social connection with Xero ## Overview -Adding social connection with Xero to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Authorized redirect URI** in your instance settings. +Adding social connection with Xero to your app with Clerk is done in a few steps - you only need to set the **Client ID**, **Client Secret** and **Redirect URI** in your instance settings. To make the development flow as smooth as possible, Clerk uses preconfigured shared OAuth credentials and redirect URIs for development instances - no other configuration is needed. @@ -27,7 +27,7 @@ First, you need to create a new OAuth2 Xero app. Click New App and fill all the ![Creating a new application](/docs/images/authentication-providers/xero/creating-new-application.jpg) -Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Xero**. Toggle on **Use custom credentials** and copy **Authorized redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections). In the top navigation, select **Configure**. Then in the sidebar, select **SSO Connections**. Select the **Add connection** button, and select **For all users**. In the **Choose provider** dropdown, select **Xero**. Toggle on **Use custom credentials** and copy **Redirect URI**. Make sure the value matches the **Redirect URIs**, as shown below. ![Copying values from the Xero dashboard](/docs/images/authentication-providers/xero/copying-values-from-xero-dashboard.jpg) diff --git a/docs/authentication/web3/coinbase-wallet.mdx b/docs/authentication/web3/coinbase-wallet.mdx index 801a6e5c37..d7e5f26bcf 100644 --- a/docs/authentication/web3/coinbase-wallet.mdx +++ b/docs/authentication/web3/coinbase-wallet.mdx @@ -44,7 +44,7 @@ To collect additional information about your user during sign-up: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/web3). 1. In the top navigation, select **Configure**. Then in the sidebar, select **[Email, phone, username](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username)**. -1. On this page, toggle on attributes you wish to collect from your user during sign up. Select the settings cog icon next to an attribute to set it as **Required**. When set as **Required**, Clerk automatically prompts the user for this information after they authenticate with Coinbase Wallet. +1. On this page, toggle on attributes you wish to collect from your user during sign up. Select the settings icon next to an attribute to set it as **Required**. When set as **Required**, Clerk automatically prompts the user for this information after they authenticate with Coinbase Wallet. ## Connect Coinbase Wallet to existing account diff --git a/docs/components/authentication/sign-in.mdx b/docs/components/authentication/sign-in.mdx index aec18bd4a8..b81eef4f27 100644 --- a/docs/components/authentication/sign-in.mdx +++ b/docs/components/authentication/sign-in.mdx @@ -18,7 +18,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/authentication/sign-up.mdx b/docs/components/authentication/sign-up.mdx index 92ebff93f5..f06ac49296 100644 --- a/docs/components/authentication/sign-up.mdx +++ b/docs/components/authentication/sign-up.mdx @@ -18,7 +18,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/clerk-provider.mdx b/docs/components/clerk-provider.mdx index 76da3b1228..e7d7104c09 100644 --- a/docs/components/clerk-provider.mdx +++ b/docs/components/clerk-provider.mdx @@ -106,7 +106,7 @@ The `` component must be added to your React entrypoint. - `appearance?` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional object to style your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- @@ -148,7 +148,7 @@ The `` component must be added to your React entrypoint. - `localization` - [Localization](/docs/customization/localization) | undefined - Optional object to localize your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- @@ -218,7 +218,7 @@ The `` component must be added to your React entrypoint. - `supportEmail?` - `string` - Optional support email for display in authentication screens. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional support email for display in authentication screens. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- diff --git a/docs/components/control/authenticate-with-callback.mdx b/docs/components/control/authenticate-with-callback.mdx index b1b4d8c8cc..50f8a0741d 100644 --- a/docs/components/control/authenticate-with-callback.mdx +++ b/docs/components/control/authenticate-with-callback.mdx @@ -1,131 +1,11 @@ --- title: \RedirectCallback /> -description: The `` is used to complete a custom OAuth flow. Simply render the component under the route you passed as `redirectUrl` to the `authenticateWithRedirect` methods. +description: Clerk's `` component is used to implement custom OAuth flows. It handles the OAuth callback and completes the authentication process. --- -The `` is used to complete a custom OAuth flow. Simply render the component under the route you passed as `redirectUrl` to the `authenticateWithRedirect` methods. +The `` component is a crucial part of implementing custom OAuth flows in your application. It serves as the callback handler for the authentication process initiated by the `authenticateWithRedirect()` method. Render it on the route specified as the `redirectUrl` in your `authenticateWithRedirect()` call. -## Usage - - - - This example below uses built in Next.js pages, but you could use any routing library you want. - - ```tsx {{ filename: 'app.tsx' }} - import '@/styles/globals.css' - import { ClerkProvider, SignedIn, SignedOut, useSignIn } from '@clerk/nextjs' - import { AppProps } from 'next/app' - import { useRouter } from 'next/router' - - const publicPages: Array = [] - - const SignInOAuthButtons = () => { - const { signIn, isLoaded } = useSignIn() - if (!isLoaded) { - return null - } - const signInWithGoogle = () => - signIn.authenticateWithRedirect({ - strategy: 'oauth_google', - redirectUrl: '/sso-callback', - redirectUrlComplete: '/', - }) - return - } - function MyApp({ Component, pageProps }: AppProps) { - const { pathname } = useRouter() - const isPublicPage = publicPages.includes(pathname) - - return ( - - {isPublicPage ? ( - - ) : ( - <> - - - - - - - - )} - - ) - } - - export default MyApp - ``` - - Once you have implemented your sign in flow, you can implement the callback page. - - ```tsx {{ filename: '/pages/sso-callback.tsx' }} - import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' - - export default function SSOCallBack() { - return - } - ``` - - - - This example below is using the `react-router-dom` library. You can use any routing library you want. - - ```tsx {{ filename: 'app.tsx' }} - import { - ClerkProvider, - AuthenticateWithRedirectCallback, - SignedOut, - useSignIn, - SignedIn, - } from '@clerk/clerk-react' - - import { Route, Routes } from 'react-router-dom' - - function App() { - return ( - - {/* Define a / route that displays the OAuth button */} - - } /> - - } /> - - - ) - } - - function HomePages() { - return ( - <> - - - - -
Hello! You are Signed In!
- - - ) - } - - function SignInOAuthButtons() { - const { signIn, isLoaded } = useSignIn() - if (!isLoaded) { - return null - } - const signInWithGoogle = () => - signIn.authenticateWithRedirect({ - strategy: 'oauth_google', - redirectUrl: '/sso-callback', - redirectUrlComplete: '/', - }) - return - } - - export default App - ``` - - +This component automatically handles the OAuth callback, completing the authentication process and managing the user's session. ## Properties @@ -233,3 +113,123 @@ The `` is used to complete a custom OAuth fl Full URL or path to navigate after successful sign in or sign up. This is the same as setting `afterSignInUrl` and `afterSignUpUrl` to the same value. The **`signXfallbackRedirectUrl` and `signXforceRedirectUrl` props have priority over the deprecated `redirectUrl` and should be used instead.** + +## Usage + +In the following example, when a user selects the "Sign in with Google" button, they are redirected to Google for authentication. After successful authentication, Google redirects the user back to your application at the `/sso-callback` route, where the `` component is automatically rendered. This component handles the OAuth callback, completes the authentication process, and manages the user's session. + + + + ```tsx {{ filename: 'app/layout.tsx', collapsible: true }} + 'use client' + + import { ClerkProvider, SignedIn, SignedOut, UserButton, useSignIn } from '@clerk/nextjs' + + const SignInOAuthButtons = () => { + const { signIn, isLoaded } = useSignIn() + + if (!isLoaded) { + return null + } + + const signInWithGoogle = () => + signIn.authenticateWithRedirect({ + strategy: 'oauth_google', + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + + return + } + + export default function RootLayout({ children }: { children: React.ReactNode }) { + return ( + + + +
+ + + + + + +
+
{children}
+ + + + ) + } + ``` + + Once you have implemented your sign-in flow, you can implement the callback page. + + ```tsx {{ filename: 'app/sso-callback/page.tsx' }} + import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' + + export default function Page() { + return + } + ``` + + + + The following example is using the `react-router-dom` library, but you can use any routing library you want. + + ```tsx {{ filename: 'app.tsx', collapsible: true }} + import { + ClerkProvider, + AuthenticateWithRedirectCallback, + SignedOut, + useSignIn, + SignedIn, + } from '@clerk/clerk-react' + + import { Route, Routes } from 'react-router-dom' + + function App() { + return ( + + {/* Define a / route that displays the OAuth button */} + + } /> + + {/* Define a /sso-callback route that renders the component */} + } /> + + + ) + } + + function HomePages() { + return ( + <> + + + + +
You are signed in
+ + + ) + } + + function SignInOAuthButtons() { + const { signIn, isLoaded } = useSignIn() + if (!isLoaded) { + return null + } + const signInWithGoogle = () => + signIn.authenticateWithRedirect({ + strategy: 'oauth_google', + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', + }) + return + } + + export default App + ``` + + diff --git a/docs/components/organization/create-organization.mdx b/docs/components/organization/create-organization.mdx index 08d2795a37..59d140f994 100644 --- a/docs/components/organization/create-organization.mdx +++ b/docs/components/organization/create-organization.mdx @@ -15,7 +15,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/organization/organization-list.mdx b/docs/components/organization/organization-list.mdx index d97d133011..1b14765ec9 100644 --- a/docs/components/organization/organization-list.mdx +++ b/docs/components/organization/organization-list.mdx @@ -29,7 +29,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/organization/organization-profile.mdx b/docs/components/organization/organization-profile.mdx index 93e0731b7d..615d0a635d 100644 --- a/docs/components/organization/organization-profile.mdx +++ b/docs/components/organization/organization-profile.mdx @@ -19,7 +19,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/organization/organization-switcher.mdx b/docs/components/organization/organization-switcher.mdx index f7e6a378ee..60c3a5e494 100644 --- a/docs/components/organization/organization-switcher.mdx +++ b/docs/components/organization/organization-switcher.mdx @@ -26,7 +26,7 @@ All props below are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/user/user-button.mdx b/docs/components/user/user-button.mdx index 76029970cb..b9730e6479 100644 --- a/docs/components/user/user-button.mdx +++ b/docs/components/user/user-button.mdx @@ -38,7 +38,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/components/user/user-profile.mdx b/docs/components/user/user-profile.mdx index 4c72998229..2465d2c3e0 100644 --- a/docs/components/user/user-profile.mdx +++ b/docs/components/user/user-profile.mdx @@ -15,7 +15,7 @@ All props are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. + Optional object to style your components. Will only affect [Clerk components](/docs/components/overview) and not [Account Portal](/docs/customization/account-portal/overview) pages. --- diff --git a/docs/custom-flows/email-links.mdx b/docs/custom-flows/email-links.mdx index a11f5989fb..d91fc06fd0 100644 --- a/docs/custom-flows/email-links.mdx +++ b/docs/custom-flows/email-links.mdx @@ -46,7 +46,7 @@ Email link authentication can be configured through the Clerk Dashboard. Go to * Don't forget that you also need to make sure you've configured your application instance to request the user's email address. Users can receive email links only via email messages. Make sure you toggle on **Email address** under the **Contact information** section. -If you click on the **Settings cog** icon next to **Email address**, the email address configuration screen will pop open. You can toggle on **Require** if you want to make sure that all users have an email address associated with their profile. +If you click on the **Settings** icon next to **Email address**, the email address configuration screen will pop open. You can toggle on **Require** if you want to make sure that all users have an email address associated with their profile. You can also find the **Verification methods** section on this screen. Here, you can toggle on **Email verification link** if you would like to allow your users to verify their email with an email link. You can also toggle on **Email verification code** if you would like to allow your users to verify their email with a one-time passcode. diff --git a/docs/custom-flows/email-password-mfa.mdx b/docs/custom-flows/email-password-mfa.mdx index 45098ff0f4..4f39e11a68 100644 --- a/docs/custom-flows/email-password-mfa.mdx +++ b/docs/custom-flows/email-password-mfa.mdx @@ -21,7 +21,7 @@ This guide will walk you through how to build a custom email/password sign-in fl 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). 1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**. - 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings cog icon next to each user attribute to check if a setting is required or optional. If you want to require **Username**, you must collect the username and pass the data to the `create()` method in your custom flow. + 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings icon next to each user attribute to check if a setting is required or optional. If you want to require **Username**, you must collect the username and pass the data to the `create()` method in your custom flow. 1. In the **Authentication strategies** section of this page, ensure **Password** is enabled. ### Enable multi-factor authentication diff --git a/docs/custom-flows/email-password.mdx b/docs/custom-flows/email-password.mdx index 4335384979..1961b21aa3 100644 --- a/docs/custom-flows/email-password.mdx +++ b/docs/custom-flows/email-password.mdx @@ -17,7 +17,7 @@ This guide will walk you through how to build a custom email/password sign-up an 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). 1. In the navigation sidebar, select **User & Authentication > Email, Phone, and Username**. - 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings cog icon next to each option to verify if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. + 1. Ensure that _only_ **Email address** is required. If **Phone number** and **Username** are enabled, ensure they are not required. Use the settings icon next to each option to verify if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. 1. In the **Authentication strategies** section of this page, ensure **Password** is enabled. > [!NOTE] diff --git a/docs/custom-flows/email-sms-otp.mdx b/docs/custom-flows/email-sms-otp.mdx index d9b2e47306..6d0f453e87 100644 --- a/docs/custom-flows/email-sms-otp.mdx +++ b/docs/custom-flows/email-sms-otp.mdx @@ -19,7 +19,7 @@ This guide will walk you through how to build a custom SMS OTP sign-up and sign- 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). 1. In the navigation sidebar, go to **User & Authentication > Email, Phone, Username**. - 1. Ensure that _only_ **Phone number** is required. If **Email address** or **Username** are enabled, ensure they are not required. Use the settings cog icon to check if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. For this guide, if you would like to use email OTP instead, require the **Email address** option instead of the **Phone number** option. + 1. Ensure that _only_ **Phone number** is required. If **Email address** or **Username** are enabled, ensure they are not required. Use the settings icon to check if a setting is required or optional. If you would like to require **Username**, you must collect the username and pass it to the `create()` method in your custom flow. For this guide, if you would like to use email OTP instead, require the **Email address** option instead of the **Phone number** option. 1. In the **Authentication strategies** section of this page, ensure **SMS verification code** is enabled. Ensure **Password** is toggled off, as you are prioritizing passwordless, SMS OTP-only authentication in this guide. If you would like to use email OTP instead, enable the **Email verification code** strategy instead of the **SMS verification code** strategy. ### Sign-up flow diff --git a/docs/customization/localization.mdx b/docs/customization/localization.mdx index ceae51cc36..690a6e85a2 100644 --- a/docs/customization/localization.mdx +++ b/docs/customization/localization.mdx @@ -1,16 +1,16 @@ --- title: Localization prop (experimental) -description: Use the Clerk localizations package to override and provide predefined or custom localizations for your Clerk Components, enabling you to offer localized content or tailor the wording to match your brand. +description: Use the Clerk localizations package to override and provide predefined or custom localizations for your Clerk components, enabling you to offer localized content or tailor the wording to match your brand. --- > [!WARNING] > This feature is currently experimental and may not behave as expected. If you encounter any issues, please reach out to [support](/contact/support){{ target: '_blank' }} with as much detail as possible. -Clerk offers the ability to override the strings for all of the elements in each of the Clerk Components. This allows you to provide localization for your users or change the wording to suit your brand. +Clerk offers the ability to override the strings for all of the elements in each of the Clerk components. This allows you to provide localization for your users or change the wording to suit your brand. ## `@clerk/localizations` -The `@clerk/localizations` package contains predefined localizations for the Clerk Components. +The `@clerk/localizations` package contains predefined localizations for the Clerk components. ### Languages @@ -256,7 +256,7 @@ Our localizations are customer-sourced and we encourage customers to add or upda ## Custom localizations -You can also provide your own localizations for the Clerk Components. This is useful if you want to provide limited or quick localization for a language that Clerk doesn't currently support or if you want to change the wording to suit your brand. +You can also provide your own localizations for the Clerk components. This is useful if you want to provide limited or quick localization for a language that Clerk doesn't currently support or if you want to change the wording to suit your brand. ### Usage diff --git a/docs/guides/transferring-your-app.mdx b/docs/guides/transferring-your-app.mdx index 80fd903c96..d754fe58ad 100644 --- a/docs/guides/transferring-your-app.mdx +++ b/docs/guides/transferring-your-app.mdx @@ -18,7 +18,7 @@ To set up a payment method without being charged: > This guide offers a temporary solution for this issue. Clerk is actively working to improve this process. 1. Switch to the receiving organization and open the organization switcher at the top-left of the Dashboard. -1. Select the cog icon (⚙) to manage your organization. +1. Select the settings icon to manage your organization. 1. In the sidebar, select **Billing**, then select **Upgrade to unlimited members**. 1. Add your billing information. **You will not be charged immediately**. Doing this just ensures billing information is added to the organization. 1. Once that billing information is added, you will be able to transfer your Clerk app to the receiving organization. diff --git a/docs/integrations/webhooks/inngest.mdx b/docs/integrations/webhooks/inngest.mdx index 0cc98d3293..9331aa6879 100644 --- a/docs/integrations/webhooks/inngest.mdx +++ b/docs/integrations/webhooks/inngest.mdx @@ -3,7 +3,7 @@ title: Handling webhooks with Inngest description: Learn how to integrate Clerk with Inngest. --- -Webhooks allow you to [synchronize data](/docs/integrations/webhooks/sync-data) from Clerk to your application backend. You can either handle them directly in your backend with an endpoint or use a tool like [Inngest](https://inngest.com/) which receives the webhook events for you and reliably executes functions in your codebase. When handling webhooks, Inngest receives the [webhook events](/docs/integrations/webhooks/overview#supported-webhook-events) for you and uses a built-in queue to reliably execute longer running functions with additional functionality including: +Webhooks allow you to [synchronize data](/docs/integrations/webhooks/sync-data) from Clerk to your application backend. You can either handle them directly in your backend with an endpoint or use a tool like [Inngest](https://www.inngest.com) which receives the webhook events for you and reliably executes functions in your codebase. When handling webhooks, Inngest receives the [webhook events](/docs/integrations/webhooks/overview#supported-webhook-events) for you and uses a built-in queue to reliably execute longer running functions with additional functionality including: - [Limiting concurrency](https://www.inngest.com/docs/guides/concurrency) to handle spikes in events without overwhelming your API or database. - Triggering multiple functions from a single event ([fan-out jobs](https://www.inngest.com/docs/guides/fan-out-jobs)). diff --git a/docs/manifest.json b/docs/manifest.json index 3bfd5ec86a..530e3bb61f 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -951,7 +951,23 @@ [ { "title": "Playwright", - "href": "/docs/testing/playwright" + "collapse": true, + "items": [ + [ + { + "title": "Overview", + "href": "/docs/testing/playwright/overview" + }, + { + "title": "Test helpers", + "href": "/docs/testing/playwright/test-helpers" + }, + { + "title": "Test authenticated flows", + "href": "/docs/testing/playwright/test-authenticated-flows" + } + ] + ] }, { "title": "Cypress", "href": "/docs/testing/cypress" }, { diff --git a/docs/organizations/organization-workspaces.mdx b/docs/organizations/organization-workspaces.mdx index 3894f2cd75..2bea196637 100644 --- a/docs/organizations/organization-workspaces.mdx +++ b/docs/organizations/organization-workspaces.mdx @@ -20,7 +20,7 @@ This guide will walk you through how to use the Clerk Dashboard to create an org ## Invite collaborators to your organization workspace 1. Navigate to the [Clerk Dashboard](https://clerk.com/dashboard). -1. In the top left navigation, select the organization workspace and select the settings cog icon. A modal will appear with the organization profile. +1. In the top left navigation, select the organization workspace and select the settings icon. A modal will appear with the organization profile. 1. Select the **Members** tab and select the **Invite** button. 1. Enter the email address of the collaborator you wish to invite and select the role you wish to assign to the collaborator. If inviting multiple collaborators at a time, ensure email addresses are separated by spaces or commas. 1. Select **Send invitations**. diff --git a/docs/organizations/overview.mdx b/docs/organizations/overview.mdx index f6fbb69e7e..62799b73a4 100644 --- a/docs/organizations/overview.mdx +++ b/docs/organizations/overview.mdx @@ -148,7 +148,7 @@ To configure your application's **Email address** settings: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username). 1. In the navigation sidebar, select **User & Authentication > Email, Phone, Username**. 1. In the **Contact information** section, ensure that **Email address** is toggled on. -1. Next to **Email address**, select the settings cog icon to configure the email address settings. Here, at least **Require** should be toggled on. +1. Next to **Email address**, select the settings icon to configure the email address settings. Here, at least **Require** should be toggled on. ## Organization management diff --git a/docs/organizations/roles-permissions.mdx b/docs/organizations/roles-permissions.mdx index 5725b02a3d..bd840396ef 100644 --- a/docs/organizations/roles-permissions.mdx +++ b/docs/organizations/roles-permissions.mdx @@ -47,7 +47,7 @@ Permissions grant users privileged access to resources and operations, like crea ### System Permissions -Clerk has a set of System Permissions that power [Clerk’s Frontend API](/docs/reference/frontend-api){{ target: '_blank' }} and [organization-related Clerk Components](/docs/components/overview#organization-components). They are a baseline set of permissions that Clerk needs to operate functionally. +Clerk has a set of System Permissions that power [Clerk’s Frontend API](/docs/reference/frontend-api){{ target: '_blank' }} and [organization-related Clerk components](/docs/components/overview#organization-components). They are a baseline set of permissions that Clerk needs to operate functionally. Clerk’s System Permissions consist of the following: diff --git a/docs/quickstarts/express.mdx b/docs/quickstarts/express.mdx index bc0743b576..f645a7a5e6 100644 --- a/docs/quickstarts/express.mdx +++ b/docs/quickstarts/express.mdx @@ -120,7 +120,7 @@ Learn how to integrate Clerk into your Express backend for secure user authentic const app = express() - app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), (req, res) => { + app.get('/protected', requireAuth({ signInUrl: '/sign-in' }), async (req, res) => { const { userId } = req.auth const user = await clerkClient.users.getUser(userId) return res.json({ user }) diff --git a/docs/references/javascript/clerk/clerk.mdx b/docs/references/javascript/clerk/clerk.mdx index 4f727ba3dc..9dceaa0102 100644 --- a/docs/references/javascript/clerk/clerk.mdx +++ b/docs/references/javascript/clerk/clerk.mdx @@ -303,14 +303,14 @@ All props below are optional. - `appearance` - [Appearance](/docs/customization/overview) | undefined - Optional object to style your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional object to style your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- - `localization` - [Localization](/docs/customization/localization) | undefined - Optional object to localize your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- diff --git a/docs/references/nextjs/clerk-middleware.mdx b/docs/references/nextjs/clerk-middleware.mdx index d3d09155f6..062b45faef 100644 --- a/docs/references/nextjs/clerk-middleware.mdx +++ b/docs/references/nextjs/clerk-middleware.mdx @@ -276,7 +276,7 @@ const isProtectedRoute = createRouteMatcher(['dashboard/(.*)']) export default clerkMiddleware((auth, req) => { if (isProtectedRoute(req)) auth().protect() - intlMiddleware(req) + return intlMiddleware(req) }) export const config = { diff --git a/docs/references/nextjs/current-user.mdx b/docs/references/nextjs/current-user.mdx index e0473559c0..4ba55fa768 100644 --- a/docs/references/nextjs/current-user.mdx +++ b/docs/references/nextjs/current-user.mdx @@ -8,7 +8,7 @@ The `currentUser` helper returns the [`Backend User`](/docs/references/backend/t Under the hood, this helper: - calls `fetch()`, so it is automatically deduped per request. -- uses the `GET /v1/users/me` endpoint. +- uses the [`GET /v1/users/{user_id}`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) endpoint. - counts towards the [Backend API Request Rate Limit](/docs/backend-requests/resources/rate-limits#rate-limits). ```tsx {{ filename: 'app/page.tsx' }} diff --git a/docs/references/nextjs/custom-signup-signin-pages.mdx b/docs/references/nextjs/custom-signup-signin-pages.mdx index 64c4536e71..59931b767b 100644 --- a/docs/references/nextjs/custom-signup-signin-pages.mdx +++ b/docs/references/nextjs/custom-signup-signin-pages.mdx @@ -141,6 +141,6 @@ If Clerk's prebuilt components don't meet your specific needs or if you require --- - - [Clerk Components](/docs/components/overview) + - [Clerk components](/docs/components/overview) - Learn more about Clerk's prebuilt components that make authentication and user management easy. diff --git a/docs/references/react/overview.mdx b/docs/references/react/overview.mdx index 2b35b3f1b6..3c89e9ecb4 100644 --- a/docs/references/react/overview.mdx +++ b/docs/references/react/overview.mdx @@ -8,7 +8,7 @@ Clerk React is a wrapper around ClerkJS. It is the recommended way to integrate > [!WARNING] > If you are using Next.js, please make sure to install `@clerk/nextjs` as `@clerk/clerk-react` is incompatible. See the [Next.js](/docs/references/nextjs/overview) documentation for more information. -Clerk React provides React.js implementations of [Clerk Components](/docs/components/overview); highly customizable, pre-built components that you can use to build beautiful user management applications. You can find display components for building [sign-in](/docs/components/authentication/sign-in), [sign-up](/docs/components/authentication/sign-up), [account switching](/docs/components/user/user-button), and [user profile management](/docs/components/user/user-profile) pages as well as flow [control components](/docs/components/control/signed-in) that act as helpers for implementing a seamless authentication experience. +Clerk React provides React.js implementations of [Clerk components](/docs/components/overview); highly customizable, pre-built components that you can use to build beautiful user management applications. You can find display components for building [sign-in](/docs/components/authentication/sign-in), [sign-up](/docs/components/authentication/sign-up), [account switching](/docs/components/user/user-button), and [user profile management](/docs/components/user/user-profile) pages as well as flow [control components](/docs/components/control/signed-in) that act as helpers for implementing a seamless authentication experience. Clerk React comes loaded with [custom hooks](/docs/references/react/use-user). These hooks give you access to the [Clerk object](/docs/references/javascript/clerk/clerk), and a set of useful helper methods for signing in and signing up. diff --git a/docs/references/remix/clerk-app.mdx b/docs/references/remix/clerk-app.mdx index a08c64d165..640f879ada 100644 --- a/docs/references/remix/clerk-app.mdx +++ b/docs/references/remix/clerk-app.mdx @@ -66,14 +66,14 @@ export default ClerkApp(App) - `supportEmail?` - `string` - Optional support email for display in authentication screens. Will only affect Clerk Components and not Account Portal pages. + Optional support email for display in authentication screens. Will only affect Clerk components and not Account Portal pages. --- - `localization` - [Localization](/docs/customization/localization) | undefined - Optional object to localize your components. Will only affect [Clerk Components][components-ref] and not [Account Portal][ap-ref] pages. + Optional object to localize your components. Will only affect [Clerk components][components-ref] and not [Account Portal][ap-ref] pages. --- diff --git a/docs/security/csrf-protection.mdx b/docs/security/csrf-protection.mdx index c5ab7e8d3a..29e5a3303f 100644 --- a/docs/security/csrf-protection.mdx +++ b/docs/security/csrf-protection.mdx @@ -3,26 +3,35 @@ title: CSRF protection description: CSRF is an attack that tricks the victim into submitting a malicious request. It inherits the identity and privileges of the victim to perform an undesired function on the victim’s behalf. --- -CSRF is an attack that tricks the victim into submitting a malicious request. It inherits the identity and privileges of the victim to perform an undesired function on the victim's behalf. For most sites, browser requests automatically include any credentials associated with the site, such as the user's session cookie, IP address, Windows domain credentials, and so forth. Therefore, if the user is currently authenticated to the site, the site will have no way to distinguish between the forged request sent by the victim and a legitimate request sent by the victim. +Cross Site Request Forgery (CSRF) is an attack that deceives a victim into submitting a malicious request. The attack inherits the victim's identity and privileges to perform an undesired action on the their behalf. For most sites, browser requests automatically include credentials associated with the site, such as the user's session cookie, IP address, Windows domain credentials, and more. Therefore, if the user is currently authenticated, the site cannot distinguish between a forged request initiated by the attacker and a legitimate request from the user. -[The OWASP® Foundation, Cross Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/xss/) +[The OWASP® Foundation, Cross Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) -Most Cross Site Request Forgery (CSRF) attacks can be protected against by properly configuring the way session tokens are stored. Clerk handles the necessary configuration on your behalf by configuring cookies with the _SameSite_ flag. +Most CSRF attacks can be protected against by properly configuring the way session tokens are stored. Clerk handles the necessary configuration on your behalf by configuring cookies with the `SameSite` flag. -## How does SameSite help prevent CSRF attacks? +## What does a CSRF attack look like? + +Imagine an attacker made a malicious website at `foo.com` that contained the following code: + +```html + +``` -SameSite is a flag on the [Set-Cookie header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie) that is issued by a server to set a cookie in the browser. +Notice the query string `?action=delete&id=123`. -When a cookie's SameSite flag is set to Strict or Lax, the cookie will not be sent with HTTP requests that originate from a third party site (a "cross-site" request). The cookie will only be sent when the originating site shares the same root domain, or more precisely, the same [public suffix](https://publicsuffix.org/). +If a user logged into `example.com` loads this page, and `example.com` is configured to execute actions from the query string for authorized users, an attacker could potentially delete the user's account on `example.com` without their knowledge. The user would simply see a webpage with a broken image, which could be easily hidden using CSS. + +## How does SameSite help prevent CSRF attacks? -For example, consider a cookie that is set on foo.example.com: +Fortunately, [the `SameSite` flag](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value), which can be added to the `Set-Cookie` header, can prevent CSRF attacks. In the previous example, if the developers of `example.com` set the `SameSite` flag on their session cookies to `Strict` or `Lax`, the browser would not send the cookie with requests to `foo.com`. Therefore, the attack would fail as the user would not be authenticated and the backend would presumably block the delete action. -- The cookie _will_ be sent when `bar.example.com` initiates a request to `foo.example.com` -- The cookie _will not_ be sent when `bar.example.org` initiates a request to `foo.example.com` +Let's break down what each of the values of `SameSite` do: -_Lax_ alleviates this restriction slightly and allows for the cookie to be sent when the user is navigating from a third party site. In the example above, if the user is on `bar.example.org` and clicks a link to `foo.example.com`, then the initial request to load `foo.example.com` will include the cookie. +- `Strict`: The cookie will only be sent with HTTP requests initiated from the same site. While this may seem like the most secure option, it results in users being signed out if they navigate to the site from an external link. Since the cookie is omitted in cross-site requests, this leads to a poor user experience and is generally not recommended when using cookies for authentication. +- `Lax`: The cookie will be sent with HTTP requests initiated from the same site, and with direct navigations from a cross-site origin, but not with requests to load resources such as images or frames. This setting still protects against CSRF attacks without the poor user experience issues of `Strict`, where users are signed out when navigating from external links. `Lax` is the default setting in modern browsers and is recommended for most use cases. +- `None`: The browser will send cookies for both same-site and cross-site requests. While this setting allows for more flexibility in certain scenarios, it also increases the risk of CSRF attacks and therefore is not recommended. -Clerk sets the SameSite flag to _Lax_, which is the default in modern browsers. +Clerk sets the `SameSite` flag for all of its session cookies to `Lax`, which is the default in modern browsers. ## Do I need to take additional steps to prevent CSRF attacks? diff --git a/docs/security/password-protection.mdx b/docs/security/password-protection.mdx index 9f7909f23c..3e49d5f2ad 100644 --- a/docs/security/password-protection.mdx +++ b/docs/security/password-protection.mdx @@ -32,7 +32,7 @@ To configure this feature: 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active). 1. In the navigation sidenav, select **User & Authentication > Email, Phone, Username**. -1. In the **Authentication strategies** section, next to **Password**, select the settings cog icon. +1. In the **Authentication strategies** section, next to **Password**, select the settings icon. 1. You can enable or disable **Reject compromised passwords on sign-up or password change, powered by HaveIBeenPwned**. 1. You can also enable or disable **Reject compromised passwords also on sign-in**. Learn more about this feature in the following section. diff --git a/docs/testing/overview.mdx b/docs/testing/overview.mdx index e3fd423a24..c3d57f7197 100644 --- a/docs/testing/overview.mdx +++ b/docs/testing/overview.mdx @@ -14,7 +14,7 @@ To avoid sending an email or SMS message with a one time passcode (OTP) during t Testing Tokens allow you to bypass bot detection mechanisms that protect Clerk applications from malicious bots, ensuring your test suites run smoothly. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests. > [!NOTE] -> While you can manually implement the following logic in your test suite, Clerk provides [Playwright](/docs/testing/playwright) and [Cypress](/docs/testing/cypress) integrations that handle this automatically. +> While you can manually implement the following logic in your test suite, Clerk provides [Playwright](/docs/testing/playwright/overview) and [Cypress](/docs/testing/cypress) integrations that handle this automatically. Obtained via the [Backend API](/docs/reference/backend-api/tag/Testing-Tokens){{ target: '_blank' }}, Testing Tokens are short-lived and valid only for the specific instance for which they are issued. Testing Tokens are only available in development instances. diff --git a/docs/testing/playwright/overview.mdx b/docs/testing/playwright/overview.mdx new file mode 100644 index 0000000000..e65125b8ab --- /dev/null +++ b/docs/testing/playwright/overview.mdx @@ -0,0 +1,76 @@ +--- +title: Testing with Playwright +description: Use Playwright to write end-to-end tests with Clerk. +--- + +[Playwright](https://playwright.dev) is an open-source, end-to-end testing framework that automates web application testing across multiple browsers. This guide will help you set up your environment for creating authenticated tests with Clerk, assuming you have some familiarity with both Clerk and Playwright. + +> [!IMPORTANT] +> Check out the [demo repo](https://github.com/clerk/clerk-playwright-nextjs) that demonstrates testing a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). To run the tests, you'll need dev instance Clerk API keys, a test user with username and password, and have username and password authentication enabled in the Clerk Dashboard. + + + ### Install `@clerk/testing` + + Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command: + + + ```sh {{ filename: 'terminal' }} + npm i @clerk/testing --save-dev + ``` + + ```sh {{ filename: 'terminal' }} + yarn add -D @clerk/testing + ``` + + ```sh {{ filename: 'terminal' }} + pnpm add @clerk/testing -D + ``` + + + ### Set your API keys + + In your test runner, set your publishable and secret key as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively. + + To find your keys: + + 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys). + 1. In the top navbar, select **Configure**. In the sidebar, select **API Keys**. + 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. + + > [!WARNING] + > Ensure that the secret key is provided securely to prevent exposure to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). + + ### Configure Playwright with Clerk + + The `clerkSetup()` function obtains a Testing Token when your test suite starts, making it available for all subsequent tests to use. This ensures that you don't have to manually generate a Testing Token for each test. + + To configure Playwright with Clerk, call the `clerkSetup()` function in your [global setup file](https://playwright.dev/docs/test-global-setup-teardown), as shown in the following example: + + ```tsx {{ filename: 'global.setup.ts' }} + import { clerkSetup } from '@clerk/testing/playwright' + import { test as setup } from '@playwright/test' + + setup('global setup', async ({}) => { + await clerkSetup() + }) + ``` + + > [!NOTE] + > You can manually set the Testing Token by using the `CLERK_TESTING_TOKEN` environment variable instead of calling `clerkSetup()`. + + ### Use `setupClerkTestingToken()` + + Now that Playwright is configured with Clerk, you can use the `setupClerkTestingToken()` function to include the Testing Token in individual test cases. This function injects the Testing Token for the specific test, ensuring the test can bypass Clerk's bot detection mechanisms. See the following example: + + ```tsx {{ filename: 'my-test.spec.ts' }} + import { setupClerkTestingToken } from '@clerk/testing/playwright' + import { test } from '@playwright/test' + + test('sign up', async ({ page }) => { + await setupClerkTestingToken({ page }) + + await page.goto('/sign-up') + // Add additional test logic here + }) + ``` + diff --git a/docs/testing/playwright/test-authenticated-flows.mdx b/docs/testing/playwright/test-authenticated-flows.mdx new file mode 100644 index 0000000000..2bf3fe5a45 --- /dev/null +++ b/docs/testing/playwright/test-authenticated-flows.mdx @@ -0,0 +1,122 @@ +--- +title: Test authenticated flows +description: Learn how to test authenticated flows with Playwright. +--- + +Playwright executes tests in isolated environments called browser contexts. Because each test case runs in a new browser context, the user session is not shared between test cases by default. However, tests can load existing authenticated state. + +This guide demonstrates how to save the auth state globally and load it in your test cases, eliminating the need to authenticate in every test and speeding up test execution. Visit the [Playwright docs about authentication](https://playwright.dev/docs/auth) for more information. + +> [!IMPORTANT] +> Check out the [demo repo](https://github.com/clerk/clerk-playwright-nextjs) that demonstrates testing a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). To run the tests, you'll need dev instance Clerk API keys, a test user with username and password, and have username and password authentication enabled in the Clerk Dashboard. + + + ### Create a storage directory + + Create a `playwright/.clerk` directory and add it to your `.gitignore`. Once the auth state is generated, it will be stored to a file in this directory. Later on, tests will reuse this state and start already authenticated. + + ```sh {{ filename: 'terminal' }} + mkdir -p playwright/.clerk + echo $'\nplaywright/.clerk' >> .gitignore + ``` + + ### Prepare auth state for your tests + + Authenticate and save the auth state in your [global setup file](https://playwright.dev/docs/test-global-setup-teardown). + + This file: + + - Is executed before all projects. + - Calls [`clerkSetup()`](/docs/testing/playwright/overview#configure-playwright-with-clerk) to configure Playwright with Clerk. + - Calls `clerk.signIn()` to sign in a test user using credentials stored in environment variables. See the [reference](/docs/testing/playwright/test-helpers#clerk-sign-in) for more information about the different parameters you can pass. + - Checks if the user can access a protected page to ensure the user is successfully authenticated. + - Stores the auth state in the storage file. + + ```tsx {{ filename: 'global.setup.ts' }} + import { clerk, clerkSetup } from '@clerk/testing/playwright' + import { test as setup } from '@playwright/test' + import path from 'path' + + // Configure Playwright with Clerk + setup('global setup', async ({}) => { + await clerkSetup() + }) + + // Define the path to the storage file, which is `user.json` + const authFile = path.join(__dirname, '../playwright/.clerk/user.json') + + setup('authenticate and save state to storage', async ({ page }) => { + // Perform authentication steps. + // This example uses a Clerk helper to authenticate + await page.goto('/') + await clerk.signIn({ + page, + signInParams: { + strategy: 'password', + identifier: process.env.E2E_CLERK_USER_USERNAME!, + password: process.env.E2E_CLERK_USER_PASSWORD!, + }, + }) + await page.goto('/protected') + // Ensure the user has successfully accessed the protected page + // by checking an element on the page that only the authenticated user can access + await page.waitForSelector("h1:has-text('This is a PROTECTED page')") + + await page.context().storageState({ path: authFile }) + }) + ``` + + ### Load the stored auth state in your tests + + You can either load the stored auth state [in the config](#-in-the-config) or directly [in a test file](#-in-a-test-file). Loading in the config is useful if you want to authenticate once and reuse the same auth state for all tests or groups of tests. Loading in a test file is useful if you want to authenticate for a specific test case. + + #### In the config + + In your `playwright.config.ts`, create a `global setup` project and declare it as a [dependency](https://playwright.dev/docs/test-projects#dependencies) for all your testing projects. This means that the `global setup` project will always run before all the tests, and because it's where you prepared auth state, it will authenticate before all the tests. All testing projects should use the authenticated state as `storageState`. + + ```tsx {{ filename: 'playwright.config.ts' }} + // ... + projects: [ + { + name: 'global setup', + testMatch: /global\.setup\.ts/, + }, + { + name: 'Main tests', + testMatch: /.*app.spec.ts/, + use: { + ...devices['Desktop Chrome'], + }, + dependencies: ['global setup'], + }, + { + name: 'Authenticated tests', + testMatch: /.*authenticated.spec.ts/, + use: { + ...devices['Desktop Chrome'], + + // Use prepared Clerk auth state + storageState: 'playwright/.clerk/user.json', + }, + dependencies: ['global setup'], + }, + ] + ``` + + #### In a test file + + To use the stored auth state in a test file, see the following example: + + ```tsx {{ filename: 'authenticated.spec.ts', mark: [4, 5] }} + import { test } from '@playwright/test' + + // Use prepared Clerk auth state + test.use({ storageState: 'playwright/.clerk/user.json' }) + + test('user test', async ({ page }) => { + // page is authenticated + }) + ``` + + +For more information, feedback, or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package. diff --git a/docs/testing/playwright.mdx b/docs/testing/playwright/test-helpers.mdx similarity index 62% rename from docs/testing/playwright.mdx rename to docs/testing/playwright/test-helpers.mdx index 3115703fcc..c653b31220 100644 --- a/docs/testing/playwright.mdx +++ b/docs/testing/playwright/test-helpers.mdx @@ -1,82 +1,8 @@ --- -title: Testing with Playwright -description: Use Playwright to write end-to-end tests with Clerk. +title: Test helpers +description: Use test helpers to sign in/sign out with Clerk in your Playwright tests. --- -[Playwright](https://playwright.dev) is an open-source, end-to-end testing framework that automates web application testing across multiple browsers. This guide will help you set up your environment for creating authenticated tests with Clerk, assuming you have some familiarity with both Clerk and Playwright. - -> [!IMPORTANT] -> Check out the [demo repo](https://github.com/clerk/clerk-playwright-nextjs) that demonstrates testing a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens). To run the tests, you'll need dev instance keys, a test user with username and password, and have username and password authentication enabled in the Clerk Dashboard. - - - ### Install `@clerk/testing` - - Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command: - - - ```sh {{ filename: 'terminal' }} - npm i @clerk/testing --save-dev - ``` - - ```sh {{ filename: 'terminal' }} - yarn add -D @clerk/testing - ``` - - ```sh {{ filename: 'terminal' }} - pnpm add @clerk/testing -D - ``` - - - ### Set your API keys - - In your test runner, set your publishable and secret key as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables, respectively. - - To find your keys: - - 1. Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys). - 1. In the top navbar, select **Configure**. In the sidebar, select **API Keys**. - 1. In the **Quick Copy** section, copy your Clerk publishable and secret key. - - > [!WARNING] - > Ensure that the secret key is provided securely to prevent exposure to third parties. For example, if you are using GitHub Actions, refer to [_Using secrets in GitHub Actions_](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions). - - ### Configure Playwright with Clerk - - The `clerkSetup()` function obtains a Testing Token when your test suite starts, making it available for all subsequent tests to use. This ensures that you don't have to manually generate a Testing Token for each test. - - To configure Playwright with Clerk, call the `clerkSetup()` function in your [global setup file](https://playwright.dev/docs/test-global-setup-teardown), as shown in the following example: - - ```tsx {{ filename: 'global.setup.ts' }} - import { clerkSetup } from '@clerk/testing/playwright' - import { test as setup } from '@playwright/test' - - setup('global setup', async ({}) => { - await clerkSetup() - }) - ``` - - > [!NOTE] - > You can manually set the Testing Token by using the `CLERK_TESTING_TOKEN` environment variable instead of calling `clerkSetup()`. - - ### Use `setupClerkTestingToken()` - - Now that Playwright is configured with Clerk, you can use the `setupClerkTestingToken()` function to include the Testing Token in individual test cases. This function injects the Testing Token for the specific test, ensuring the test can bypass Clerk's bot detection mechanisms. See the following example: - - ```tsx {{ filename: 'my-test.spec.ts' }} - import { setupClerkTestingToken } from '@clerk/testing/playwright' - import { test } from '@playwright/test' - - test('sign up', async ({ page }) => { - await setupClerkTestingToken({ page }) - - await page.goto('/sign-up') - // Add additional test logic here - }) - ``` - - -## Test Helpers - The `@clerk/testing` package also provides some helper functions to sign in/sign out with Clerk in your Playwright tests without having to interact with the UI. To use these commands, import the `clerk` object from the `@clerk/testing/playwright` package. @@ -272,5 +198,3 @@ test('ensure that clerk has loaded', async ({ page }) => { // clerk has loaded }) ``` - -For more information, feedback, or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package.