auth

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

Enable OAuth provider in config.toml

To enable an OAuth provider like Apple for local development, add a section to config.toml with the provider name. Example format for Apple: [auth.external.apple] with fields: enabled (boolean), client_id (string), secret (string), and redirect_uri (string, optional, overrides default auth redirectUrl).

env() function example for OAuth configuration

To use environment variables for OAuth configuration, reference them in config.toml like this: [auth.external.github] with enabled = true, client_id = "env(GITHUB_CLIENT_ID)", secret = "env(GITHUB_SECRET)", and redirect_uri = "" (optional override for default auth redirectUrl). The corresponding .env file should contain GITHUB_CLIENT_ID and GITHUB_SECRET variables.

Permission error or empty result often indicates RLS problem

A permission error or an unexpectedly empty result at the API layer is often a Postgres row-level security or privilege problem one layer down, though filters, authentication, query shape, or a stale schema cache can produce the same symptom. When in doubt, trace toward the database.

Auth errors troubleshooting table

Symptom: Login/logout/session broken; JWT invalid claim/missing sub; cookies not sent; OAuth redirect wrong; OTP/magic-link expired; MFA/TOTP fails; auth 500/503; emails not arriving. Layer: Auth → auth_logs, postgres_logs. Troubleshooting guides: 401 missing sub; 500 auth errors; 503 AuthRetryableFetchError; OTP expired; OAuth not redirecting; No auth emails; Next.js auth.

RLS and access errors troubleshooting table

Symptom: Empty data array with rows present; wrong rows returned; UPDATE/DELETE affects 0 rows; 42501 permission denied; service_role still blocked; policy not matching. Layer: RLS & access → postgres_logs. Troubleshooting guides: Empty select array; service_role hits RLS; Database API 42501 errors; RLS Simplified; Deprecated RLS features.

Email and password authentication in Kotlin Supabase client

Sign in with email: auth.signInWith(Email) { this.email = email; this.password = password }. Sign up with email: auth.signUpWith(Email) { this.email = email; this.password = password }. Sign in with Google: auth.signInWith(Google). Wrap these calls in try-catch blocks to handle exceptions.

Deep link handling for OAuth and OTP sign-in in Android

Create a DeepLinkHandlerActivity to handle OAuth and OTP callbacks. Register it in AndroidManifest.xml with an intent-filter matching android:scheme="app" and android:host="supabase.com". Call supabaseClient.handleDeeplinks(intent, onSessionSuccess) to process the deep link and extract user session information. After successful authentication, navigate back to MainActivity using FLAG_ACTIVITY_CLEAR_TOP.

Supabase client configuration in Android with PKCE auth

Create a SupabaseModule.kt with Hilt to provide singleton instances of SupabaseClient, Postgrest, Auth, and Storage. The SupabaseClient is instantiated using createSupabaseClient with supabaseUrl and supabaseKey from BuildConfig. Auth must be configured with flowType = FlowType.PKCE, scheme = "app", and host = "supabase.com". Install Postgrest, Auth, and Storage modules on the client.

Supabase Metrics API authentication

Authentication to the Supabase Metrics API uses HTTP Basic Auth. The password must be a Secret API key (identified by the sb_secret_ prefix). Secret API keys should be rotated regularly and Prometheus configuration updated accordingly.

Secure storage of Secret API keys in Prometheus

Secret API keys should be stored with a secret manager or injected via environment variables rather than stored directly in prometheus.yml.

Secret API key security for metrics

Store Secret API keys for metrics in a secret manager (AWS Secrets Manager, GCP Secret Manager, Vault, etc.). Rotate the key periodically via Project Settings → API Keys. For observability vendors, create a dedicated Secret API key scoped for metrics-only automation instead of using broadly-scoped keys.

Auth report charts and metrics

The Auth report includes: Active Users (count of unique users performing auth actions, shows user engagement and retention patterns), Sign In Attempts by Type (breakdown of authentication methods used, shows password vs OAuth vs magic link preferences), Sign Ups (total new user registrations, shows growth trends and onboarding funnel performance), API Gateway Auth Errors (error rates grouped by status code, shows authentication friction and security issues), Password Reset Requests (volume of password recovery attempts, shows user experience pain points).

SSO invite restrictions

Invites sent from an SSO account can only be accepted by another SSO account coming from the same identity provider. This is a security measure that prevents accidental invites to accounts not managed by the company's enterprise systems.

SQL Query Snippets execution by Read-Only role

SQL Query Snippets executed by the Read-Only role run against the database using the supabase_read_only_user role, which has the predefined Postgres role pg_read_all_data. This means Read-Only queries are limited to executing SELECT queries.

Project permissions table by role - Authentication Users

Authentication Users permissions by role: Create, Delete: Owner, Admin, and Developer. List: Owner, Admin, Developer, and Read-Only. Send OTP, Send password recovery, Send magic link, Remove MFA factors: Owner, Admin, and Developer.

Project permissions table by role - Authentication Providers and Config

Authentication Providers permissions by role: View: Owner, Admin, Developer, and Read-Only. Update: Owner and Admin. Rate Limits (View): Owner, Admin, Developer, and Read-Only. (Update): Owner and Admin. Email Templates (View): Owner, Admin, Developer, and Read-Only. (Update): Owner and Admin. URL Configuration (View): Owner, Admin, Developer, and Read-Only. (Update): Owner and Admin. Hooks (View): Owner, Admin, Developer, and Read-Only. (Create, Delete): Owner, Admin, and Developer.

Read-Only role access to secrets

The Read-Only role is able to access secrets in Supabase.

Custom domain activation requirements for SAML

Before activating a custom domain with SAML, contact each SAML identity provider and ask them to update the SAML application metadata. They should use `https://api.example.com/auth/v1/...` instead of `https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}`. The EntityID of the project changes when the domain is activated, which may cause existing SAML to stop working until providers update their configuration. Plan this ahead of time.

Vanity subdomain activation requirements for OAuth

Before activating a vanity subdomain, update OAuth provider settings by adding the subdomain Supabase Auth callback URL in addition to the existing Supabase project URL. Example: add `https://my-example-brand.supabase.co/auth/v1/callback` alongside `https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback`. For Twitter OAuth, ensure frontend code uses the subdomain instead of the default project domain.

Vanity subdomain activation requirements for SAML

Before activating a vanity subdomain with SAML, contact each SAML identity provider and ask them to update the SAML application metadata using `https://my-example-brand.supabase.co/auth/v1/...` instead of the original project domain. The EntityID changes upon activation, which may cause SAML to stop working until providers update their configuration.

Custom domain activation requirements for OAuth

Before activating a custom domain, update OAuth provider settings in each provider's developer console (not in Supabase dashboard). Add the custom domain Supabase Auth callback URL in addition to the existing Supabase project URL. Example: add `https://api.example.com/auth/v1/callback` alongside `https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback`. This prevents OAuth flows from breaking after domain activation.

Custom domain activation requirements for Twitter OAuth

When using Sign in with Twitter, ensure frontend code uses the custom domain instead of the default project domain, as Twitter OAuth uses cookies bound to the project's domain.

Advanced MFA Phone feature charging model

Advanced MFA Phone is a paid add-on feature that is charged by the hour. You are charged for the exact number of hours the feature is enabled for a project. If the feature is enabled for part of an hour, you are still charged for the full hour.

Advanced MFA Phone not covered by Spend Cap

The Advanced MFA Phone add-on is not covered by the Spend Cap cost control feature.

SMS and WhatsApp messaging charges for MFA Phone

Additional charges apply for each SMS or WhatsApp message sent when using Advanced MFA Phone, depending on your third-party messaging provider such as Twilio or MessageBird.

MFA Phone add-on billing in arrears

Project add-ons including MFA Phone are billed in arrears based on how many hours you used them. If you remove the MFA Phone add-on, you are no longer billed from the time of removal onward.

MFA Phone usage invoice line item name

Usage is shown as 'Auth MFA Phone Hours' on your invoice.

SSO MAU counted once per billing cycle

A single user who signs in and signs out multiple times within the same billing cycle is counted as one SSO MAU regardless of the number of authentication events. For example, User-1 signing in on January 3, signing out on January 4, and signing in again on January 17 within the same billing cycle counts as one SSO MAU.

signInWithSSO method for SSO authentication

To authenticate a user with SSO, call supabase.auth.signInWithSSO() with the domain parameter set to the company domain (e.g., 'company.com'). The method returns data with a url property that redirects the user to the identity provider's authentication flow: const { data, error } = await supabase.auth.signInWithSSO({ domain: 'company.com' }); if (data?.url) { window.location.href = data.url; }

Auth egress definition and example

Auth egress is data sent from Supabase Auth to the client while managing an application's users. This includes actions like signing in, signing out, or creating new users via the JavaScript Client SDK. Example: when a user signs in to an online shop, session data including authentication tokens and user profile details sent back to the client contributes to Auth Egress.

Firebase to Supabase auth migration tools

Supabase provides two tools for migrating auth users from Firebase: firestoreusers2json (available in TypeScript and JavaScript) exports users from Firebase to a .json file, and import_users (available in TypeScript and JavaScript) imports users from a .json file into the Supabase auth.users table in Postgres.

Set up Firebase to Supabase migration - configuration file

To set up the migration tool, clone the firebase-to-supabase repository and create a supabase-service.json file in the /auth directory with the following structure: host (database server hostname), user (postgres), password (your Supabase project password), database (postgres), and port (5432). Obtain the host and user values from your Supabase project dashboard under Connect > Session pooler view parameters.

Save Firebase password hash parameters

Before migrating users, retrieve Firebase password hash parameters by logging into Firebase Console, selecting Authentication in the Build section, selecting Users, clicking the menu (3 dots) at the top right of the users list, and clicking Password hash parameters. Save the values for base64_signer_key, base64_salt_separator, rounds, and mem_cost.

firestoreusers2json command line options

The firestoreusers2json command exports Firebase users to JSON with syntax: node firestoreusers2json.js [<filename.json>] [<batch_size>]. The filename.json parameter is optional and defaults to ./users.json. The batch_size parameter is optional and defaults to 100 users per batch.

import_users command line options

The import_users command imports users from a JSON file into Supabase Auth with syntax: node import_users.js <path_to_json_file> [<batch_size>]. The path_to_json_file parameter is required and specifies the full local path and filename of the JSON input file. The batch_size parameter is optional and defaults to 100 users per batch.

Advanced Firebase password migration with middleware

For more advanced migrations where existing Firebase passwords need to be verified and updated in Supabase on first login, a middleware server component can be implemented. Details on this approach are available in the firebase-to-supabase repository.

Supabase password for database access

When creating a new Supabase project, note the password provided, as it is needed for database access. If forgotten, the password can be reset in the Database Settings.

Login flow with MFA enabled

Once MFA is enabled for a Supabase user account, users will be prompted to enter their second factor challenge code from their preferred TOTP app during login.

Auth schema ownership requirements

All entities under the auth schema must be owned by the supabase_auth_admin role. Breaking this assumption risks rendering the auth service inoperational for the project.

SSO testing and multi-environment setup recommendations

For multi-environment setups (Dev/Staging/Prod), use IdP-initiated flow with multiple SAML apps under the same domain rather than domain-based routing. Testing in an Azure sandbox or test tenant is recommended before applying SSO to production.

SSO attribute mapping with Azure preset

The Attribute Mapping section should be filled out using the Azure preset when configuring Supabase SSO with Azure AD.

SSO protocol support

Supabase only supports the SAML 2.0 protocol for Single Sign-On.

SSO metadata URL configuration

The metadata URL obtained from Azure AD's App Federation Metadata URL (in the SAML Certificates section) must be entered into the Metadata URL field during Supabase SSO configuration.

SSO configuration location in dashboard

SSO configuration is accessed via the SSO tab under the Organization Settings page.

Supabase SAML metadata download URL

The Supabase SAML metadata file can be downloaded from: https://alt.supabase.io/auth/v1/sso/saml/metadata?download=true

Azure AD SSO basic SAML configuration settings

When configuring Supabase SSO with Azure AD, set Sign on URL to https://supabase.com/dashboard/sign-in-sso and Relay State to https://supabase.com/dashboard.

Azure AD SSO feature availability

Azure AD single sign-on is only available on Team and Enterprise Plans.

SSO organization invitations restriction

When SSO is enabled for an organization, organization invites are restricted to company members belonging to the same identity provider.

SSO invitation types

When inviting users to an organization, you can explicitly choose whether the invitation requires SSO authentication or allows non-SSO login (password/social). This enables mixed authentication organizations with both SSO and non-SSO users.

SSO default role for auto-joined users

When enabling auto-join, you can choose the role that automatically joined users receive. Options include Read-only, Developer, Administrator, and Owner. Supabase recommends using Developer as the default (principle of least privilege) and promoting users individually as needed.

SSO auto-join feature

The auto-join feature optionally allows users with a matching domain to join your organization automatically when they sign in via SSO. This applies on every login, not only on first signup.

SSO email domains configuration

Email domains are required only if you enable SP-initiated login. You can associate one or more email domains with your SSO provider. Users with matching email addresses can sign in via SSO at supabase.com. Email domains are not required for IdP-initiated flow.

SSO login flow recommendation

For quick decision making, start with IdP-initiated only (the default), as it works for 90% of use cases. Both IdP-initiated and SP-initiated flows can be enabled depending on organization needs.

IdP-initiated login flow

IdP-initiated login is the recommended flow where users start their login from their identity provider (Okta, Azure AD, Google Workspace) by clicking an app tile or bookmark. This is the simplest and most common configuration, requires no domain configuration, and works automatically once SSO is enabled. It is best for organizations with established IdP workflows, multiple SAML apps per domain, and provides the simplest user experience.

Supported SSO identity providers

Supabase supports practically all identity providers that support the SAML 2.0 SSO protocol. Documented provider guides include Google Workspace (formerly G Suite), Azure Active Directory, and Okta. For other providers, contact support.

Removing individual SSO user access

To revoke access for a specific SSO user without disabling the provider entirely, you may: (1) Remove or disable the user's account in your identity provider, or (2) Downgrade or remove their permissions for any organizations in Supabase.

SSO safety requirements before disabling

Before disabling or deleting SSO: (1) Verify a non-SSO owner account exists and can log in, (2) Communicate to affected users in advance, (3) Consider whether disabling is better than deleting if the change is temporary.

Disabling SSO locks out all SSO users

If you disable or delete the SSO provider for an organization, all SSO users will immediately be unable to sign in.

Non-SSO accounts must be removed to switch to SSO

If a user is already a member of the organization under a non-SSO account, they will need to be removed and invited again with an SSO-required invitation to join under their SSO account.

SSO users not eligible for identity linking

Each user account verified using an SSO identity provider will not be eligible for identity linking to existing user accounts in the system. If a user signed up with a password and then uses their company SSO login with the project, two separate user accounts with the same email will exist in the system. Users must ensure they are logged in with the correct account when accessing organizations/projects.

Give your agent this brain