From 06da5f172e695b0e424c05353c00874366257f2c Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Tue, 10 Dec 2024 11:24:07 +0200 Subject: [PATCH] Add docs for enterprise_sso and update examples (#1770) Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> --- ...ections.mdx => enterprise-connections.mdx} | 56 ++++++++++--------- docs/manifest.json | 4 +- .../javascript/sign-in/authenticate-with.mdx | 17 +++++- .../javascript/sign-up/authenticate-with.mdx | 9 +-- .../javascript/sign-up/verification.mdx | 5 +- .../javascript/types/verification.mdx | 2 +- 6 files changed, 55 insertions(+), 38 deletions(-) rename docs/custom-flows/{saml-connections.mdx => enterprise-connections.mdx} (64%) diff --git a/docs/custom-flows/saml-connections.mdx b/docs/custom-flows/enterprise-connections.mdx similarity index 64% rename from docs/custom-flows/saml-connections.mdx rename to docs/custom-flows/enterprise-connections.mdx index e062065c88..dd0135cdb6 100644 --- a/docs/custom-flows/saml-connections.mdx +++ b/docs/custom-flows/enterprise-connections.mdx @@ -1,25 +1,25 @@ --- -title: Build a custom flow for authenticating with SAML connections -description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports OAuth connections. +title: Build a custom flow for authenticating with enterprise connections +description: Learn how to use the Clerk API to build a custom sign-up and sign-in flow that supports enterprise connections. --- ## Before you start -You must configure your application instance through the Clerk Dashboard for the SAML connection(s) that you want to use. Visit [the appropriate SAML guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. +You must configure your application instance through the Clerk Dashboard for the enterprise connection(s) that you want to use. Visit [the appropriate guide for your platform](/docs/authentication/enterprise-connections/overview) to learn how to configure your instance. ## Create the sign-up and sign-in flow -When using SAML, the sign-in and sign-up flows are equivalent. A successful SAML flow consists of the following steps: +When using Enterprise SSO, the sign-in and sign-up flows are equivalent. A successful Enterprise SSO flow consists of the following steps: -1. Start the SAML flow by calling [`SignIn.authenticateWithRedirect(params)`](/docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect) or [`SignUp.authenticateWithRedirect(params)`](/docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect). Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider. +1. Start the Enterprise SSO flow by calling [`SignIn.authenticateWithRedirect(params)`][sign-in-redirect] or [`SignUp.authenticateWithRedirect(params)`][sign-up-redirect]. Both of these methods require a `redirectUrl` param, which is the URL that the browser will be redirected to once the user authenticates with the identity provider. 1. Create a route at the URL that the `redirectUrl` param points to. The following example names this route `/sso-callback`. This route should either call the [`Clerk.handleRedirectCallback()`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) method or render the prebuilt [``](/docs/components/control/authenticate-with-callback) component. The following example shows two files: -1. The sign-in page where the user can start the SAML flow. -1. The SSO callback page where the SAML flow is completed. +1. The sign-in page where the user can start the Enterprise SSO flow. +1. The SSO callback page where the flow is completed. @@ -30,13 +30,13 @@ The following example shows two files: import * as React from 'react' import { useSignIn, useSignUp } from '@clerk/nextjs' - export default function SAMLSignIn() { + export default function Page() { const { signIn } = useSignIn() const { signUp } = useSignUp() if (!signIn || !signUp) return null - const signInWithSAML = (e: React.FormEvent) => { + const signInWithEnterpriseSSO = (e: React.FormEvent) => { e.preventDefault() const email = (e.target as HTMLFormElement).email.value @@ -44,7 +44,7 @@ The following example shows two files: signIn .authenticateWithRedirect({ identifier: email, - strategy: 'saml', + strategy: 'enterprise_sso', redirectUrl: '/sso-callback', redirectUrlComplete: '/', }) @@ -58,9 +58,9 @@ The following example shows two files: } return ( -
signInWithSAML(e)}> + signInWithEnterpriseSSO(e)}> - +
) } @@ -69,10 +69,10 @@ The following example shows two files: ```jsx {{ filename: 'app/sign-up/sso-callback/page.tsx' }} import { AuthenticateWithRedirectCallback } from '@clerk/nextjs' - export default function SSOCallback() { + export default function Page() { // Handle the redirect flow by rendering the // prebuilt AuthenticateWithRedirectCallback component. - // This is the final step in the custom SAML flow. + // This is the final step in the custom Enterprise SSO flow. return } ``` @@ -80,13 +80,13 @@ The following example shows two files: -## SAML account transfer flows +## Enterprise account transfer flows -It is common for users who are authenticating with SAML to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow. +It is common for users who are authenticating with an enterprise account to use a sign-in button when they mean to sign-up, and vice versa. For those cases, the `SignIn` and `SignUp` objects have a `transferable` status that indicates whether the user can be transferred to the other flow. **If you would like to keep your sign-in and sign-up flows completely separate, then you can skip this section.** -The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace `signIn.authenticateWithRedirect()` with `signUp.authenticateWithRedirect()` in your code. +The following example demonstrates how to handle these cases in your sign-in flow. To apply the same logic to the sign-up flow, simply replace [`signIn.authenticateWithRedirect()`][sign-in-redirect] with [`signUp.authenticateWithRedirect()`][sign-up-redirect] in your code. @@ -96,13 +96,13 @@ The following example demonstrates how to handle these cases in your sign-in flo import * as React from 'react' import { useSignIn, useSignUp } from '@clerk/nextjs' - export default function SAMLSignIn() { + export default function Page() { const { signIn } = useSignIn() const { signUp, setActive } = useSignUp() if (!signIn || !signUp) return null - const signInWithSAML = (e: React.FormEvent) => { + const signInWithEnterpriseSSO = (e: React.FormEvent) => { e.preventDefault() const email = (e.target as HTMLFormElement).email.value @@ -110,7 +110,7 @@ The following example demonstrates how to handle these cases in your sign-in flo signIn .authenticateWithRedirect({ identifier: email, - strategy: 'saml', + strategy: 'enterprise_sso', redirectUrl: '/sso-callback', redirectUrlComplete: '/', }) @@ -127,7 +127,7 @@ The following example demonstrates how to handle these cases in your sign-in flo if (!signIn || !signUp) return null // If the user has an account in your application, but does not yet - // have a SAML account connected to it, you can transfer the SAML + // have a enterprise account connected to it, you can transfer the enterprise // account to the existing user account. const userExistsButNeedsToSignIn = signUp.verifications.externalAccount.status === 'transferable' && @@ -143,9 +143,9 @@ The following example demonstrates how to handle these cases in your sign-in flo } } - // If the user has a SAML account but does not yet + // If the user has a enterprise account but does not yet // have an account in your app, you can create an account - // for them using the SAML information. + // for them using the enterprise account's information. const userNeedsToBeCreated = signIn.firstFactorVerification.status === 'transferable' if (userNeedsToBeCreated) { @@ -160,18 +160,22 @@ The following example demonstrates how to handle these cases in your sign-in flo } } else { // If the user has an account in your application - // and has an SAML account connected to it, you can sign them in. - signInWithSAML(e) + // and has an enterprise account connected to it, you can sign them in. + signInWithEnterpriseSSO(e) } } return (
handleSignIn(e)}> - +
) } ``` + +[sign-in-redirect]: /docs/references/javascript/sign-in/authenticate-with#authenticate-with-redirect + +[sign-up-redirect]: /docs/references/javascript/sign-up/authenticate-with#authenticate-with-redirect diff --git a/docs/manifest.json b/docs/manifest.json index 1952a20efe..7f84702730 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1673,8 +1673,8 @@ "href": "/docs/custom-flows/oauth-connections" }, { - "title": "SAML connections", - "href": "/docs/custom-flows/saml-connections" + "title": "Enterprise connections", + "href": "/docs/custom-flows/enterprise-connections" }, { "title": "Sign out", diff --git a/docs/references/javascript/sign-in/authenticate-with.mdx b/docs/references/javascript/sign-in/authenticate-with.mdx index bd7949b32c..f54ad008f2 100644 --- a/docs/references/javascript/sign-in/authenticate-with.mdx +++ b/docs/references/javascript/sign-in/authenticate-with.mdx @@ -19,16 +19,20 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi - `strategy` - - [OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' + - [OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' | 'enterprise\_sso' - The strategy corresponding to the OAuth provider. For example: `oauth_facebook`, `oauth_github`, etc. + The strategy to use for authentication. The following strategies are supported: + + - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). + - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. --- - `redirectUrl` - `string` - Full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `` component. + The full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `` component. --- @@ -36,6 +40,13 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi - `string` The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in. + + --- + + - `identifier` + - `string | undefined` + + Identifier to use for targeting an enterprise connection at sign-in. ### `authenticateWithMetamask()` diff --git a/docs/references/javascript/sign-up/authenticate-with.mdx b/docs/references/javascript/sign-up/authenticate-with.mdx index c98405e5ad..3b20ac50ff 100644 --- a/docs/references/javascript/sign-up/authenticate-with.mdx +++ b/docs/references/javascript/sign-up/authenticate-with.mdx @@ -38,26 +38,27 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi --- - `strategy` - - `'oauth_' | 'saml'` + - `'oauth_' | 'saml' | 'enterprise_sso'` The strategy to use for authentication. The following strategies are supported: - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). - - `saml`: The user will be authenticated with SAML. + - `saml`: The user will be authenticated with SAML. **Deprecated** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. --- - `identifier` - `string | undefined` - Identifier to use for targeting a SAML connection at sign-up. + Identifier to use for targeting an enterprise connection at sign-up. --- - `emailAddress` - `string | undefined` - Email address to use for targeting a SAML connection at sign-up. + Email address to use for targeting an enterprise connection at sign-up. --- diff --git a/docs/references/javascript/sign-up/verification.mdx b/docs/references/javascript/sign-up/verification.mdx index 7a15cb0e2c..9c1c158aec 100644 --- a/docs/references/javascript/sign-up/verification.mdx +++ b/docs/references/javascript/sign-up/verification.mdx @@ -20,14 +20,15 @@ function prepareVerification(params: PrepareVerificationParams): Promise - `strategy` - - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'oauth_' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'` + - `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'enterprise_sso' | 'oauth_' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'` The verification strategy to validate the user's sign-up request. The following strategies are supported: - `phone_code`: Send an SMS with a unique token to input. - `email_code`: Send an email with a unique token to input. - `email_link`: Send an email with a link which validates sign-up - - `saml`: The user will be authenticated with SAML. **Experimental** + - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.** + - `enterprise_sso`: The user will be authenticated either through SAML or OIDC depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier. - `oauth_`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider). - `web3_metamask_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Metamask](https://metamask.io/). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. - `web3_coinbase_wallet_signature`: The verification will attempt to be completed using the user's Web3 wallet address via [Coinbase Wallet](https://www.coinbase.com/wallet). The `web3_wallet_id` parameter can also be specified to select which of the user's known Web3 wallets will be used. diff --git a/docs/references/javascript/types/verification.mdx b/docs/references/javascript/types/verification.mdx index c0955b8f32..432df00c99 100644 --- a/docs/references/javascript/types/verification.mdx +++ b/docs/references/javascript/types/verification.mdx @@ -48,7 +48,7 @@ An interface that represents the state of the verification process of a sign-in - `unverified`: The verification has not been verified yet. - `verified`: The verification has been verified. - - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [SAML](/docs/custom-flows/saml-connections#saml-account-transfer-flows) authentication flows. + - `transferable`: The verification is transferable to between sign-in and sign-up flows. This status is to be used in [OAuth](/docs/custom-flows/oauth-connections#o-auth-account-transfer-flows) and [Enterprise SSO](/docs/custom-flows/enterprise-connections#enterprise-account-transfer-flows) authentication flows. - `failed`: The verification has failed. - `expired`: The verification has expired.