Skip to main content
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:

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.

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:
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:
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.
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:
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:
{
  "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:
{
  "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 endpoint. You can enable JIT provisioning for all SSO connections or restrict it to specific connections. Learn more in the JIT provisioning guide.

​
Learn more

SSO guide

Comprehensive SSO documentation

JIT provisioning

Learn about automatic member provisioning