auth

381 notes in this subject, read out of this brain and free to use. This is page 4 of 7.

Testing SSO changes deployment order

Always test SSO changes in non-production first: Make change in Dev environment, test thoroughly using testing guide, deploy to Staging and verify, monitor 1-2 days, deploy to Production during low-usage period, monitor closely after production deployment.

Configuration synchronization across SSO environments

Keep critical settings synchronized: Attribute mappings should be identical across all providers, Certificate settings require coordinated renewals, each organization needs a non-SSO owner account. Use a configuration drift checklist: verify attribute mappings match, document certificate expiration dates, confirm non-SSO owner accounts exist, verify auto-join settings are intentional, confirm default roles appropriate for each environment.

SSO naming conventions

IDP app names should be consistent and descriptive: ✅ "Supabase - Production", ✅ "Supabase Prod" vs ❌ "Supabase" (ambiguous), ❌ "SUPA_PROD" (unclear). Match Supabase organization names to IDP app names when possible, e.g., IDP app "Supabase - Production" → Org slug acme-production, IDP app "Supabase - Staging" → Org slug acme-staging.

Role assignment patterns for multiple environments

Option 1 - Different default roles per environment: Dev with Administrator role (full developer control), Staging with Developer role, Prod with no auto-join using explicit invitations for Read-only or Developer roles. Option 2 - Consistent roles with manual promotion: All environments auto-join with Developer role, promote to Administrator/Owner manually as needed. Option 3 - No auto-join: All environments require explicit invitations with appropriate roles, maximum control with more overhead. Choose based on security posture and operational preferences.

Step-by-step setup for IDP-initiated multi-environment pattern

Step 1: Plan environments - document organization names, slugs, purposes, user access needs, default roles. Step 2: Create SAML apps in IDP for each environment using provider guides (Okta, Azure AD, Google Workspace), use consistent naming like "Supabase - Production", "Supabase - Staging", "Supabase - Development". Step 3: Configure each Supabase organization - navigate to SSO settings, enable Single Sign-On, verify Enable SP-initiated login is OFF, upload metadata, configure attribute mappings (Email required mapping to email, Name optional to name or displayName), configure auto-join (dev/staging usually enabled with Developer role, prod usually disabled). Step 4: Test each environment separately by clicking app tile and verifying redirect and user info. Step 5: Assign users in IDP (Production restrictive, Staging to QA/release managers, Dev to all engineers). Step 6: Document and communicate app tile-to-environment mapping and access processes.

Acquisitions with multiple email domains SSO

For organizations with multiple email domains (parent company parent.com, subsidiary1.com, subsidiary2.com) authenticating through the same central IDP: Option A - Enable SP-initiated flow with all domains added, configure single IDP metadata, users with any matching domain can log in. Option B - Create separate SAML apps for each entity as IDP-initiated only, assign users by subsidiary, provides more isolation and clearer boundaries.

SSO migration workflow phases

When migrating from one identity provider to another, use four phases: Phase 1 (Dual configuration) - Configure new IDP as additional provider while keeping existing IDP active, test with small group. Phase 2 (Gradual rollout) - Migrate users in batches, update app tile assignments, monitor. Phase 3 (Cutover) - Move all users to new IDP, verify none depend on old, disable old provider. Phase 4 (Cleanup) - After 1-2 weeks verification, delete old provider. Always maintain at least one non-SSO owner account during migration.

Multi-environment SSO configuration table

Configuration for three environments differs as follows: | Environment | Organization | IDP App Name | ACS URL | |---|---|---|---| | Dev | dev | "Supabase Dev" | `https://...dev-org.../saml/acs` | | Staging | staging | "Supabase Staging" | `https://...staging-org.../saml/acs` | | Production | prod | "Supabase Prod" | `https://...prod-org.../saml/acs` | For each organization: SP-initiated OFF, IDP-initiated ON, Auto-join at user preference (typically enabled for dev, disabled for prod).

Multiple environments SSO configuration example

For Dev, Staging, and Production environments with company.com emails: Create three separate SAML apps in the identity provider, each pointing to a different Supabase organization. In each Supabase organization, navigate to SSO settings, enable Single Sign-On, leave Enable SP-initiated login OFF (critical), upload metadata from the corresponding IDP app, configure attribute mappings (Email required, Name optional), and configure auto-join settings. Users click the appropriate app tile for the environment they need.

Recommended pattern for multiple SSO providers

Configure each environment as IdP-initiated only with no domains. Users access each environment through different app tiles in their identity provider.

IDP-initiated enables unlimited SAML apps per domain

Identity provider (IdP)-initiated flow solves domain conflicts that occur with SP-initiated flow only. With SP-initiated only, each SAML app requires a unique email domain. Since all employees typically use the same domain (e.g., company.com), this creates a problem. IDP-initiated flow doesn't require domain configuration, allowing unlimited SAML apps under the same domain.

Identify and migrate custom roles from md5 to scram-sha-256

To identify roles using md5 hashing and migrate their passwords, use these SQL statements after upgrade: List roles using md5: SELECT rolname FROM pg_authid WHERE rolcanlogin = true AND rolpassword LIKE 'md5%'; Migrate a role's password to scram-sha-256: ALTER ROLE <role_name> WITH PASSWORD '<password>';

Custom roles with md5 passwords caveat

The md5 hashing method is being deprecated in favor of scram-sha-256, which is the default and most secure authentication method in latest Postgres versions. Supabase automatically migrates Supabase-managed roles' passwords to scram-sha-256 during upgrade, but you must manually migrate passwords of any custom roles you created, otherwise you won't be able to connect using them after upgrade.

Auto-join verification checklist

Checklist for auto-join functionality: (1) Auto-join works when enabled; (2) Users receive correct default role; (3) Non-matching domains are excluded (if using SP-initiated with domains); (4) Existing users auto-join on their next login (not only on new signups); (5) Auto-join can be disabled and re-enabled as needed; (6) Auto-join is idempotent (no duplicate memberships); (7) Auto-join works with IdP-initiated only (no domains); (8) Auto-join works with both IdP and SP-initiated flows.

Safe deletion verification checklist

Checklist for safe SSO provider deletion: (1) Cannot delete without non-SSO owner account; (2) Error message clearly explains requirement; (3) Adding non-SSO owner enables deletion; (4) All SSO members removed upon deletion; (5) Non-SSO members unaffected by SSO provider deletion; (6) Organization remains accessible via non-SSO accounts; (7) SSO configuration completely removed after deletion; (8) Non-SSO owner account tested BEFORE deletion.

SSO account restrictions checklist

Checklist for SSO account restrictions: (1) SSO accounts cannot delete SSO providers; (2) SSO accounts CAN update SSO settings; (3) SSO accounts CAN disable SSO providers; (4) Non-SSO owners CAN delete SSO providers; (5) Error messages clearly explain the restriction; (6) Restriction applies to all SSO accounts (not only certain roles).

Invitation verification checklist

Checklist for invitation testing: (1) SSO-required invitations work correctly; (2) Non-SSO invitations work correctly; (3) SSO mismatch error message is clear; (4) Mixed authentication organization functions properly; (5) Invitations can be resent if needed.

Pre-configuration checklist for SSO setup

Before testing SSO, verify: Organization has Team or Enterprise plan; Login flow type decided (IdP-initiated, SP-initiated, or both); Email domains identified (only required if using SP-initiated); Auto-join settings and default role are decided; At least one non-SSO owner account exists (critical safety requirement); Certificate expiration dates are documented (especially for Google Workspace).

IdP-initiated login testing procedure

Test IdP-initiated login by: (1) Opening IdP dashboard (Okta, Azure AD, Google Workspace); (2) Locating Supabase app tile or bookmark and clicking it; (3) If already authenticated with IdP, immediate redirect to Supabase occurs; (4) If not authenticated, complete IdP login flow then redirect; (5) Verify you're logged into correct organization; (6) Verify user profile information is populated correctly. IdP-initiated login is always available and doesn't require domain configuration.

SP-initiated login testing requirements and procedure

SP-initiated login requires: 'Enable SP-initiated login' toggle is ON and at least one email domain configured. Test procedure: (1) Visit /dashboard/sign-in-sso or click 'Sign in with SSO' from main sign-in page; (2) Enter email with matching configured domain and click 'Continue'; (3) Verify redirect to identity provider; (4) Complete authentication if needed; (5) Verify redirect back to Supabase and correct organization access; (6) Test domain matching by trying email with non-matching domain - should receive error 'No SSO provider found'. Skip this test if SP-initiated flow is not enabled or no domains configured.

Domainless SSO configuration testing (IdP-initiated only)

For domainless SSO providers that enable multiple SAML apps per domain: (1) Configure SSO with 'Enable SP-initiated login' OFF (or no domains configured), IdP metadata configured, and attribute mappings configured; (2) Verify SP-initiated is unavailable by visiting /dashboard/sign-in-sso, entering email, and expecting error 'No SSO provider found'; (3) Verify IdP-initiated works by opening IdP dashboard, clicking Supabase app tile, and successfully logging in; (4) If using multiple environments (Dev/Staging/Prod), each should have separate app tile in IdP; clicking each tile should route to correct organization. Expected: IdP-initiated works perfectly, SP-initiated is unavailable (expected), multiple environments accessible via different tiles, no domain conflicts between environments.

Auto-join applies on every login, not only first signup

A recent improvement in Supabase SSO is that auto-join now applies on EVERY login, not only on first signup. This resolves a common issue where org owners would test with auto-join disabled, enable it, then log in again expecting to auto-join. To test auto-join: enable it in SSO settings, log out completely from Supabase, then sign in again via SSO and verify you were automatically added to the organization.

Recommended workflow for testing auto-join

Recommended testing workflow for auto-join: (1) Start with auto-join disabled - navigate to /dashboard/org/_/sso, ensure 'Join organization on signup' is disabled, configure SSO provider, test basic SSO login; (2) Enable auto-join after successful test - return to /dashboard/org/_/sso, toggle 'Join organization on signup' to enabled, select default role (recommended: Developer), click 'Save changes'; (3) Test auto-join with your account - log out completely from Supabase, sign in again via SSO, verify you were automatically added to the organization and received correct default role; (4) Test with additional users - have colleagues with matching email domains sign in via SSO and verify they automatically join the organization and received correct default role; (5) Test domain restrictions (if using SP-initiated) - try signing in with email from non-configured domain; user should be able to sign in but will NOT see the organization; (6) Test idempotency - log in again with account that's already a member, verify no error occurs, check members list for no duplicate entry, confirm role hasn't changed unexpectedly; (7) Test with domainless configuration - if configured SSO without domains (IdP-initiated only), enable auto-join, have new user access via IdP app tile, verify auto-join works without domain check; (8) Test auto-join re-enablement - disable auto-join, have new user sign in via SSO and verify they are NOT added to organization, re-enable auto-join, same user logs out and logs in again and verify they ARE now added to organization.

Invitation authentication type choice - SSO vs non-SSO

A recent improvement allows explicitly choosing whether an invitation requires SSO or non-SSO authentication, instead of inheriting from inviter's account type. When creating invitations: (1) Navigate to /dashboard/org/_/team; (2) Click 'Invite' to create new invitation; (3) Select either 'Require SSO' option or 'Non-SSO' option; (4) For SSO-required invitations, recipient must log in via SSO to accept; (5) For non-SSO invitations, recipient can use password or social login to accept.

SSO mismatch error when accepting invitations

When testing SSO invitation acceptance: if recipient tries to accept SSO-required invitation while logged in with non-SSO account, error displays: 'Invite token SSO provider does not match the one you are logged in with'. Recipient should log out and sign in via SSO, then can successfully accept the invitation.

SSO account deletion restrictions - safety mechanism

SSO accounts cannot delete SSO providers. This is a safety mechanism that prevents scenarios where an SSO user could accidentally lock out the entire organization by deleting the SSO provider they use to authenticate. When SSO account attempts to delete SSO provider, error message displays: 'Only a non-SSO account may delete an SSO Provider'. However, SSO accounts CAN: read SSO configuration, update SSO settings, and disable (but not delete) SSO provider. Only deletion is restricted.

Non-SSO owner requirement for SSO provider deletion

To delete an SSO provider, system verifies at least one non-SSO owner account exists. If only SSO accounts exist and all owners authenticate via SSO, deletion fails with error: 'At least one non-SSO account is required to maintain organization access'. This requirement prevents complete organization lockout.

SSO provider deletion removes all SSO members automatically

When an SSO provider is deleted: (1) System verifies at least one non-SSO owner account exists; (2) All SSO members are automatically removed from the organization; (3) SSO provider configuration is deleted; (4) Organization continues operating with remaining non-SSO members. This behavior prevents 'orphaned' SSO accounts that can no longer authenticate. Testing deletion should only occur in non-production environments or test organizations.

Critical safety practice - maintain non-SSO owner account

Best practice to maintain at least one non-SSO owner account: (1) Required to prevent complete organization lockout; (2) System enforces this when deleting SSO provider; (3) Create dedicated non-SSO owner BEFORE enabling SSO; (4) Store credentials securely in a password manager; (5) Verify this account can log in before critical changes. This is a critical safety requirement.

Certificate expiration monitoring for SSO

Best practice for certificate expiration: (1) Set calendar reminders 30 days before certificate expiration; (2) This is especially important for Google Workspace (certificates shown during setup); (3) Test SSO after certificate renewal; (4) Update metadata in Supabase after IdP certificate renewal; (5) Communicate planned renewal to team.

Domain configuration best practices for SSO

Best practices for configuring domains in SSO: (1) Use specific corporate email domains only; (2) Public domains (gmail.com, yahoo.com, etc.) are automatically blocked; (3) Be cautious with domains you don't fully control; (4) Multiple domains are supported for contractors/acquisitions; (5) Document which domains are configured and why.

Auto-join default role selection principle

When selecting default role for auto-join: (1) Default to 'Developer' role (principle of least privilege); (2) Avoid 'Owner' or 'Administrator' for auto-join; (3) Promote users individually as needed; (4) Review and document access control strategy.

Attribute mapping requirements for SSO

For SSO attribute mapping: (1) Email mapping is REQUIRED; (2) Use provider presets (Okta, Azure, G Suite) when available to avoid errors; (3) Document custom mappings for future reference; (4) Test mappings return expected user data; (5) Keep mappings consistent across environments; (6) Attribute keys must be spelled exactly as shown in provider.

Multi-environment SSO strategy

For multi-environment SSO setup: (1) Consider separate providers for dev/staging/prod; (2) Test configuration changes in non-production first; (3) Keep provider configurations synchronized; (4) Document differences between environments; (5) Domainless pattern (IdP-initiated only) is recommended if setting up Dev/Staging/Prod with multiple environments under same domain.

Pre-change notification for SSO modifications

Before making SSO changes: (1) Notify team members in advance; (2) Schedule during low-usage period if possible; (3) Have rollback plan ready; (4) Keep Supabase support contact information handy; (5) Document what you're changing and why.

Post-SSO configuration change verification

After SSO configuration changes: (1) Test login immediately; (2) Verify auto-join still works (if enabled); (3) Check that invitations are working; (4) Confirm no users are locked out; (5) Monitor for support requests from team.

Pre-deletion steps for SSO provider

Before deleting SSO provider: (1) Verify at least one non-SSO owner exists (system enforces); (2) Understand that all SSO members will be removed automatically; (3) Communicate to affected users BEFORE deletion; (4) Consider disabling rather than deleting if temporary; (5) Have plan for users to regain access if needed.

Common SSO issue - auto-join not working

Common workflow causing auto-join to appear non-functional: (1) Org owner tests SSO with auto-join disabled; (2) Enables auto-join after testing; (3) Logs in again expecting to auto-join but nothing happens. Solution: Auto-join now applies on every login, not only on first signup. To test: enable auto-join, log out completely, log back in via SSO. If still not working, verify domain configuration matches user email exactly.

Common SSO issue - SSO sign-in doesn't work

If SSO sign-in doesn't work at all, common causes are: (1) Metadata URL/file incorrect or expired; (2) Certificate expired (especially Google Workspace - check during setup); (3) Attribute mapping misconfigured; (4) User not assigned to Supabase app in identity provider; (5) Email domain not configured in Supabase SSO settings; (6) User email domain doesn't match configured domains. Troubleshooting steps: (1) Verify metadata URL/file is accessible and current; (2) Check certificate expiration date; (3) Verify attribute mappings (email mapping is required); (4) Confirm user is assigned to app in IdP; (5) Check domain configuration in Supabase matches user email; (6) Review IdP logs for authentication errors.

Common SSO issue - attribute mapping errors or missing user data

For attribute mapping errors or missing user data: (1) Email mapping to 'email' is REQUIRED; (2) Attribute keys must be spelled exactly as shown in provider; (3) Use provider presets (Okta, Azure, G Suite) to avoid errors. Troubleshooting: (1) Verify email attribute is mapped correctly; (2) Check attribute names match your IdP configuration exactly; (3) Test that mappings return expected user data; (4) Use IdP test tools to see what attributes are being sent.

Login flow verification checklist for SSO

Checklist to verify login flows before rollout: (1) IdP-initiated login works from IdP dashboard; (2) SP-initiated login works (if domains configured); (3) SP-initiated properly blocked if no domains configured; (4) Domain matching works correctly for SP-initiated; (5) Non-matching domains show appropriate errors; (6) Multiple environments route correctly (if using multiple providers); (7) Both flows work simultaneously (if both enabled).

Final verification checklist before SSO rollout

Complete checklist before rolling out SSO to organization: Authentication & Login Flows: IdP-initiated login works from IdP dashboard; SP-initiated login works (if domains configured); Appropriate login flow chosen for use case; Domain configuration correct (or intentionally empty for IdP-only); Multiple environments route correctly (if using multiple providers). Auto-Join Functionality: Auto-join adds users to correct organization (if enabled); Auto-joined users receive correct default role; Auto-join works on first login (not only on signup); Existing users auto-join when feature enabled; Auto-join is idempotent (no duplicate memberships); Auto-join works with IdP-initiated (no domains required); Non-matching domains excluded (if using SP-initiated). Invitations: SSO-required invitations work correctly; Non-SSO invitations work correctly; Invitation types can be explicitly chosen; SSO mismatch errors are clear. Safety & Access Controls: At least one non-SSO owner account exists; Non-SSO owner account can log in successfully; Non-SSO credentials stored securely; SSO account deletion restrictions understood and tested; Safe deletion behavior verified (if tested). Configuration: Certificate expiration date documented with calendar reminders; Team notified of SSO availability; Login instructions provided (IdP tile and/or supabase.com); Rollback plan documented; Support contact information available. Testing Completed: Tested with multiple user accounts; Both login flows tested (if both enabled); Auto-join behavior verified; SSO account restrictions confirmed; Domain restrictions validated (if applicable); Multi-environment isolation verified (if using multiple providers).

Row Level Security recommended for queues

It is recommended to leave Row Level Security (RLS) enabled when creating a queue. With RLS enabled, you do not need to set additional RLS on the queue tables.

RLS required on pgmq schema tables for client-side access

If you expose the pgmq schema with the Data API, you must enable Row Level Security (RLS) on all Queue tables (all tables in pgmq schema that begin with q_) for security purposes.

Recommended role permissions for Queues

For authenticated role, enable Select, Insert, Update, and Delete permissions on queue operations. For postgres and service_role roles, enable all permissions (Select, Insert, Update, Delete), but these roles should never be exposed client-side.

Provider tokens definition and sources

A provider token is a long-lived token issued by a third-party identity provider. These are issued by social login services (e.g., Google, Twitter, Apple, Microsoft) and uniquely identify a user on those platforms.

Access token definition and properties

An access token is a short-lived token, usually no more than 1 hour, that authorizes a client to access resources on a server. It comes in the form of a JSON Web Token (JWT).

Authentication definition and methods

Authentication (abbreviated authn.) is the process of verifying the identity of a user. Verification can happen through three methods: (1) asking users for something they know (password, passphrase), (2) checking that users have access to something they own (email address, phone number, hardware key, recovery codes), or (3) confirming that users have some biological features (fingerprint, facial structure, iris print).

Authenticator app and TOTP generation

An authenticator app generates time-based one-time passwords (TOTPs). These passwords are generated based off a long and difficult to guess secret string. The secret is initially passed to the application by scanning a QR code.

Authorization definition

Authorization (abbreviated authz.) is the process of verifying if a certain identity is allowed to access resources. Authorization often occurs by verifying an access token.

Identity provider definition and protocols

An identity provider is software or service that allows third-party applications to identify users without the exchange of passwords. Social login platforms typically use the OAuth protocol, while enterprise single-sign on is based on the OIDC or SAML protocols.

JSON Web Token (JWT) definition and usage

A JSON Web Token is a type of data structure, represented as a string, that usually contains identity and authorization information about a user. It encodes information about its lifetime and is signed with a cryptographic key making it tamper resistant. Access tokens are JWTs and by inspecting the information they contain you can allow or deny access to resources. Row level security policies are based on the information present in JWTs.

JWT signing secret security

JWTs issued by Supabase are signed using the HMAC-SHA256 algorithm. The secret key used in the signing is called the JWT signing secret. You should not share this secret with someone or some thing you don't trust, nor should you post it publicly. Anyone with access to the secret can create arbitrary JWTs.

Multi-factor authentication (MFA or 2FA) definition

Multi-factor authentication is the process of authenticating a user's identity by using a combination of factors: something users know, something users have, or something they are.

Nonce definition and usage

Nonce means number used once. It is a unique and difficult to guess string used to either initialize a protocol or algorithm securely, or detect abuse in various forms of replay attacks.

OAuth protocol definition and use cases

OAuth is a protocol allowing third-party applications to request and receive authorization from their users. It is typically used to implement social login, and serves as a base for enterprise single-sign on in the OIDC protocol. Applications can request different levels of access, including basic user identification information such as name, email address, and user ID.

OIDC (OpenID Connect) protocol definition

OIDC stands for OpenID Connect and is a protocol that enables single-sign on for enterprises. OIDC is based on modern web technologies such as OAuth and JSON Web Tokens. It is commonly used instead of the older SAML protocol.

One-time password (OTP) definition

A one-time password is a short, randomly generated and difficult to guess password or code that is sent to a device (like a phone number) or generated by a device or application.

Password hashing functions and algorithms

Password hashing functions are specially-designed algorithms that allow web servers to verify a password without storing it as-is. Unlike other difficult to guess strings, passwords are picked by users and often are easy to guess by attackers. These algorithms slow down and make it very costly for attackers to guess passwords. The three generally accepted password hashing functions are Argon2, bcrypt, and scrypt.

Password strength definition and measurement

Password strength is a measurement of how difficult a password is to guess. Basic measurement includes calculating the number of possibilities given the types of characters used in the password. For example, a password of only letters has fewer variations than ones with letters and digits. Better measurements include strategies such as looking for similarity to words, phrases, or already known passwords.

Give your agent this brain