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

> [card] SAML
>
> **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] OIDC
>
> **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

## SSO authentication flow

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

**1. 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.

**2. Redirect to IdP**

Redirect the user to their identity provider using the connection details:

> [tab] SAML
>
> 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] OIDC
>
> 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.

**3. 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.

**4. 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"
  }
}
```

**5. 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.

## 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](https://stytch.com/docs/api-reference/b2b/api/organizations/update-organization.md) endpoint. You can enable JIT provisioning for all SSO connections or restrict it to specific connections. Learn more in the [JIT provisioning guide](https://stytch.com/docs/multi-tenant-auth/enterprise-ready/org-management/jit-provision-members.md).

## Learn more

> [card] [SSO guide](https://stytch.com/docs/multi-tenant-auth/authentication/sso/overview.md)
>
> Comprehensive SSO documentation

> [card] [JIT provisioning](https://stytch.com/docs/multi-tenant-auth/enterprise-ready/org-management/jit-provision-members.md)
>
> Learn about automatic member provisioning
