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

1. Navigate to your Supabase Dashboard

2. Select your project

3. Go to Authentication → Providers

4. Locate SAML 2.0 section

5. Toggle Enable SAML 2.0 to enabled

6. 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

1. Sign in to Azure Portal

2. Navigate to Microsoft Entra ID → Enterprise applications

3. Click New application → Create your own application

4. Select Integrate any other application you don't find in the gallery (Non-gallery)

5. Name it (e.g., "sfp SSO Production")

6. Click Create

Configure SAML Settings

1. In your application, go to Single sign-on

2. Select SAML as the method

3. Click Edit in Basic SAML Configuration

4. 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

1. Click Save

Configure Attributes and Claims

1. In Attributes & Claims, click Edit

2. 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

1. In SAML Certificates section

2. Download Federation Metadata XML

3. Save the file locally

Assign Users

1. Go to Users and groups

2. Click Add user/group

3. Select users who need sfp access

4. 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

Login to Supabase

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:

1. Contact your Supabase instance

2. Identify the SAML provider for your domain

3. Redirect you to Entra ID for authentication

4. 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:

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

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

1. Protect your anon key: While public, avoid committing it to version control

2. Use separate Supabase projects for different environments

3. Regularly rotate certificates in Entra ID

4. Monitor authentication logs in both Supabase and Entra ID

5. Implement proper RLS policies in your Supabase database

Next Steps

After successful configuration:

1. Document the SSO domain for your team

2. Create user onboarding documentation

3. Set up monitoring for authentication failures

4. Plan for certificate rotation schedules

5. Consider implementing automated user provisioning