From c1613821a26ebac8c42569c1bcdaf202a08d15fc Mon Sep 17 00:00:00 2001 From: Nikos Polykandriotis Date: Wed, 4 Dec 2024 16:20:12 +0200 Subject: [PATCH] Add docs for enterprise_sso and update examples --- ...ections.mdx => enterprise-connections.mdx} | 48 +++++++++---------- docs/manifest.json | 4 +- .../javascript/sign-in/authenticate-with.mdx | 15 +++++- .../javascript/sign-up/authenticate-with.mdx | 9 ++-- .../javascript/sign-up/verification.mdx | 5 +- 5 files changed, 47 insertions(+), 34 deletions(-) rename docs/custom-flows/{saml-connections.mdx => enterprise-connections.mdx} (67%) diff --git a/docs/custom-flows/saml-connections.mdx b/docs/custom-flows/enterprise-connections.mdx similarity index 67% rename from docs/custom-flows/saml-connections.mdx rename to docs/custom-flows/enterprise-connections.mdx index e062065c88..c30f3213bc 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)`](/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. 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 EnterpriseSSOSignIn() { 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)}> - +
) } @@ -72,7 +72,7 @@ The following example shows two files: export default function SSOCallback() { // 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,9 +80,9 @@ 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.** @@ -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 EnterpriseSSOSignIn() { 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,15 +160,15 @@ 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)}> - +
) } diff --git a/docs/manifest.json b/docs/manifest.json index 89b2f99a8c..638499d407 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..38f881a511 100644 --- a/docs/references/javascript/sign-in/authenticate-with.mdx +++ b/docs/references/javascript/sign-in/authenticate-with.mdx @@ -19,9 +19,13 @@ 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** + - `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. --- @@ -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 a 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 8f2f746c29..3a158050a8 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 a 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 a 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..44d5bf1445 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** + - `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.