Adding SSO to a custom auth flow

Authentication flow

Before you begin, make sure you’ve completed the SSO provider setup steps.

Overview

Headless frontend SDK
Backend 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 and Organization-specific authentication flows are supported.

Discovery authentication
Organization-specific 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 they are trying to access.

Prerequisites

Complete the steps in the SSO provider setup guide
Enable the Frontend SDKs in your Stytch Dashboard

Implementation

Discover available SSO Connections

If you have a centralized login page, prompt the user for their email and call sso.discoverConnections.

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.

Start the SSO flow

Use the selected connection_id to initiate the SSO flow.

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>;
};

The user will be redirected to their IdP to authenticate.

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.

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>;
};

The Stytch frontend SDK will store stytch_session_token and stytch_session_jwt in cookies for you. See session cookie management.

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

Complete the steps in the SSO provider setup guide, including creating an Organization.
Enable the Frontend SDKs in your Stytch Dashboard

Implementation

Fetch Organization SSO Connections

Use the Organization slug to fetch SSO Connections and render them in your UI.

React

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
};

Start the SSO flow

Call sso.start() using the selected connection_id.

React

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>;
};

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.

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>;
};

This guide walks through integrating SSO using Stytch’s backend SDKs or Direct API. This approach handles all authentication logic on your backend.

Discovery authentication

Prerequisites

Complete the steps in the SSO provider setup guide.

Implementation

Configure the callback route

Stytch will make a callback to your Redirect URL. Handle stytch_token_type=sso and authenticate the token.

Python

@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()

Initiate SSO

Test the SSO flow by navigating to:

https://test.stytch.com/v1/public/sso/start?connection_id={connection_id}&public_token={public_token}

(Optional) Build a connection selector

If multiple SSO Connections exist, show users a list based on their Organization.

@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
    )

​Authentication flow

​Overview

​Prerequisites

​Implementation

​Prerequisites

​Implementation

​Prerequisites

​Implementation

Authentication flow

Overview

Prerequisites

Implementation

Prerequisites

Implementation

Prerequisites

Implementation