> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding SSO to a custom auth flow

> Integrate SSO with Stytch's headless or backend SDKs for complete control over your authentication flow.

## Authentication flow

```mermaid theme={null}
sequenceDiagram
    participant Browser
    participant App as Your Application Logic
    participant Stytch
    participant IDP as Workflow Idp

    Browser->>App: User initiates SSO login
    App->>Stytch: Call sso.start()
    Stytch-->>App: Returns redirect URL
    App-->>Browser: Follow redirect URL
    Browser->>IDP: Redirects to IdP
    IDP<<-->>Browser: User authenticates with IdP
    IDP<<-->>Stytch: Stytch performs SSO handshake with IdP
    Stytch-->>Browser: Redirect to Login or Signup Redirect URL with token
    Browser-->>App: Extract sso_token from URL
    App->>Stytch: Call sso.authenticate() with sso_token
    Stytch->>App: Member logged in<br/>Returns Member info & Session
```

***

> [!NOTE]
>
> Before you begin, make sure you've completed the [SSO provider setup steps](https://stytch.com/docs/multi-tenant-auth/authentication/sso/provider-setup.md).

## Overview

> [tab] Headless frontend SDK
>
> This guide walks through integrating SSO using Stytch's headless frontend SDKs. This approach gives you complete control over your UI while handling authentication logic on the frontend.
>
> Both Discovery (Centralized login flow that allows users to view all Organizations they have access to, including pending invites and Organizations they are allowed to automatically join based on their verified email domain.) and Organization-specific authentication flows are supported.
>
> > [tab] Discovery authentication
> >
> > The Discovery flow is designed for situations where end users are signing up or logging in from a central landing page, and have not specified which Organization (Represents an instance or tenant in your application, typically mapping to each of your top-level customers.) they are trying to access.
> >
> > ### Prerequisites
> >
> > 1. Complete the steps in the [SSO provider setup guide](https://stytch.com/docs/multi-tenant-auth/authentication/sso/provider-setup.md)
> > 2. Enable the Frontend SDKs in [your Stytch Dashboard](https://stytch.com/dashboard/sdk-configuration)
> >
> > ### Implementation
> >
> > **1. Discover available SSO Connections**
> >
> > If you have a centralized login page, prompt the user for their email and call `sso.discoverConnections`.
> >
> > ```jsx React icon="react" theme={null}
> > import { useStytchB2BClient } from '@stytch/react/b2b';
> >
> > export const SSOConnectionsDiscovery = () => {
> >   const stytch = useStytchB2BClient();
> >
> >   const discoverSSOConnections = (email) => {
> >     stytch.sso.discoverConnections(email);
> >   };
> >
> >   return <button onClick={() => discoverSSOConnections(email)}>Continue</button>;
> > };
> > ```
> >
> > The `sso.discoverConnections()` method returns an array of SSO Connections. Use the `display_name` and `idp_type` to render the available options, then pass the selected `connection_id` into the next step.
> >
> > **2. Start the SSO flow**
> >
> > Use the selected `connection_id` to initiate the SSO flow.
> >
> > ```jsx React icon="react" theme={null}
> > import { useStytchB2BClient } from '@stytch/react/b2b';
> >
> > export const Login = ({ connectionId }) => {
> >   const stytchClient = useStytchB2BClient();
> >
> >   const startSSO = () =>
> >     stytchClient.sso.start({
> >       connection_id: connectionId,
> >     });
> >
> >   return <button onClick={startSSO}>Log in with SSO</button>;
> > };
> > ```
> >
> > ```html Vanilla JS icon="square-js" theme={null}
> > <script type="module">
> >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> >   const stytch = new StytchB2BHeadlessClient('PUBLIC_TOKEN');
> >
> >   document.getElementById('login-with-sso').onclick = () => stytch.sso.start({
> >     connection_id: 'saml-connection-test-51861cbc-d3b9-428b-9761-227f5fb12be9',
> >   });
> > </script>
> >
> > <button id="login-with-sso">Login with SSO</button>
> > ```
> >
> > The user will be redirected to their IdP to authenticate.
> >
> > **3. Handle the SSO callback**
> >
> > After the SSO handshake, Stytch redirects to your Login or Signup Redirect URL with a token in the URL. Call `sso.authenticate` to finish the login process.
> >
> > ```jsx React icon="react" theme={null}
> > import { useEffect } from 'react';
> > import { useStytchB2BClient, useStytchMemberSession } from '@stytch/react/b2b';
> >
> > export const Authenticate = () => {
> >   const stytchClient = useStytchB2BClient();
> >   const { session } = useStytchMemberSession();
> >
> >   useEffect(() => {
> >     if (session) {
> >       window.location.href = 'https://example.com/profile';
> >     } else {
> >       const token = new URLSearchParams(window.location.search).get('token');
> >       stytchClient.sso.authenticate({
> >         sso_token: token,
> >       });
> >     }
> >   }, [stytchClient, session]);
> >
> >   return <div>Loading</div>;
> > };
> > ```
> >
> > ```html Vanilla JS icon="square-js" theme={null}
> > <script>
> >   import { StytchB2BHeadlessClient } from '@stytch/vanilla-js/b2b/headless';
> >   const stytch = new StytchB2BHeadlessClient('PUBLIC_TOKEN');
> >
> >   const token = new URLSearchParams(window.location.search).get('token');
> >   stytch.sso.authenticate({
> >     sso_token: token
> >   });
> > </script>
> > ```
> >
> > The Stytch frontend SDK will store `stytch_session_token` and `stytch_session_jwt` in cookies for you. See [session cookie management](https://stytch.com/docs/api-reference/b2b/frontend-sdks/vanilla-js/resources/cookies-and-session-management.md).
>
> > [tab] Organization-specific authentication
> >
> > If end users login via a page that indicates which Organization they're trying to access (e.g., `<org-slug>.your-app.com` or `your-app.com/team/<org-slug>`), you can offer Organization-specific authentication.
> >
> > ### Prerequisites
> >
> > 1. Complete the steps in the [SSO provider setup guide](https://stytch.com/docs/multi-tenant-auth/authentication/sso/provider-setup.md), including creating an Organization.
> > 2. Enable the Frontend SDKs in [your Stytch Dashboard](https://stytch.com/dashboard/sdk-configuration)
> >
> > ### Implementation
> >
> > **1. Fetch Organization SSO Connections**
> >
> > Use the Organization slug to fetch SSO Connections and render them in your UI.
> >
> > ```jsx React icon="react" theme={null}
> > import { useEffect, useState } from 'react';
> > import { useStytchB2BClient } from '@stytch/react/b2b';
> >
> > export const OrganizationLoginPage = ({ slug }) => {
> >   const stytch = useStytchB2BClient();
> >   const [organization, setOrganization] = useState();
> >   useEffect(() => {
> >     stytch.organization
> >       .getBySlug({ organization_slug: slug })
> >       .then((response) => setOrganization(response.organization));
> >   }, [stytch, slug]);
> >
> >   if (organization === undefined) {
> >     return <p>Loading...</p>;
> >   }
> >
> >   if (!organization) {
> >     return <p>No organization found for {slug}</p>;
> >   }
> >
> >   const ssoConnections = organization.sso_active_connections;
> >
> >   // render UI
> > };
> > ```
> >
> > **2. Start the SSO flow**
> >
> > Call `sso.start()` using the selected `connection_id`.
> >
> > ```jsx React icon="react" theme={null}
> > import { useStytchB2BClient } from '@stytch/react/b2b';
> >
> > export const Login = ({ organization }) => {
> >   const stytchClient = useStytchB2BClient();
> >
> >   const startSSO = (connectionId) =>
> >     stytchClient.sso.start({
> >       connection_id: connectionId,
> >     });
> >
> >   return <button onClick={() => startSSO(organization.default_connection_id)}>Log in with SSO</button>;
> > };
> > ```
> >
> > **3. Handle the SSO callback**
> >
> > Stytch will redirect the user to the Login or Signup Redirect URL. Extract the token from the URL and call the authentication method to finish the login process.
> >
> > ```jsx React icon="react" theme={null}
> > import { useEffect } from 'react';
> > import { useStytchB2BClient, useStytchMemberSession } from '@stytch/react/b2b';
> > import { Navigate } from "react-router-dom";
> >
> > export const Authenticate = () => {
> >   const stytchClient = useStytchB2BClient();
> >   const { session } = useStytchMemberSession();
> >
> >   useEffect(() => {
> >     if (session) {
> >       <Navigate to="/profile" />;
> >     } else {
> >       const token = new URLSearchParams(window.location.search).get('token');
> >       stytchClient.sso.authenticate({
> >         sso_token: token,
> >       });
> >     }
> >   }, [stytchClient, session]);
> >
> >   return <div>Loading...</div>;
> > };
> > ```
> >
> > ```html Vanilla JS icon="square-js" theme={null}
> > <script>
> >   import { StytchB2BClient } from '@stytch/vanilla-js/b2b';
> >   const stytch = new StytchB2BClient('STYTCH_PUBLIC_TOKEN');
> >
> >   const token = new URLSearchParams(window.location.search).get('token');
> >   stytch.sso.authenticate({ sso_token: token });
> > </script>
> > ```

> [tab] Backend SDK
>
> This guide walks through integrating SSO using Stytch's backend SDKs or Direct API. This approach handles all authentication logic on your backend.
>
> > [tab] Discovery authentication
> >
> > ### Prerequisites
> >
> > Complete the steps in the [SSO provider setup guide](https://stytch.com/docs/multi-tenant-auth/authentication/sso/provider-setup.md).
> >
> > ### Implementation
> >
> > **1. Configure the callback route**
> >
> > Stytch will make a callback to your Redirect URL. Handle `stytch_token_type=sso` and authenticate the token.
> >
> > ```python Python icon="python" theme={null}
> > @app.route("/authenticate", methods=["GET"])
> > def authenticate() -> str:
> >     token_type = request.args["stytch_token_type"]
> >     if token_type == "sso":
> >         resp = stytch_client.sso.authenticate(sso_token=request.args["token"])
> >         if resp.status_code != 200:
> >             return "Authentication error"
> >     else:
> >         return "unsupported auth method"
> >
> >     member = resp.member
> >     session["stytch_session"] = resp.session_jwt
> >     return member.json()
> > ```
> >
> > **2. Initiate SSO**
> >
> > Test the SSO flow by navigating to:
> >
> > ```text theme={null}
> > https://test.stytch.com/v1/public/sso/start?connection_id={connection_id}&public_token={public_token}
> > ```
> >
> > **3. (Optional) Build a connection selector**
> >
> > If multiple SSO Connections exist, show users a list based on their Organization.
> >
> > ```python theme={null}
> > @app.route("/org/<string:slug>", methods=["GET"])
> > def org_index(slug: str):
> >     resp = stytch_client.organizations.search(query=SearchQuery(operator="AND", operands=[{
> >         "filter_name": "organization_slugs",
> >         "filter_value": [slug]
> >     }]))
> >     if resp.status_code != 200 or len(resp.organizations) == 0:
> >         return "Error fetching org"
> >
> >     organization = resp.organizations[0]
> >     return render_template(
> >         "organizationLogin.html",
> >         public_token=STYTCH_PUBLIC_TOKEN,
> >         org_name=organization.organization_name,
> >         sso_connections=organization.sso_active_connections
> >     )
> > ```
