From 50a41ae88b5b9cdc617cfd0299d190985b0f4fb3 Mon Sep 17 00:00:00 2001 From: victoria Date: Thu, 19 Sep 2024 18:33:12 +0200 Subject: [PATCH] update advanced guides with warnings on when and how to use (#1549) --- docs/advanced-usage/clerk-idp.mdx | 14 +++++++++++--- docs/advanced-usage/satellite-domains.mdx | 6 ++++-- docs/advanced-usage/using-proxies.mdx | 3 +++ docs/deployments/overview.mdx | 5 +++++ docs/organizations/metadata.mdx | 3 +++ 5 files changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/advanced-usage/clerk-idp.mdx b/docs/advanced-usage/clerk-idp.mdx index db523bb00f..f4209e03fe 100644 --- a/docs/advanced-usage/clerk-idp.mdx +++ b/docs/advanced-usage/clerk-idp.mdx @@ -4,11 +4,19 @@ description: Learn how to use Clerk to facilitate Single Sign-On (SSO) with othe --- > [!WARNING] -> This feature will not return a Clerk JWT and does not provide authentication. Please see the [FAQ](#how-can-the-access-tokens-obtained-from-the-token-url-be-used) below for more information. +> **This feature is not designed for handling authentication directly in your application.** To handle authentication _in your_ application, you can [configure one of the many OAuth providers that Clerk offers](/docs/authentication/social-connections/oauth#configuration), such as Google. -Clerk can be configured as an identity provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. With this feature, your users can sign in with your Clerk application on other websites to authorize sharing of their user info. +Clerk can be configured as an identity provider to facilitate Single Sign-On (SSO) with other clients that support the OAuth 2.0 protocol. This feature allows users to sign in to other applications using their Clerk credentials, enabling user information sharing between your Clerk application and external websites. -![Clerk IDP Flow](/docs/images/advance/clerk-idp-flow.svg) +## When should you use Clerk as an OAuth provider? + +You can use Clerk as an OAuth provider if you want your users to sign in to a third party site or a tool using their credentials from your application. **This is not the same as supporting an OAuth provider, such as Google, in your application. If you want your users to be able to sign in to your application with an OAuth provider, see [the dedicated guide](/docs/authentication/social-connections/oauth#configuration).** + +## How it works + +The following diagram shows the flow for using Clerk as an OAuth provider. + +![Diagram of the Clerk as an IdP flow](/docs/images/advance/clerk-idp-flow.svg) ### Retrieve callback URL from the client application diff --git a/docs/advanced-usage/satellite-domains.mdx b/docs/advanced-usage/satellite-domains.mdx index 1b4b785bb4..1c8cc3aa9a 100644 --- a/docs/advanced-usage/satellite-domains.mdx +++ b/docs/advanced-usage/satellite-domains.mdx @@ -3,8 +3,10 @@ title: Authentication across different domains description: Learn how to share sessions across different domains by adding satellite domains to your application. --- -> [!IMPORTANT] -> This guide addresses authentication across different domains with shared sessions, for example `example-site.com` and `example-site-admin.com`. Authentication across subdomains with shared sessions works by default with Clerk. +> [!WARNING] +> This guide addresses authentication across different domains with shared sessions. For example, `example-site.com` and `example-site-admin.com`. +> +> [Authentication across subdomains](/docs/deployments/overview#authentication-across-subdomains) with shared sessions works by default with Clerk. Clerk supports sharing sessions across different domains by adding one or many satellite domains to an application. diff --git a/docs/advanced-usage/using-proxies.mdx b/docs/advanced-usage/using-proxies.mdx index 1f7d32df39..8c5d3cd26e 100644 --- a/docs/advanced-usage/using-proxies.mdx +++ b/docs/advanced-usage/using-proxies.mdx @@ -3,6 +3,9 @@ title: Proxying the Clerk Frontend API description: Learn how to proxy the Clerk Frontend API through your domain. --- +> [!WARNING] +> This guide is for users who need to proxy Clerk's Frontend API for deployment. If your application already uses a CNAME subdomain that is required for deploying with Clerk, then you must proxy Clerk's API using a different subdomain. Refer to [the Clerk deployment guide](/docs/deployments/overview#dns-records) on how to configure DNS records for deployment. + Clerk supports two configuration methods for connecting to the Clerk Frontend API: CNAME and Proxy. The recommended way to connect to the Clerk Frontend API is to [set up CNAME records and use DNS](/docs/deployments/overview). However, if you're unable to use this approach, or would like more control over your integration with Clerk, you can use a proxy. diff --git a/docs/deployments/overview.mdx b/docs/deployments/overview.mdx index 965e6a1789..7dca5abf37 100644 --- a/docs/deployments/overview.mdx +++ b/docs/deployments/overview.mdx @@ -52,6 +52,11 @@ To see what DNS records you need to add: When you set a root domain for your production deployment, Clerk's authentication will work across all subdomains. User sessions will also be shared across the subdomains. +**Examples** + +- `example-site.com` and `dashboard.example-site.com` +- `dashboard.example-site.com` and `accounts.example-site.com` + To share sessions and authentication across two different domains with the same Clerk application, see the [Authentication across different domains guide](/docs/advanced-usage/satellite-domains). ## Deploy certificates diff --git a/docs/organizations/metadata.mdx b/docs/organizations/metadata.mdx index 7a7b5b1710..1eb9bcb24d 100644 --- a/docs/organizations/metadata.mdx +++ b/docs/organizations/metadata.mdx @@ -3,6 +3,9 @@ title: Organization metadata description: Organization objects hold a set of metadata that can be used internally to store arbitrary information. --- +> [!CAUTION] +> This guide is for users who want to build a _custom_ user interface using the Clerk API. To create organizations using a _prebuilt_ UI, you should use Clerk's [prebuilt components](/docs/components/overview). + Organization metadata allows you to store information about an organization that is not part of the standard fields, such as custom attributes that are specific to your application. There are two types of metadata: **public** and **private**.