Enterprise SSO and SAML for Self-Hosted Supabase: Complete Setup Guide

Enterprise customers don't use passwords. They use Single Sign-On (SSO) through identity providers like Okta, Azure AD, or Google Workspace. If you're self-hosting Supabase, enabling SAML SSO isn't as straightforward as it is on Supabase Cloud—but it's absolutely possible.

This guide walks you through the complete process of configuring enterprise SSO with SAML 2.0 for your self-hosted Supabase deployment.

Why Enterprise SSO Matters for Self-Hosted Supabase

Organizations choose self-hosted Supabase for data sovereignty, compliance requirements, and cost control. But many of these same organizations have strict authentication policies requiring SSO integration with their corporate identity provider.

Here's the problem: while Supabase Cloud supports SSO out of the box for Team and Enterprise plans, self-hosted deployments require manual configuration. The documentation is sparse, and developers often discover this gap only after committing to self-hosting.

Common enterprise requirements include:

Centralized user management: IT admins manage access from one place
Compliance mandates: SOC 2, HIPAA, and GDPR often require SSO
Security policies: No password sprawl across SaaS applications
Audit trails: Track authentication events through the IdP

The good news is that GoTrue, Supabase's authentication service, fully supports SAML 2.0. You just need to enable and configure it properly.

Prerequisites for SAML SSO Setup

Before diving into configuration, ensure you have:

A running self-hosted Supabase instance - Either Docker Compose or Kubernetes deployment
HTTPS configured - SAML requires encrypted connections; you'll need valid SSL certificates
Admin access to your identity provider - Okta, Azure AD, Google Workspace, or another SAML-compatible IdP
Access to modify environment variables - You'll need to restart services after configuration

If you haven't set up custom domains and SSL yet, check out our custom domains setup guide first.

Step 1: Generate the SAML Signing Key

SAML assertions need to be cryptographically signed. Generate a private key for this purpose:

# Generate a 2048-bit RSA private key in DER format
openssl genpkey -algorithm rsa -outform DER -out saml_private_key.der

# Convert to base64 for environment variable
base64 -w 0 saml_private_key.der > saml_private_key.b64

# Store this value securely - you'll need it for configuration
cat saml_private_key.b64

Keep this key secure. It's used to sign SAML requests and should never be exposed publicly.

Step 2: Configure GoTrue Environment Variables

GoTrue (the auth service) needs several environment variables to enable SAML. Add these to your Docker Compose or Kubernetes configuration:

# docker-compose.yml - auth service section
auth:
  environment:
    # Enable SAML authentication
    GOTRUE_SAML_ENABLED: "true"
    
    # Your base64-encoded private key from Step 1
    GOTRUE_SAML_PRIVATE_KEY: "${SAML_PRIVATE_KEY}"
    
    # External URL where your Supabase instance is accessible
    API_EXTERNAL_URL: "https://supabase.yourdomain.com"
    GOTRUE_EXTERNAL_URL: "https://supabase.yourdomain.com/auth/v1"
    
    # Site URL for redirects after authentication
    GOTRUE_SITE_URL: "https://your-app.com"

The API_EXTERNAL_URL must match exactly how users access your Supabase instance. Mismatched URLs are the most common cause of SAML configuration failures.

Step 3: Expose SAML Endpoints in Kong

By default, the Kong API gateway doesn't expose SAML endpoints. You need to add them manually to your kong.yml configuration:

# Add to /docker/volumes/api/kong.yml

- name: auth-v1-sso-saml-acs
  url: http://auth:9999/sso/saml/acs
  routes:
    - name: auth-v1-sso-saml-acs
      strip_path: true
      paths:
        - /auth/v1/sso/saml/acs
      
- name: auth-v1-sso-saml-metadata
  url: http://auth:9999/sso/saml/metadata
  routes:
    - name: auth-v1-sso-saml-metadata
      strip_path: true
      paths:
        - /auth/v1/sso/saml/metadata

After modifying kong.yml, restart the Kong service to apply changes:

docker-compose restart kong

Step 4: Verify SAML Is Enabled

Before connecting your identity provider, confirm that SAML is properly enabled:

curl https://supabase.yourdomain.com/auth/v1/settings

You should see "saml_enabled": true in the response. If it shows false, double-check your environment variables and restart the auth service.

Step 5: Configure Your Identity Provider

Now configure your corporate IdP to trust your Supabase instance. The process varies by provider.

Azure AD (Microsoft Entra ID)

In Azure Portal, navigate to Azure Active Directory → Enterprise Applications
Click New Application → Create your own application
Select "Integrate any other application you don't find in the gallery"
Go to Single sign-on → SAML
Set the following values:
- Identifier (Entity ID): https://supabase.yourdomain.com/auth/v1/sso/saml/metadata
- Reply URL (ACS URL): https://supabase.yourdomain.com/auth/v1/sso/saml/acs
Under Attributes & Claims, ensure email is mapped to user.mail
Download the Federation Metadata XML URL

Okta

In Okta Admin Console, go to Applications → Create App Integration
Select SAML 2.0 and click Next
Configure SAML settings:
- Single sign-on URL: https://supabase.yourdomain.com/auth/v1/sso/saml/acs
- Audience URI: https://supabase.yourdomain.com/auth/v1/sso/saml/metadata
Add attribute statement: email → user.email
Complete the wizard and copy the Identity Provider metadata URL

Google Workspace

In Google Admin Console, go to Apps → Web and mobile apps
Click Add app → Add custom SAML app
Configure the SAML settings with your ACS URL and Entity ID
Map the email attribute appropriately

Step 6: Register the Identity Provider with Supabase

With your IdP configured, register it with Supabase using the Admin API:

curl -X POST 'https://supabase.yourdomain.com/auth/v1/admin/sso/providers' \
  -H 'Authorization: Bearer YOUR_SERVICE_ROLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "saml",
    "metadata_url": "https://login.microsoftonline.com/TENANT_ID/federationmetadata/2007-06/federationmetadata.xml",
    "domains": ["yourdomain.com"],
    "attribute_mapping": {
      "keys": {
        "email": {
          "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
        }
      }
    }
  }'

Replace:

YOUR_SERVICE_ROLE_KEY with your Supabase service role key
The metadata_url with your IdP's metadata URL
domains with the email domains that should use SSO

The response will include an id for the SSO provider—save this for reference.

Step 7: Test SSO Authentication

Test the SSO flow by initiating a sign-in:

curl 'https://supabase.yourdomain.com/auth/v1/sso' \
  -H 'Content-Type: application/json' \
  -d '{"domain": "yourdomain.com"}'

You'll receive a JSON response with a url property. Opening this URL in a browser should redirect you to your identity provider's login page.

Multi-Tenant SSO Configuration

Building a B2B SaaS application? You can configure multiple SSO providers for different customer organizations. Each gets their own sso_provider_id included in the JWT:

# Add another SSO provider for a different customer
curl -X POST 'https://supabase.yourdomain.com/auth/v1/admin/sso/providers' \
  -H 'Authorization: Bearer YOUR_SERVICE_ROLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "saml",
    "metadata_url": "https://customer-idp.com/metadata.xml",
    "domains": ["customer.com"]
  }'

Use the sso_provider_id in your Row Level Security policies to enforce tenant isolation:

CREATE POLICY "Users can only access their tenant's data"
ON your_table
FOR ALL
USING (
  tenant_id = (auth.jwt() ->> 'sso_provider_id')::uuid
);

Troubleshooting Common Issues

"SAML response validation failed"

This usually means URL mismatches. Verify:

API_EXTERNAL_URL matches exactly what's configured in your IdP
ACS URL in your IdP matches https://your-domain/auth/v1/sso/saml/acs
Your SSL certificate is valid and trusted

"Identity provider not found"

The email domain doesn't match any registered SSO provider. Check:

The domains array in your provider configuration
User is signing in with an email from a registered domain

"Clock skew detected"

SAML assertions have short validity windows. Ensure:

Your server's clock is synchronized (use NTP)
Time zone settings are correct on both systems

SSO Works But User Data Is Missing

Check attribute mappings. The IdP must send at minimum the email attribute. Verify:

Attribute statements are configured in your IdP
The attribute_mapping in your provider registration matches your IdP's claim names

Security Considerations

When implementing enterprise SSO:

Protect the service role key: It has admin access to authentication APIs
Use HTTPS everywhere: SAML security depends on transport encryption
Rotate the SAML signing key periodically: Update both Supabase and IdP configurations
Monitor authentication logs: Watch for unusual patterns or failed attempts
Test failover procedures: Know how users authenticate if SSO is unavailable

Note that Single Logout (SLO) is not currently supported by Supabase Auth. Users can sign out of your application, but this won't terminate their IdP session.

How Supascale Simplifies This

Configuring SAML SSO for self-hosted Supabase involves multiple moving parts—environment variables, Kong routes, IdP configuration, and API calls. It's manageable but requires careful attention to detail.

Supascale simplifies self-hosted Supabase management with a visual interface for configuration, including OAuth provider setup. While enterprise SAML configuration still requires the steps above, having proper backup and restore capabilities means you can confidently test configurations without fear of breaking your production environment.

With automated backups and one-click restore, experimenting with authentication settings becomes much less risky.

Conclusion

Enterprise SSO with SAML 2.0 is fully achievable with self-hosted Supabase—it just requires manual configuration that Supabase Cloud handles automatically. The key steps are:

Generate and configure a SAML signing key
Enable SAML in GoTrue environment variables
Expose SAML endpoints through Kong
Configure your identity provider
Register the IdP with Supabase's Admin API

For organizations with compliance requirements mandating self-hosted infrastructure, this configuration unlocks enterprise authentication capabilities while maintaining full control over your data.

Ready to simplify your self-hosted Supabase deployment? Check out Supascale's pricing—one-time purchase, unlimited projects, no recurring fees.