SAML Connections

Custom flow

In case our default SAML flow doesn’t cover your needs, you can leverage the Clerk SDK to build a completely custom SAML flow.

You still need to configure your instance through the Clerk Dashboard by following this link to your Enterprise Connections.

When using SAML, the sign in and sign up are equivalent. A successful SAML flow consists of the following steps:

Start the OAuth flow by calling SignIn.authenticateWithRedirect(params) or SignUp.authenticateWithRedirect(params). Note that 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.
Create a route at the URL redirectUrl points, typically /sso-callback, that calls the Clerk.handleRedirectCallback() or simply renders the prebuilt <AuthenticateWithRedirectCallback/> component.

The React example below uses react-router-dom to define the required route. For NextJS apps, you only need to create a pages/sso-callback file.

1
import React from "react";
2
import {
3
  BrowserRouter,
4
  Switch,
5
  Route,
6
} from "react-router-dom";
7
import { SamlStrategy } from "@clerk/types";
8
import {
9
  ClerkProvider,
10
  ClerkLoaded,
11
  AuthenticateWithRedirectCallback,
12
  UserButton,
13
  useSignIn,
14
  SignedIn,
15
  SignedOut
16
} from "@clerk/clerk-react";
17

18
function App() {
19
  return (
20
    //  react-router-dom requires your app to be wrapped with a Router
21
    <BrowserRouter>
22
      <ClerkProvider frontendApi="{{fapi}}">
23
        <Switch>
24
          {/* Define a / route that displays the OAuth buttons */}
25
          <Route path="/">
26
            <SignedOut>
27
							<SignInSAMLButton />
28
            </SignedOut>
29
            <SignedIn>
30
              <UserButton afterSignOutAllUrl="/" />
31
            </SignedIn>
32
          </Route>
33
         
34
           {/* Define a /sso-callback route that handles the SAML redirect flow from the IdP */}
35
          <Route path="/sso-callback">
36
            <SSOCallback />
37
          </Route>
38
        </Switch>
39
      </ClerkProvider>
40
    </BrowserRouter>
41
  );
42
}
43

44
function SSOCallback() {
45
  // Handle the redirect flow by rendering the
46
  // prebuilt AuthenticateWithRedirectCallback component.
47
  // This is the final step in the custom SAML flow
48
  return <AuthenticateWithRedirectCallback />;
49
}
50

51
function SignInSAMLButton() {
52
  const { signIn } = useSignIn();
53

54
  const signInWith = (strategy: SamlStrategy) => {
55
    return signIn.authenticateWithRedirect({
56
		  identifier: "email_goes_here",
57
		  strategy: strategy,
58
		  redirectUrl: "/sso-callback",
59
		  redirectUrlComplete: "/",
60
    });
61
  };
62

63
  // Render a button for each supported SAML provider
64
  // you want to add to your app
65
  return (
66
    <div>
67
      <button onClick={() => signInWith("saml")}>
68
        Sign in with SAML
69
      </button>
70
    </div>
71
  );
72
}
73

74
export default App;

To initiate a SAMLflow for a user that is already signed in, you can use the user.createExternalAccount(params) method, where user is a reference to the currently signed in user.

1
user
2
      .createExternalAccount({ strategy: strategy, redirect_url: 'your-redirect-url' })
3
      .then(externalAccount => {
4
        // navigate to
5
        // externalAccount.verification!.externalVerificationRedirectURL
6
      })
7
      .catch(err => {
8
        // handle error
9
      });

SAML account transfer flow

When a user initiates a SAML SSO verification during sign-in, or sign-up, it may sometimes be necessary to move the verification between the two flows.

For example: if someone already has an account, and tries to go through the sign up flow with the same SAML account, they can’t perform a successful sign up again. Or, if someone attempts to sign in with their SAML credentials but does not yet have an account, they won’t be signed in to the account. For these scenarios we have “account transfers.”

1
// Get sign-in and sign-up objects in the SAML callback page
2
const { signIn, signUp } = window.Clerk.client;
3

4
// If the user has an account in your application, but does not yet 
5
// have a saml account connected, you can use the transfer method to 
6
// forward that information.
7

8
const userExistsButNeedsToSignIn =
9
  signUp.verifications.externalAccount.status === "transferable" &&
10
  signUp.verifications.externalAccount.error?.code ===
11
    "external_account_exists";
12

13
if (userExistsButNeedsToSignIn) {
14
  const res = await signIn.create({ transfer: true });
15
  if (res.status === "complete") {
16
    window.Clerk.setActive({
17
      session: res.createdSessionId,
18
    });
19
  }
20
}
21

22
// If the user has an existing saml account but does not yet exist as 
23
// a user in your app, you can use the transfer method to forward that 
24
// information.
25

26
const userNeedsToBeCreated =
27
  signIn.firstFactorVerification.status === "transferable";
28

29
if (userNeedsToBeCreated) {
30
  const res = await signUp.create({
31
    transfer: true,
32
  });
33
  if (res.status === "complete") {
34
    window.Clerk.setActive({
35
      session: res.createdSessionId,
36
    });
37
  }
38
}