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

# SSO overview

> Authenticate users with SAML and OIDC Single Sign-On using the Stytch API

SSO (Single Sign-On) allows users to authenticate to a service provider (SP) through their organization's identity provider (IdP) using SAML or OIDC protocols. Organizations can configure SSO connections to enable secure, centralized authentication for their members.

## SSO protocols

Stytch supports two SSO protocols:

<CardGroup cols={2}>
  <Card title="SAML" icon="shield-check">
    **Security Assertion Markup Language** - XML-based protocol commonly used in enterprise environments

    * IdP-initiated and SP-initiated flows
    * Supports signed assertions and responses
    * Works with Okta, Azure AD, Google Workspace, OneLogin, etc.
  </Card>

  <Card title="OIDC" icon="lock">
    **OpenID Connect** - Modern authentication protocol built on OAuth 2.0

    * JSON-based with simpler implementation
    * Uses JWTs for identity tokens
    * Works with Okta, Azure AD, Google, and other providers
  </Card>
</CardGroup>

## SSO authentication flow

The typical SSO authentication flow involves several steps coordinated between your application, Stytch, and the organization's identity provider (IdP).

<Steps>
  <Step title="Start the SSO flow">
    Initiate the SSO flow by redirecting the user to their identity provider. First, retrieve the organization's SSO connections to get the IdP URLs:

    ```bash theme={null}
    curl --request GET \
      --url https://test.stytch.com/v1/b2b/sso/organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931 \
      --user 'PROJECT_ID:SECRET'
    ```

    This returns all SAML and OIDC connections configured for the organization, including the URLs needed to start authentication.
  </Step>

  <Step title="Redirect to IdP">
    Redirect the user to their identity provider using the connection details:

    <Tabs>
      <Tab title="SAML" icon="shield-check">
        Use the `idp_sso_url` from the connection object to redirect the user's browser:

        ```
        https://idp.example.com/sso/saml
        ```

        The IdP will handle authentication and redirect back to the `acs_url` with a SAML assertion.
      </Tab>

      <Tab title="OIDC" icon="lock">
        Build a redirect to the `authorization_url` with required parameters:

        ```
        https://idp.example.com/authorize?
          client_id=YOUR_CLIENT_ID&
          redirect_uri=https://api.stytch.com/v1/b2b/sso/oidc/REDIRECT_PATH&
          response_type=code&
          scope=openid profile email
        ```

        The user authenticates at the IdP, which redirects back to Stytch's callback URL with an authorization code.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Handle the callback">
    After the user authenticates at their IdP, Stytch processes the SAML assertion or OIDC token and redirects back to your application with an `sso_token` as a query parameter:

    ```
    https://your-app.com/callback?stytch_token_type=sso&token=SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=
    ```

    Extract the `token` value from the URL query parameters.
  </Step>

  <Step title="Authenticate the SSO token">
    Exchange the SSO token for a member session by calling the authenticate endpoint:

    ```bash theme={null}
    curl --request POST \
      --url https://test.stytch.com/v1/b2b/sso/authenticate \
      --header 'Content-Type: application/json' \
      --user 'PROJECT_ID:SECRET' \
      --data '{
        "sso_token": "SeiGwdj5lKkrEVgcEY3QNJXt6srxS3IK2Nwkar6mXD4=",
        "session_duration_minutes": 60
      }'
    ```

    **Key parameters:**

    * `sso_token`: The token from the callback URL (required)
    * `session_duration_minutes`: How long the session should last (default: 60)
    * `session_custom_claims`: Custom data to include in the session JWT
    * `session_token` or `session_jwt`: Existing session to link to (optional)

    **Response:**

    ```json theme={null}
    {
      "status_code": 200,
      "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
      "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
      "session_token": "mZAYn5aLEqKUlZ_Ad9U_fWr38GaAQ1oFAhT8ds245v7Q",
      "session_jwt": "eyJhbGc...",
      "member_authenticated": true,
      "member": {
        "member_id": "member-test-32fc5024-9c09-4da3-bd2e-c9ce4da9375f",
        "email_address": "user@example.com",
        "name": "Jane Doe",
        "status": "active"
      },
      "organization": {
        "organization_id": "organization-test-07971b06-ac8b-4cdb-9c15-63b17e653931",
        "organization_name": "Acme Corp",
        "organization_slug": "acme-corp"
      }
    }
    ```
  </Step>

  <Step title="Handle MFA (if required)">
    If the organization requires MFA, the response will have `member_authenticated: false` and include an `intermediate_session_token`:

    ```json theme={null}
    {
      "member_authenticated": false,
      "intermediate_session_token": "intermediate_session_token_...",
      "member_id": "member-test-...",
      "organization_id": "organization-test-..."
    }
    ```

    Use the intermediate session token to complete an MFA challenge (TOTP or SMS) before the member is fully authenticated.
  </Step>
</Steps>

## JIT provisioning

Just-in-Time (JIT) provisioning allows new users to automatically join an organization when authenticating via SSO, without requiring a pre-existing invitation. When enabled, users authenticating through approved SSO connections are automatically created as members of the organization.

To configure JIT provisioning for SSO connections, use the [Update Organization](/docs/api-reference/b2b/api/organizations/update-organization) endpoint. You can enable JIT provisioning for all SSO connections or restrict it to specific connections. Learn more in the [JIT provisioning guide](/docs/multi-tenant-auth/enterprise-ready/org-management/jit-provision-members).

## Learn more

<CardGroup cols={2}>
  <Card title="SSO guide" icon="book" href="/docs/multi-tenant-auth/authentication/sso/overview">
    Comprehensive SSO documentation
  </Card>

  <Card title="JIT provisioning" icon="user-plus" href="/docs/multi-tenant-auth/enterprise-ready/org-management/jit-provision-members">
    Learn about automatic member provisioning
  </Card>
</CardGroup>