Configure SAML SSO

SAML 2.0 SSO lets your users authenticate through an enterprise Identity Provider (IdP) such as Okta, Azure AD (Entra ID), Google Workspace, or any SAML 2.0-compliant provider. Unlike OAuth providers, SAML IdPs are not configured through environment variables - they are managed dynamically at runtime through the Auth admin API.

This guide covers the full setup: generating a signing key, enabling SAML in your Zuvo instance, registering an IdP, and integrating SSO into your application.

Before you begin

You need:

• A running self-hosted Zuvo instance (see the setup guide)
• Open SSL installed (for key generation)
• Your IdP's SAML metadata URL or metadata XML
• The SERVICE_ROLE_KEY from your .env file (needed for admin API calls)
• API_EXTERNAL_URL set to the publicly-accessible URL of your Zuvo Auth service (e.g., https://<your-domain>/auth/v1). Used as the base for constructing the SAML Service Provider entity ID and ACS endpoint URL

How SAML SSO works in Zuvo

SAML SSO is configured in two layers:

1. Global SAML enable (environment variables) - a small set of env vars that enable the SAML engine and provide a signing key. These go in .env and docker-compose.yml.
2. Per-IdP configuration (admin API) - individual Identity Providers are registered, updated, and deleted at runtime via the Auth admin API. No restart is needed when adding or removing providers.

The login flow works as follows:

1. Your app calls POST /auth/v1/sso with a domain or provider_id
2. Auth generates a SAML AuthnRequest and returns a redirect URL to the IdP
3. The user authenticates at the IdP
4. The IdP POSTs a SAML Response to POST /auth/v1/sso/saml/acs
5. Auth validates the assertion, creates or links the user, and issues a session
6. The user is redirected back to your app with session tokens

Step 1: Generate an RSA private key

SAML requests must be signed. The value expected by GOTRUE_SAML_PRIVATE_KEY is a Base64-encoded PKCS#1 DER RSA private key (with a 2048-bit key as the minimum requirement). Generate it with:

openssl genpkey -algorithm RSA -out pk_pkcs8.pem -quiet && \
openssl pkey -in pk_pkcs8.pem -out pk_rsa1.der -outform DER -traditional && \
base64 -w 0 -i pk_rsa1.der

The commands above:

1. Generate an RSA private key in PKCS#8 PEM format
2. Convert the key to PKCS#1 DER format
3. Base64-encode the key for use as the value of GOTRUE_SAML_PRIVATE_KEY

Save the Base64 output - make sure to copy it as single line, ignoring the trailing newline. Remove the temporary files.

Step 2: Add environment variables

Add the following to your .env file:

############
# SAML SSO
############

SAML_ENABLED=true
SAML_PRIVATE_KEY=<your-base64-encoded-private-key>

# Optional: accept encrypted SAML assertions from IdPs (default: false)
# SAML_ALLOW_ENCRYPTED_ASSERTIONS=false

# Optional: how long relay state tokens remain valid (default: 2m0s)
# SAML_RELAY_STATE_VALIDITY_PERIOD=2m0s

# Optional: rate limit on the ACS endpoint (requests per second, default: 15)
# SAML_RATE_LIMIT_ASSERTION=15

Step 3: Pass SAML variables to the Auth container

In docker-compose.yml, add the SAML environment variables to the auth service. Auth expects the GOTRUE_ prefix for all of its configuration variables:

auth:
  environment:
    # ... existing variables ...

    # SAML SSO
    GOTRUE_SAML_ENABLED: ${SAML_ENABLED}
    GOTRUE_SAML_PRIVATE_KEY: ${SAML_PRIVATE_KEY}
    # GOTRUE_SAML_ALLOW_ENCRYPTED_ASSERTIONS: ${SAML_ALLOW_ENCRYPTED_ASSERTIONS}
    # GOTRUE_SAML_RELAY_STATE_VALIDITY_PERIOD: ${SAML_RELAY_STATE_VALIDITY_PERIOD}
    # GOTRUE_SAML_RATE_LIMIT_ASSERTION: ${SAML_RATE_LIMIT_ASSERTION}

Step 4: Restart the containers

Apply the configuration changes:

sh run.sh recreate

Verify the Auth service is healthy:

sh run.sh status auth

Step 5: Retrieve your service provider metadata

Once SAML is enabled, your Zuvo instance exposes service provider (SP) metadata at {API_EXTERNAL_URL}/sso/saml/metadata.

Verify it using curl:

curl http://<your-domain>/auth/v1/sso/saml/metadata

This returns an XML document containing your SP entity ID, ACS endpoint URL, and signing certificate. You will need to provide this to your IdP.

Key values in the metadata:

Step 6: Register an identity provider

Use the Auth admin API to register your IdP. You need the SERVICE_ROLE_KEY for authentication.

Option A: Register with a metadata URL (recommended)

If your IdP provides a metadata URL, Auth will fetch and cache the metadata automatically and refresh it when it becomes stale:

curl -X POST 'http://<your-domain>/auth/v1/admin/sso/providers' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-service-role-key' \
  -d '{
    "type": "saml",
    "metadata_url": "https://idp.example.com/saml/metadata",
    "domains": ["example.com"],
    "attribute_mapping": {
      "keys": {
        "email": {
          "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
        },
        "name": {
          "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
        }
      }
    }
  }'

Option B: Register with inline metadata XML

If you have the IdP metadata as an XML string:

curl -X POST 'http://<your-domain>/auth/v1/admin/sso/providers' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-service-role-key' \
  -d '{
    "type": "saml",
    "metadata_xml": "<EntityDescriptor ...>...</EntityDescriptor>",
    "domains": ["example.com"]
  }'

The response includes the provider id (UUID) - save this for use in your application or for later management:

{
  "id": "d3f5a1b2-...",
  "resource_id": null,
  "disabled": false,
  "saml": {
    "entity_id": "https://idp.example.com/saml",
    "metadata_url": "https://idp.example.com/saml/metadata"
  },
  "domains": [{ "domain": "example.com" }],
  "created_at": "...",
  "updated_at": "..."
}

Registration parameters reference

Step 8: Configure your identity provider

On the IdP side, create a new SAML application and configure it with your SP details:

IdP-specific configuration

Attribute mapping

Attribute mapping lets you control how SAML assertion attributes are translated into Zuvo user claims. If no mapping is provided, Auth uses sensible defaults:

Default email detection order:

1. urn:oid:0.9.2342.19200300.100.1.3 (LDAP mail OID)
2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
3. http://schemas.xmlsoap.org/claims/EmailAddress
4. Attributes named mail, Mail, or email
5. Subject NameID (if it looks like an email address)

Default user ID detection:

1. urn:oasis:names:tc:SAML:attribute:subject-id attribute
2. Subject NameID (if format is persistent)

Custom attribute mapping example

Map IdP-specific attributes to user metadata:

{
  "attribute_mapping": {
    "keys": {
      "email": {
        "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
      },
      "name": {
        "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
      },
      "department": {
        "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department",
        "default": "unknown"
      },
      "groups": {
        "name": "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups",
        "array": true
      },
      "role": {
        "names": ["http://schemas.microsoft.com/ws/2008/06/identity/claims/role", "role", "Role"],
        "default": "member"
      }
    }
  }
}

Each mapping key supports:

Mapped attributes are stored in the user's raw_user_meta_data and are available via user.user_metadata in your application.

Managing providers

List all providers

curl 'http://<your-domain>/auth/v1/admin/sso/providers' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'apikey: your-service-role-key'

Filter by resource ID using exact match:

curl 'http://<your-domain>/auth/v1/admin/sso/providers?resource_id=my-idp' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'apikey: your-service-role-key'

or prefix match:

curl 'http://<your-domain>/auth/v1/admin/sso/providers?resource_id_prefix=prod-' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'apikey: your-service-role-key'

Get a specific provider

curl 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'apikey: your-service-role-key'

Update a provider

curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-service-role-key' \
  -d '{
    "domains": ["example.com", "subsidiary.com"],
    "attribute_mapping": {
      "keys": {
        "email": {
          "name": "mail"
        }
      }
    }
  }'

Disable a provider (without deleting)

curl -X PUT 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-service-role-key' \
  -d '{ "disabled": true }'

Delete a provider

curl -X DELETE 'http://<your-domain>/auth/v1/admin/sso/providers/{provider_id}' \
  -H 'Authorization: Bearer your-service-role-key' \
  -H 'apikey: your-service-role-key'

Client-side integration

Using supabase-js

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('http://<your-domain>', 'your-anon-key')

// Option 1: SSO by email domain
const { data, error } = await supabase.auth.signInWithSSO({
  domain: 'example.com',
})

// Option 2: SSO by provider ID
const { data, error } = await supabase.auth.signInWithSSO({
  providerId: 'd3f5a1b2-...',
})

// Redirect the user to the IdP
if (data?.url) {
  window.location.href = data.url
}

Both methods return an object with a url property - redirect the user to this URL to begin authentication at the IdP.

Using the REST API directly

By domain:

curl -X POST 'http://<your-domain>/auth/v1/sso' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-anon-key' \
  -d '{
    "domain": "example.com",
    "skip_http_redirect": true
  }'

By provider ID:

curl -X POST 'http://<your-domain>/auth/v1/sso' \
  -H 'Content-Type: application/json' \
  -H 'apikey: your-anon-key' \
  -d '{
    "provider_id": "d3f5a1b2-...",
    "skip_http_redirect": true
  }'

Both return { "url": "https://idp.example.com/sso?SAMLRequest=..." }.

Domain-based vs provider-based lookup

Test the login flow

1. Open your application and trigger SSO login (or use the curl command above)
2. You should be redirected to your IdP's login page
3. After authenticating, the IdP posts back to the ACS endpoint
4. Auth processes the assertion and redirects you back to your SITE_URL (or redirect_to URL) with session tokens

To verify the session was created:

curl 'http://<your-domain>/auth/v1/user' \
  -H 'Authorization: Bearer user-session-token' \
  -H 'apikey: your-anon-key'

The response should include app_metadata.provider: "sso:saml" and any mapped attributes in user_metadata.

Environment variable reference

Troubleshooting

"SAML is not enabled on this server"

The GOTRUE_SAML_ENABLED variable is not set to true, or the Auth container did not pick up the change. Verify the env var is passed through docker-compose.yml and restart:

sh run.sh recreate

"Invalid private key" on startup

The GOTRUE_SAML_PRIVATE_KEY value is malformed. Ensure it is:

• Base64-encoded (single line, no line breaks)
• In PKCS#1 format (openssl pkey ... -traditional output)
• At least 2048-bit RSA

Regenerate if needed:

openssl genpkey -algorithm RSA -out pk_pkcs8.pem -quiet && \
openssl pkey -in pk_pkcs8.pem -out pk_rsa1.der -outform DER -traditional && \
base64 -w 0 -i pk_rsa1.der

IdP cannot reach the ACS endpoint

• Verify API_EXTERNAL_URL is set to a URL containing /auth/v1 the IdP can reach (not localhost unless testing locally)
• Check that the API gateway routes for /auth/v1/sso/saml/acs and /auth/v1/sso/saml/metadata are configured as open (no key-auth plugin).
• Check the Auth container logs: docker compose logs auth

"No SSO provider found for this domain"

• Verify the domain is registered: list providers and check the domains array
• Domain matching is exact and case-insensitive - Example.com matches example.com

Assertion validation fails

• Ensure the IdP's signing certificate matches what is in the metadata registered with Auth
• If using metadata_url, Auth automatically refreshes stale metadata (after ValidUntil, CacheDuration, or 24 hours). Force a refresh by updating the provider.
• Check clock sync between your server and the IdP - SAML assertions have time-based validity windows (NotBefore / NotOnOrAfter)

User is created but attributes are missing

• Check your attribute_mapping configuration. Use the IdP's SAML assertion viewer (most IdPs have one) to see the exact attribute names being sent.
• Attribute names are matched case-insensitively against both the Name and FriendlyName fields in the assertion.
• Mapped attributes appear in user.user_metadata.

Relay state expired

The user took too long between initiating SSO and completing authentication at the IdP. Increase GOTRUE_SAML_RELAY_STATE_VALIDITY_PERIOD (default is 2 minutes).

Additional resources

• SSO with SAML 2.0 - Client-side SAML integration guide
• Auth server configuration reference - Full list of Auth environment variables
• SAML 2.0 specification - The underlying standard