Skip to content

Commit

Permalink
Add docs for enterprise_sso and update examples (#1770)
Browse files Browse the repository at this point in the history
Co-authored-by: Alexis Aguilar <[email protected]>
  • Loading branch information
2 people authored and royanger committed Dec 16, 2024
1 parent 7629028 commit c79de6d
Show file tree
Hide file tree
Showing 6 changed files with 55 additions and 38 deletions.
Original file line number Diff line number Diff line change
@@ -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.
---

<Include src="_partials/custom-flows-callout" />

## 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 [`<AuthenticateWithRedirectCallback/>`](/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.

<Tabs items={["Next.js"]}>
<Tab>
Expand All @@ -30,21 +30,21 @@ 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

signIn
.authenticateWithRedirect({
identifier: email,
strategy: 'saml',
strategy: 'enterprise_sso',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
Expand All @@ -58,9 +58,9 @@ The following example shows two files:
}

return (
<form onSubmit={(e) => signInWithSAML(e)}>
<form onSubmit={(e) => signInWithEnterpriseSSO(e)}>
<input type="email" name="email" placeholder="Enter email address" />
<button>Sign in with SAML</button>
<button>Sign in with Enterprise SSO</button>
</form>
)
}
Expand All @@ -69,24 +69,24 @@ 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 <AuthenticateWithRedirectCallback />
}
```
</CodeBlockTabs>
</Tab>
</Tabs>

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

<Tabs items={["Next.js"]}>
<Tab>
Expand All @@ -96,21 +96,21 @@ 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

signIn
.authenticateWithRedirect({
identifier: email,
strategy: 'saml',
strategy: 'enterprise_sso',
redirectUrl: '/sso-callback',
redirectUrlComplete: '/',
})
Expand All @@ -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' &&
Expand All @@ -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) {
Expand All @@ -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 (
<form onSubmit={(e) => handleSignIn(e)}>
<input type="email" name="email" placeholder="Enter email address" />
<button>Sign in with SAML</button>
<button>Sign in with Enterprise SSO</button>
</form>
)
}
```
</Tab>
</Tabs>

[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
4 changes: 2 additions & 2 deletions docs/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
17 changes: 14 additions & 3 deletions docs/references/javascript/sign-in/authenticate-with.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,23 +19,34 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi

<Properties>
- `strategy`
- <code>[OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml'</code>
- <code>[OAuthStrategy](/docs/references/javascript/types/oauth#o-auth-strategy) | 'saml' | 'enterprise\_sso'</code>

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_<provider>`: 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 `<AuthenticateWithRedirectCallback />` 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 `<AuthenticateWithRedirectCallback />` component.

---

- `redirectUrlComplete`
- `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.
</Properties>

### `authenticateWithMetamask()`
Expand Down
9 changes: 5 additions & 4 deletions docs/references/javascript/sign-up/authenticate-with.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,26 +38,27 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
---

- `strategy`
- `'oauth_<provider>' | 'saml'`
- `'oauth_<provider>' | 'saml' | 'enterprise_sso'`

The strategy to use for authentication. The following strategies are supported:

- `oauth_<provider>`: 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.

---

Expand Down
5 changes: 3 additions & 2 deletions docs/references/javascript/sign-up/verification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,15 @@ function prepareVerification(params: PrepareVerificationParams): Promise<SignUpR

<Properties>
- `strategy`
- `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'oauth_<provider>' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature'`
- `'phone_code' | 'email_code' | 'email_link' | 'saml' | 'enterprise_sso' | 'oauth_<provider>' | '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_<provider>`: 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.
Expand Down
2 changes: 1 addition & 1 deletion docs/references/javascript/types/verification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit c79de6d

Please sign in to comment.