Configuring Entra ID SAML SSO with Supabase Cloud

This guide walks through configuring Microsoft Entra ID (formerly Azure AD) as a SAML identity provider for your Supabase Cloud project to enable SSO authentication with sfp pro CLI/Codev

Prerequisites

Before starting the configuration, ensure you have:

Supabase Requirements:
- Supabase Pro plan or higher (SAML support requires Pro tier)
- Write access to your Supabase project
- Supabase CLI version 1.46.4 or higher
- Your project reference ID and anon key
Entra ID Requirements:
- Admin access to your Microsoft Entra ID tenant
- At least one verified domain in your Entra ID tenant
- Ability to create Enterprise Applications
sfp Requirements:
- sfp CLI installed
- Access to your sfp server instance
- sfp server URL (e.g., https://your-sfp-server.com)

Step 1: Enable SAML in Supabase Dashboard

Navigate to your Supabase Dashboard
Select your project
Go to Authentication → Providers
Locate SAML 2.0 section
Toggle Enable SAML 2.0 to enabled
Save the configuration

Step 2: Note Your Supabase Configuration

Gather the following information from your Supabase project:

# Your Supabase project URL
SUPABASE_URL=https://<project-ref>.supabase.co

# Your Supabase anon key (from Project Settings → API)
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# SAML endpoints (replace <project-ref> with your actual reference)
Entity ID: https://<project-ref>.supabase.co/auth/v1/sso/saml/metadata
ACS URL: https://<project-ref>.supabase.co/auth/v1/sso/saml/acs
Metadata URL: https://<project-ref>.supabase.co/auth/v1/sso/saml/metadata

Step 3: Configure Entra ID Enterprise Application

Create the Application

Sign in to Azure Portal
Navigate to Microsoft Entra ID → Enterprise applications
Click New application → Create your own application
Select Integrate any other application you don't find in the gallery (Non-gallery)
Name it (e.g., "sfp SSO Production")
Click Create

Configure SAML Settings

In your application, go to Single sign-on
Select SAML as the method
Click Edit in Basic SAML Configuration
Configure these URLs (replace <project-ref> with your actual reference):

Field

Value

Identifier (Entity ID)

https://<project-ref>.supabase.co/auth/v1/sso/saml/metadata

Reply URL (ACS URL)

https://<project-ref>.supabase.co/auth/v1/sso/saml/acs

Sign on URL

https://<project-ref>.supabase.co

Click Save

Configure Attributes and Claims

In Attributes & Claims, click Edit
Ensure these claims are configured:

Claim Name

Source Attribute

Unique User Identifier

user.mail

emailaddress

user.mail

displayname

user.displayname

givenname

user.givenname

surname

user.surname

Download Federation Metadata

In SAML Certificates section
Download Federation Metadata XML
Save the file locally

Assign Users

Go to Users and groups
Click Add user/group
Select users who need sfp access
Click Assign

Step 4: Configure Supabase with Entra ID

Install Supabase CLI

# macOS
brew install supabase/tap/supabase

# or via npm
npm install -g supabase

# Verify installation
supabase -v

supabase login

Add the SAML Provider

Using your downloaded metadata file and your organization's domain:

supabase sso add --type saml \
  --project-ref <your-project-ref> \
  --metadata-file /path/to/federation-metadata.xml \
  --domains "yourdomain.com"

Example:

supabase sso add --type saml \
  --project-ref loxlnircunupmpzuthoz \
  --metadata-file ~/Downloads/entra-metadata.xml \
  --domains "flxbl.io"

Configure Attribute Mappings

Create attribute-mapping.json:

{
  "keys": {
    "email": {
      "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    },
    "full_name": {
      "name": "http://schemas.microsoft.com/identity/claims/displayname"
    },
    "first_name": {
      "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
    },
    "last_name": {
      "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    }
  }
}

Apply the mapping:

# Get provider ID
supabase sso list --project-ref <your-project-ref>

# Update with mapping
supabase sso update <provider-id> \
  --project-ref <your-project-ref> \
  --attribute-mapping-file ./attribute-mapping.json

Verify Configuration

supabase sso show <provider-id> --project-ref <your-project-ref>

Ensure you see your domain listed in the output.

Step 5: Configure sfp CLI

Configure sfp to use your Supabase instance:

# Set your custom Supabase URL
sfp config:set auth-supabase-url https://<project-ref>.supabase.co

# Set your Supabase anon key
sfp config:set auth-supabase-anon-key eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Optionally, set default SSO domain
sfp config:set auth-sso-domain yourdomain.com

Example with actual values:

sfp config:set auth-supabase-url https://loxlnircunupmpzuthoz.supabase.co
sfp config:set auth-supabase-anon-key "your-actual-anon-key"
sfp config:set auth-sso-domain flxbl.io

Step 6: Test SAML Authentication

Test the complete flow with sfp:

sfp server auth login \
  --email [email protected] \
  --provider saml \
  --sso-domain yourdomain.com \
  --sfp-server-url https://your-sfp-server.com \
  --no-global-auth

Example:

sfp server auth login \
  --email [email protected] \
  --provider saml \
  --sso-domain flxbl.io \
  --sfp-server-url https://flxbl-dev.flxbl.io \
  --no-global-auth

This command will:

Contact your Supabase instance
Identify the SAML provider for your domain
Redirect you to Entra ID for authentication
Upon successful login, create a JWT token for sfp server access

Troubleshooting

Common Issues

"No SSO provider assigned for this domain"

Verify domain configuration: supabase sso list --project-ref <your-project-ref>
Ensure the domain matches exactly what you configured
Check that SAML is enabled in Supabase dashboard

"SAML assertion does not contain email address"

Verify email claim is configured in Entra ID
Check attribute mappings include email
Ensure assigned users have email addresses in Entra ID

Authentication succeeds but sfp login fails

Verify sfp config points to correct Supabase instance:

sfp config:get auth-supabase-url
sfp config:get auth-supabase-anon-key

Ensure the user's email domain matches the configured SSO domain

Certificate errors

Update metadata if certificates rotated:

supabase sso update <provider-id> \
  --project-ref <your-project-ref> \
  --metadata-file /path/to/new-metadata.xml

Debug Commands

# Check sfp configuration
sfp config:list

# Verify SSO provider configuration
supabase sso show <provider-id> --project-ref <your-project-ref> -o json

# Test with verbose output
sfp server auth login \
  --email [email protected] \
  --provider saml \
  --sso-domain yourdomain.com \
  --sfp-server-url https://your-sfp-server.com \
  --no-global-auth \
  --loglevel debug

Managing Multiple Environments

For different environments (dev, staging, production), you can:

Use environment variables:

export SUPABASE_URL=https://dev-project.supabase.co
export SUPABASE_ANON_KEY=dev-anon-key
export AUTH_SSO_DOMAIN=dev.yourdomain.com

Or switch sfp configuration:

# Development
sfp config:set auth-supabase-url https://dev-project.supabase.co
sfp config:set auth-supabase-anon-key dev-anon-key

# Production
sfp config:set auth-supabase-url https://prod-project.supabase.co
sfp config:set auth-supabase-anon-key prod-anon-key

Security Considerations

Protect your anon key: While public, avoid committing it to version control
Use separate Supabase projects for different environments
Regularly rotate certificates in Entra ID
Monitor authentication logs in both Supabase and Entra ID
Implement proper RLS policies in your Supabase database

Next Steps

After successful configuration:

Document the SSO domain for your team
Create user onboarding documentation
Set up monitoring for authentication failures
Plan for certificate rotation schedules
Consider implementing automated user provisioning

Last updated 3 hours ago