The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
docs: add oauth and otp how-to guides for self-hosted (#43286)
Andrey A.28808d2c9f45
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.tsindex 4cea890356d..42c83651762 100644--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts@@ -1,8 +1,9 @@-import type { ComponentProps } from 'react'// End of third-party importsimport { isFeatureEnabled } from 'common/enabled-features'+import type { ComponentProps } from 'react'import type { IconPanel } from 'ui-patterns/IconPanel'+import type { GlobalMenuItems, NavMenuConstant, NavMenuSection } from '../Navigation.types'const {@@ -2849,9 +2850,14 @@ export const self_hosting: NavMenuConstant = {name: 'How-to Guides',items: [{ name: 'Self-Hosted Functions', url: '/guides/self-hosting/self-hosted-functions' },- { name: 'Restore from Platform', url: '/guides/self-hosting/restore-from-platform' },+ {+ name: 'Restore Project from Platform',+ url: '/guides/self-hosting/restore-from-platform',+ },{ name: 'Configure S3 Storage', url: '/guides/self-hosting/self-hosted-s3' },{ name: 'Copy Storage from Platform', url: '/guides/self-hosting/copy-from-platform-s3' },+ { name: 'Configure Social Login (OAuth)', url: '/guides/self-hosting/self-hosted-oauth' },+ { name: 'Configure Phone Login & MFA', url: '/guides/self-hosting/self-hosted-phone-mfa' },{ name: 'Enabling MCP server', url: '/guides/self-hosting/enable-mcp' },],},diff --git a/apps/docs/content/guides/self-hosting/docker.mdx b/apps/docs/content/guides/self-hosting/docker.mdxindex 74146dcdc8d..74f9564ca3e 100644--- a/apps/docs/content/guides/self-hosting/docker.mdx+++ b/apps/docs/content/guides/self-hosting/docker.mdx@@ -428,6 +428,14 @@ By default all files are stored locally on the server. You can connect Storage tSee the [Configure S3 Storage](/docs/guides/self-hosting/self-hosted-s3) guide for detailed setup instructions.+#### Configuring social login (OAuth) providers++See the [Configure Social Login (OAuth) Providers](/docs/guides/self-hosting/self-hosted-oauth) guide for setup instructions.++#### Configuring phone login, SMS, and MFA++See the [Configure Phone Login & MFA](/docs/guides/self-hosting/self-hosted-phone-mfa) guide for SMS provider setup, OTP settings, and multi-factor authentication configuration.+#### Configuring Supabase AI AssistantConfiguring the Supabase AI Assistant is optional. By adding **your own** `OPENAI_API_KEY` to `.env` you can enable AI services, which help with writing SQL queries, statements, and policies.diff --git a/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdxnew file mode 100644index 00000000000..702cdd87565--- /dev/null+++ b/apps/docs/content/guides/self-hosting/self-hosted-oauth.mdx@@ -0,0 +1,458 @@+---+title: 'Configure Social Login (OAuth) Providers'+description: 'Set up social login (OAuth/OIDC) providers for self-hosted Supabase with Docker.'+subtitle: 'Set up social login (OAuth/OIDC) providers for self-hosted Supabase with Docker.'+---++This guide covers the **server-side configuration** required to enable social login providers on a self-hosted Supabase instance running with Docker Compose. This applies to all OAuth and OIDC-based providers, including third-party identity providers like Keycloak.++## Before you begin++You need:++- A working self-hosted Supabase installation. See [Self-Hosting with Docker](/docs/guides/self-hosting/docker).+- `API_EXTERNAL_URL` set to the publicly reachable URL of your Supabase instance (e.g., `https://<your-domain>`).++<Admonition type="danger">++HTTPS is strongly recommended in production. Most OAuth providers reject `http://` callback URLs (except `localhost`).++</Admonition>++Your **OAuth callback URL** is built from `API_EXTERNAL_URL`. For example, if `API_EXTERNAL_URL` is `https://<your-domain>`, the callback URL will become:++```+https://<your-domain>/auth/v1/callback+```++You will have to register this URL with each OAuth provider.++## OAuth request flow++When a user signs in with an OAuth provider, the following flow occurs:++1. Your app calls `supabase.auth.signInWithOAuth()` and the browser redirects to the Auth service+2. API gateway (Kong) routes the request to the Auth container (`/auth/v1/authorize`)+3. Auth redirects the user to the OAuth provider (e.g., Google) for consent+4. The provider redirects back to `https://<your-domain>/auth/v1/callback`+5. Auth exchanges the authorization code for tokens and redirects the user to your `SITE_URL` or an allowed redirect URL++## Auth environment variables++The Auth service (GoTrue) uses the prefix `GOTRUE_EXTERNAL_` followed by a provider name for all OAuth configuration. For example, when using Google:++- `GOTRUE_EXTERNAL_GOOGLE_ENABLED`+- `GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID`+- `GOTRUE_EXTERNAL_GOOGLE_SECRET`+- `GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI`++## Step-by-step configuration++The default `.env.example` and `docker-compose.yml` include commented-out placeholders for Google, GitHub, and Azure.++### Step 1: Register your app with the provider++1. Go to the OAuth provider's developer console and create an application.+2. Set the **authorized redirect URL**, e.g., `https://<your-domain>/auth/v1/callback`+3. Copy the **client ID** and **client secret** into your `.env` file.++### Step 2: Configure variables in the `.env` file++Uncomment the lines for your provider in `.env` and add your client ID and secret, e.g., for Google:++```+GOOGLE_ENABLED=true+GOOGLE_CLIENT_ID=your-client-id+GOOGLE_SECRET=your-client-secret+```++### Step 3: Enable the matching lines in `docker-compose.yml`++Uncomment the corresponding `GOTRUE_EXTERNAL_` lines in the `auth` service's `environment`:++```+GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}+GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}+GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}+GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+```++<Admonition type="note">++For providers **not** pre-configured in the files (see the [full provider list](#other-supported-providers) below), add the lines manually following the same pattern: variables in `.env`, passthrough with `GOTRUE_EXTERNAL_PROVIDER_` in `docker-compose.yml`.++</Admonition>++### Step 4: Restart the auth service++```sh+docker compose up -d --force-recreate --no-deps auth+```++### Step 5: Verify the configuration++Check that the provider is enabled:++```sh+curl https://<your-domain>/auth/v1/settings+```++The response should include your provider under `external`:++```+{+ "external": {+ "google": true+ }+}+```++## Provider-specific setup++<Tabs+ scrollable+ size="small"+ type="underlined"+ defaultActiveId="google"+>++<TabPanel id="google" label="Google">++**Google Cloud Console setup:**++1. Go to [Google Cloud Console](https://console.cloud.google.com/)+2. Create or select a project+3. Select **Solutions** > **All products** in the navigation menu on the left+4. Go to **APIs & services** > **OAuth consent screen** and click **Get started**+5. Follow the configuration steps and add an **External** app+6. Go to **APIs & Services** > **Credentials**+7. Click **Create Credentials** > **OAuth client ID**+8. Set application type to **Web application**+9. Under **Authorized redirect URIs**, add: `https://<your-domain>/auth/v1/callback`+10. Click **Create** and copy the client ID and client secret++**`.env`:**++```+GOOGLE_ENABLED=true+GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com+GOOGLE_SECRET=your-google-client-secret+```++**`docker-compose.yml`:**++```+GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}+GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}+GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}+GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+```++</TabPanel>++<TabPanel id="github" label="GitHub">++**GitHub setup:**++1. Go to [GitHub Developer Settings](https://github.com/settings/developers)+2. Click **New OAuth app**+3. Fill in **Homepage URL**, e.g., `https://<your-domain>`+4. Set **Authorization callback URL** to: `https://<your-domain>/auth/v1/callback`+5. Click **Register application**+6. Copy the client ID, generate and copy a client secret++**`.env`:**++```+GITHUB_ENABLED=true+GITHUB_CLIENT_ID=your-github-client-id+GITHUB_SECRET=your-github-client-secret+```++**`docker-compose.yml`:**++```+GOTRUE_EXTERNAL_GITHUB_ENABLED: ${GITHUB_ENABLED}+GOTRUE_EXTERNAL_GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID}+GOTRUE_EXTERNAL_GITHUB_SECRET: ${GITHUB_SECRET}+GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+```++</TabPanel>++<TabPanel id="azure" label="Azure">++**Azure Portal setup:**++1. Go to [Azure Portal](https://portal.azure.com/)+2. Go to **All services** > **Identity** > **App registrations** via the navigation menu on the left+3. Click **New registration**+4. Add application **Name**+5. Under **Redirect URI**, select **Web** and enter: `https://<your-domain>/auth/v1/callback`+6. Click **Register**+7. Copy the **Application (client) ID**+8. Click on **Client credentials** > **Add a certificate or secret**+9. Click on **New client secret** and add a client secret+10. Copy the secret value (not "secret ID")++**`.env`:**++```+AZURE_ENABLED=true+AZURE_CLIENT_ID=your-azure-application-client-id+AZURE_SECRET=your-azure-client-secret+## Optional: restrict to a specific tenant (defaults to 'common')+# AZURE_URL=https://login.microsoftonline.com/your-tenant-id+```++**`docker-compose.yml`:**++```+GOTRUE_EXTERNAL_AZURE_ENABLED: ${AZURE_ENABLED}+GOTRUE_EXTERNAL_AZURE_CLIENT_ID: ${AZURE_CLIENT_ID}+GOTRUE_EXTERNAL_AZURE_SECRET: ${AZURE_SECRET}+GOTRUE_EXTERNAL_AZURE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+## Optional: uncomment for tenant-specific Azure login+# GOTRUE_EXTERNAL_AZURE_URL: ${AZURE_URL}+```++</TabPanel>++<TabPanel id="apple" label="Apple">++**Apple Developer setup:**++1. Refer to [Apple Developer documentation](https://developer.apple.com/documentation/signinwithapple/configuring-your-environment-for-sign-in-with-apple) to learn how to enable App ID and create a Services ID+2. Create a private key for sign in with Apple+3. Generate a client secret JWT from your private key. See [Apple Developer documentation](https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret) for details.++**`.env`:**++```+APPLE_ENABLED=true+APPLE_CLIENT_ID=com.example.your-services-id+APPLE_SECRET=your-generated-jwt-client-secret+```++**`docker-compose.yml`:**++```+GOTRUE_EXTERNAL_APPLE_ENABLED: ${APPLE_ENABLED}+GOTRUE_EXTERNAL_APPLE_CLIENT_ID: ${APPLE_CLIENT_ID}+GOTRUE_EXTERNAL_APPLE_SECRET: ${APPLE_SECRET}+GOTRUE_EXTERNAL_APPLE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+```++<Admonition type="note">++Apple uses `response_mode=form_post` for its OAuth flow. The Auth service handles this automatically - no additional configuration is needed.++</Admonition>++</TabPanel>++<TabPanel id="keycloak" label="Keycloak">++**Keycloak setup:**++1. Open your Keycloak admin console+2. Select (or create) the realm you want to use+3. Go to **Clients** > **Create client**+4. Set **Client type** to **OpenID Connect**+5. Set **Client ID** (e.g., `supabase`)+6. On the next screen, enable **Client authentication**+7. Under **Valid redirect URIs**, add: `https://<your-domain>/auth/v1/callback`+8. Save, then go to the **Credentials** tab and copy the **Client secret**++**`.env` variables:**++```+KEYCLOAK_ENABLED=true+KEYCLOAK_CLIENT_ID=supabase+KEYCLOAK_SECRET=your-keycloak-client-secret+## Required: your Keycloak realm URL+KEYCLOAK_URL=https://keycloak.example.com/realms/myrealm+```++**`docker-compose.yml` passthrough:**++```+GOTRUE_EXTERNAL_KEYCLOAK_ENABLED: ${KEYCLOAK_ENABLED}+GOTRUE_EXTERNAL_KEYCLOAK_CLIENT_ID: ${KEYCLOAK_CLIENT_ID}+GOTRUE_EXTERNAL_KEYCLOAK_SECRET: ${KEYCLOAK_SECRET}+GOTRUE_EXTERNAL_KEYCLOAK_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback+GOTRUE_EXTERNAL_KEYCLOAK_URL: ${KEYCLOAK_URL}+```++<Admonition type="danger">++`KEYCLOAK_URL` is **required**. It must be the full realm URL (e.g., `https://keycloak.example.com/realms/myrealm`). The Auth service uses this to discover the OIDC endpoints (`.well-known/openid-configuration`). Without it, Keycloak login will not work.++</Admonition>++</TabPanel>++</Tabs>++## Other supported providers++Supabase Auth supports the following OAuth providers:++| Provider | Env prefix | Additional variables | Docs |+| ----------------- | ---------------- | ------------------------------- | --------------------------------------------------------------------- |+| Apple | `APPLE_` | - | [Login with Apple](/docs/guides/auth/social-login/auth-apple) |+| Azure (Microsoft) | `AZURE_` | `URL` (tenant URL) | [Login with Azure](/docs/guides/auth/social-login/auth-azure) |+| Bitbucket | `BITBUCKET_` | - | [Login with Bitbucket](/docs/guides/auth/social-login/auth-bitbucket) |+| Discord | `DISCORD_` | - | [Login with Discord](/docs/guides/auth/social-login/auth-discord) |+| Facebook | `FACEBOOK_` | - | [Login with Facebook](/docs/guides/auth/social-login/auth-facebook) |+| Figma | `FIGMA_` | - | [Login with Figma](/docs/guides/auth/social-login/auth-figma) |+| GitHub | `GITHUB_` | `URL` (for GitHub Enterprise) | [Login with GitHub](/docs/guides/auth/social-login/auth-github) |+| GitLab | `GITLAB_` | `URL` (for self-hosted GitLab) | [Login with GitLab](/docs/guides/auth/social-login/auth-gitlab) |+| Google | `GOOGLE_` | - | [Login with Google](/docs/guides/auth/social-login/auth-google) |+| Kakao | `KAKAO_` | - | [Login with Kakao](/docs/guides/auth/social-login/auth-kakao) |+| Keycloak (OIDC) | `KEYCLOAK_` | `URL` (realm URL, **required**) | [Login with Keycloak](/docs/guides/auth/social-login/auth-keycloak) |+| LinkedIn (OIDC) | `LINKEDIN_OIDC_` | - | [Login with LinkedIn](/docs/guides/auth/social-login/auth-linkedin) |+| Notion | `NOTION_` | - | [Login with Notion](/docs/guides/auth/social-login/auth-notion) |+| Slack (OIDC) | `SLACK_OIDC_` | - | [Login with Slack](/docs/guides/auth/social-login/auth-slack) |+| Snapchat | `SNAPCHAT_` | - | - |+| Spotify | `SPOTIFY_` | - | [Login with Spotify](/docs/guides/auth/social-login/auth-spotify) |+| Twitch | `TWITCH_` | - | [Login with Twitch](/docs/guides/auth/social-login/auth-twitch) |+| Twitter | `TWITTER_` | - | [Login with Twitter](/docs/guides/auth/social-login/auth-twitter) |+| WorkOS | `WORKOS_` | - | [Login with WorkOS](/docs/guides/auth/social-login/auth-workos) |+| Zoom | `ZOOM_` | - | [Login with Zoom](/docs/guides/auth/social-login/auth-zoom) |++For each provider, you need at minimum `ENABLED`, `CLIENT_ID`, `SECRET`, and `REDIRECT_URI` in `.env` and `docker-compose.yml`.++<Admonition type="caution">++**LinkedIn (OIDC)** and **Slack (OIDC)** use multi-word env prefixes. The full Docker Compose variables are `GOTRUE_EXTERNAL_LINKEDIN_OIDC_CLIENT_ID` and `GOTRUE_EXTERNAL_SLACK_OIDC_CLIENT_ID` respectively - not `LINKEDIN_CLIENT_ID` or `SLACK_CLIENT_ID`.++</Admonition>++## Test the login flow++You can test OAuth with the following minimal `index.html` served, e.g., via `python -m http.server 3000`:++```html+<!doctype html>+<html>+ <body>+ <h1>Supabase OAuth Test</h1>+ <button id="loginBtn">Sign in with Google</button>+ <pre id="result"></pre>++ <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>+ <script>+ document.addEventListener('DOMContentLoaded', function () {+ const SUPABASE_URL = 'https://<your-domain>'+ const SUPABASE_ANON_KEY = 'your-anon-key'++ const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_ANON_KEY)++ const button = document.getElementById('loginBtn')++ button.addEventListener('click', async () => {+ const { error } = await supabase.auth.signInWithOAuth({+ provider: 'google',+ })++ if (error) {+ document.getElementById('result').textContent = JSON.stringify(error, null, 2)+ }+ })++ supabase.auth.getSession().then(({ data }) => {+ if (data.session) {+ document.getElementById('result').textContent =+ 'Logged in as: ' + data.session.user.email+ }+ })+ })+ </script>+ </body>+</html>+```++<Admonition type="tip">++Make sure `SITE_URL` or `ADDITIONAL_REDIRECT_URLS` includes the URL where you open this test page. Otherwise the Auth service will reject the redirect after login.++</Admonition>++For detailed client-side integration, see [Social Login](/docs/guides/auth/social-login).++## Troubleshooting++### "Provider not enabled" or provider shows `false` in `/auth/v1/settings`++- Check that `GOTRUE_EXTERNAL_*_ENABLED` is set to `true` in `docker-compose.yml`+- Verify the `.env` variable is not empty, e.g., check with `docker compose exec auth env | grep GOOGLE`++### Variables added to `.env` but provider still not working++Configuration variables from `.env` are **not** automatically available inside the container unless there's a matching passthrough definition in `docker-compose.yml`. Check, e.g., for:++```+GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}+```++Run `docker compose exec auth env | grep GOTRUE_EXTERNAL` to verify the variables are reaching the container.++### `SITE_URL` or redirect URL errors after login++After a successful OAuth login, the Auth service redirects to `SITE_URL` or a URL from `ADDITIONAL_REDIRECT_URLS`. Ensure:++- `SITE_URL` in `.env` is set to your application's URL+- If your app uses a different redirect URL, add it to `ADDITIONAL_REDIRECT_URLS` (comma-separated)++{/* supa-mdx-lint-disable-next-line Rule001HeadingCase */}++### Nonce check failure on mobile (Google Sign In)++When using Google Sign In on mobile with ID tokens, nonce verification may fail because mobile SDKs don't always support the nonce flow that the Auth service expects.++<Admonition type="caution">++`GOTRUE_EXTERNAL_SKIP_NONCE_CHECK` disables nonce validation on ID tokens, which weakens replay-attack protection. Treat it as a **short-lived troubleshooting workaround**, not a permanent fix:++- Enable it only in the environment where you're debugging the issue.+- Revert it as soon as the issue is resolved.+- Prefer fixing the client-side nonce handling or switching to an OAuth flow (authorization code with PKCE) that avoids ID-token nonce issues entirely.++</Admonition>++To enable it, uncomment the following line in `docker-compose.yml`:++```+GOTRUE_EXTERNAL_SKIP_NONCE_CHECK: true+```++### Auth service fails to start++Check the auth container logs:++```sh+docker compose logs auth+```++Common causes:++- Missing required environment variable (e.g., `CLIENT_ID` or `SECRET` is empty)+- Invalid `API_EXTERNAL_URL` (must be a valid URL with protocol)++## Environment variable reference++All OAuth-related environment variables for the `auth` service in `docker-compose.yml`:++| Variable | Description | Required |+| -------------------------------- | ------------------------------------------------------------------------ | -------- |+| `GOTRUE_EXTERNAL_*_ENABLED` | Enable the provider (`true`/`false`) | Yes |+| `GOTRUE_EXTERNAL_*_CLIENT_ID` | OAuth client ID from the provider | Yes |+| `GOTRUE_EXTERNAL_*_SECRET` | OAuth client secret from the provider | Yes |+| `GOTRUE_EXTERNAL_*_REDIRECT_URI` | Callback URL: `${API_EXTERNAL_URL}/auth/v1/callback` | Yes |+| `GOTRUE_SITE_URL` | Default redirect URL after authentication (set via `SITE_URL` in `.env`) | Yes |++## Additional resources++- [Redirect URLs](/docs/guides/auth/redirect-urls)+- [Auth server on GitHub](https://github.com/supabase/auth) (check README and `example.env`)diff --git a/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdx b/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdxnew file mode 100644index 00000000000..64d2d13ba74--- /dev/null+++ b/apps/docs/content/guides/self-hosting/self-hosted-phone-mfa.mdx@@ -0,0 +1,222 @@+---+title: 'Configure Phone Login & MFA'+description: 'Set up phone login SMS providers, OTP settings, and multi-factor authentication for self-hosted Supabase with Docker.'+subtitle: 'Set up phone login SMS providers, OTP settings, and multi-factor authentication for self-hosted Supabase with Docker.'+---++This guide covers the **server-side configuration** for phone login and multi-factor authentication (MFA) on a self-hosted Supabase instance running with Docker Compose.++For client-side implementation, see [Phone Login](/docs/guides/auth/phone-login) and [Multi-Factor Authentication](/docs/guides/auth/auth-mfa).++## Before you begin++You need:++- A working self-hosted Supabase installation. See [Self-Hosting with Docker](/docs/guides/self-hosting/docker).+- An account with an SMS provider (e.g., Twilio)++Phone auth is **enabled by default** in the Docker setup (`ENABLE_PHONE_SIGNUP=true` in `.env`). However, without an SMS provider configured, the Auth service has no way to deliver OTP codes.++## SMS provider configuration++The default `.env.example` and `docker-compose.yml` include commented-out SMS provider placeholders. The example below uses Twilio - you'll need a Twilio account with an account SID, auth token, and message service SID. See [Twilio's documentation](https://www.twilio.com/docs/messaging) for how to obtain these credentials.++To enable SMS delivery:++### Step 1: Uncomment and configure the settings in `.env`++```+SMS_PROVIDER=twilio+SMS_OTP_EXP=60+SMS_OTP_LENGTH=6+SMS_MAX_FREQUENCY=60s+SMS_TEMPLATE=Your code is {{ .Code }}++## Twilio credentials+SMS_TWILIO_ACCOUNT_SID=your-account-sid+SMS_TWILIO_AUTH_TOKEN=your-auth-token+SMS_TWILIO_MESSAGE_SERVICE_SID=your-message-service-sid+```++### Step 2: Uncomment the matching lines in `docker-compose.yml`++Uncomment the `GOTRUE_SMS_*` lines in the `auth` service's `environment` block:++```+GOTRUE_SMS_PROVIDER: ${SMS_PROVIDER}+GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}+GOTRUE_SMS_OTP_LENGTH: ${SMS_OTP_LENGTH}+GOTRUE_SMS_MAX_FREQUENCY: ${SMS_MAX_FREQUENCY}+GOTRUE_SMS_TEMPLATE: ${SMS_TEMPLATE}+GOTRUE_SMS_TWILIO_ACCOUNT_SID: ${SMS_TWILIO_ACCOUNT_SID}+GOTRUE_SMS_TWILIO_AUTH_TOKEN: ${SMS_TWILIO_AUTH_TOKEN}+GOTRUE_SMS_TWILIO_MESSAGE_SERVICE_SID: ${SMS_TWILIO_MESSAGE_SERVICE_SID}+```++### Step 3: Restart the auth service++```sh+docker compose up -d --force-recreate --no-deps auth+```++### Step 4: Verify++```sh+docker compose exec auth env | grep GOTRUE_SMS+```++Confirm your provider and credentials appear in the output.++<Admonition type="note">++For providers other than Twilio, add the provider-specific `GOTRUE_SMS_*` lines manually to `docker-compose.yml`.++</Admonition>++## OTP settings++### Expiration++<Admonition type="caution">++The default OTP expiration is **60 seconds**. This is often too short for production use, consider increasing it.++</Admonition>++Set `SMS_OTP_EXP` in `.env` (value is in seconds):++```+# Set expiration to 5 minutes+SMS_OTP_EXP=300+```++And ensure `GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}` is uncommented in `docker-compose.yml`.++### Length++The default OTP length is 6 digits. You can set it to any value between 6 and 10:++```+SMS_OTP_LENGTH=8+```++### Rate limiting++`SMS_MAX_FREQUENCY` controls the minimum interval between SMS sends to the same phone number. The default is 60 seconds:++```+## Allow one SMS every 30 seconds+SMS_MAX_FREQUENCY=30s+```++## Test OTPs for development++To avoid sending real SMS during development, use `SMS_TEST_OTP` to map phone numbers to fixed OTP codes:++```+SMS_TEST_OTP=16505551234:123456,16505555678:654321+```++And uncomment `GOTRUE_SMS_TEST_OTP: ${SMS_TEST_OTP}` in `docker-compose.yml`.++When a test phone number requests an OTP, the Auth service skips SMS delivery and accepts only the mapped code. Other phone numbers continue to use the real SMS provider.++<Admonition type="caution">++Remove test OTPs before deploying to production. You can also set an expiration with `SMS_TEST_OTP_VALID_UNTIL` (ISO 8601 datetime, e.g., `2026-12-31T23:59:59Z`) so they stop working automatically.++</Admonition>++## Multi-factor authentication (MFA)++The Auth service supports three MFA factor types. Configure them by uncommenting variables in `.env` and the matching `GOTRUE_MFA_*` lines in `docker-compose.yml`.++### App authenticator (TOTP)++TOTP is **enabled by default** - users can enroll with apps like Google Authenticator or Authy without any additional configuration.++To disable TOTP:++```+MFA_TOTP_ENROLL_ENABLED=false+MFA_TOTP_VERIFY_ENABLED=false+```++### Phone MFA++Phone MFA is **disabled by default** (opt-in). It uses the same SMS provider configuration as phone login.++To enable:++```+MFA_PHONE_ENROLL_ENABLED=true+MFA_PHONE_VERIFY_ENABLED=true+```++### Maximum enrolled factors++By default, a user can enroll up to 10 MFA factors. To change this:++```+MFA_MAX_ENROLLED_FACTORS=5+```++## Troubleshooting++### OTP expires too quickly++The default `SMS_OTP_EXP` is 60 seconds. Increase it in `.env`:++```+SMS_OTP_EXP=300+```++Ensure `GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}` is uncommented in `docker-compose.yml`, then restart:++```sh+docker compose up -d --force-recreate --no-deps auth+```++### SMS not being delivered++Check the auth container logs for errors:++```sh+docker compose logs auth --tail 50+```++Verify provider credentials reach the container:++```sh+docker compose exec auth env | grep GOTRUE_SMS+```++Common causes:++- Provider credentials are in `.env` but the matching `GOTRUE_SMS_*` line is still commented out in `docker-compose.yml`+- Provider credentials are wrong+- Phone number format is wrong (use E.164 format: `+1234567890`)++### Variables are configured in `.env` but not working++Configuration variables from `.env` are **not** automatically available inside the container unless there's a matching passthrough definition in `docker-compose.yml`. Check, e.g., for:++```sh+docker compose exec auth env | grep -E 'GOTRUE_SMS|GOTRUE_MFA'+```++After changing the configuration environment variables, recreate the Auth service container:++```sh+docker compose up -d --force-recreate --no-deps auth+```++### Rate limit errors++If users see "rate limit exceeded" errors, check `SMS_MAX_FREQUENCY` (minimum interval between sends) and the global rate limit `GOTRUE_RATE_LIMIT_SMS_SENT` (default: 30 per hour).++### Additional resources++- [Multi-Factor Authentication (Phone)](/docs/guides/auth/auth-mfa/phone)+- [Multi-Factor Authentication (TOTP)](/docs/guides/auth/auth-mfa/totp)+- [Auth server on GitHub](https://github.com/supabase/auth) (check README and `example.env`)diff --git a/docker/.env.example b/docker/.env.exampleindex 3e1e2dc35e6..af4a4d34e9a 100644--- a/docker/.env.example+++ b/docker/.env.example@@ -143,6 +143,56 @@ ENABLE_ANONYMOUS_USERS=falseENABLE_PHONE_SIGNUP=trueENABLE_PHONE_AUTOCONFIRM=true+## OAuth / Social login providers++# Uncomment and fill in the providers you want to enable.+# You must ALSO uncomment the matching GOTRUE_EXTERNAL_* lines in docker-compose.yml.+# Documentation: https://supabase.com/docs/guides/self-hosting/self-hosted-oauth+# GOOGLE_ENABLED=false+# GOOGLE_CLIENT_ID=+# GOOGLE_SECRET=++# GITHUB_ENABLED=false+# GITHUB_CLIENT_ID=+# GITHUB_SECRET=++# AZURE_ENABLED=false+# AZURE_CLIENT_ID=+# AZURE_SECRET=++# Phone / SMS provider configuration+# Uncomment to configure SMS delivery for phone auth and phone MFA.+# You must ALSO uncomment the matching GOTRUE_SMS_* lines in docker-compose.yml.+# Documentation: https://supabase.com/docs/guides/self-hosting/self-hosted-phone-mfa+# SMS_PROVIDER=twilio+# SMS_OTP_EXP=60+# SMS_OTP_LENGTH=6+# SMS_MAX_FREQUENCY=60s+# SMS_TEMPLATE=Your code is {{ .Code }}++# SMS_TWILIO_ACCOUNT_SID=+# SMS_TWILIO_AUTH_TOKEN=+# SMS_TWILIO_MESSAGE_SERVICE_SID=++# Test OTP: map phone numbers to fixed OTP codes for development+# Format: phone1:code1,phone2:code2+# SMS_TEST_OTP=++# Multi-factor authentication (MFA)+# Uncomment to change MFA defaults.+# You must ALSO uncomment the matching GOTRUE_MFA_* lines in docker-compose.yml.++# App Authenticator (TOTP) - enabled by default+# MFA_TOTP_ENROLL_ENABLED=true+# MFA_TOTP_VERIFY_ENABLED=true++# Phone MFA - disabled by default (opt-in)+# MFA_PHONE_ENROLL_ENABLED=false+# MFA_PHONE_VERIFY_ENABLED=false++## Maximum MFA factors a user can enroll+# MFA_MAX_ENROLLED_FACTORS=10+############# Storage - Configuration for Storagediff --git a/docker/docker-compose.yml b/docker/docker-compose.ymlindex 0fc499912b3..6dc1dd0ab55 100644--- a/docker/docker-compose.yml+++ b/docker/docker-compose.yml@@ -156,7 +156,48 @@ services:GOTRUE_EXTERNAL_PHONE_ENABLED: ${ENABLE_PHONE_SIGNUP}GOTRUE_SMS_AUTOCONFIRM: ${ENABLE_PHONE_AUTOCONFIRM}- # Uncomment to enable custom access token hook. Please see: https://supabase.com/docs/guides/auth/auth-hooks for full list of hooks and additional details about custom_access_token_hook++ # Uncomment to enable OAuth / social login providers.+ # GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}+ # GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}+ # GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}+ # GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback++ # GOTRUE_EXTERNAL_GITHUB_ENABLED: ${GITHUB_ENABLED}+ # GOTRUE_EXTERNAL_GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID}+ # GOTRUE_EXTERNAL_GITHUB_SECRET: ${GITHUB_SECRET}+ # GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback++ # GOTRUE_EXTERNAL_AZURE_ENABLED: ${AZURE_ENABLED}+ # GOTRUE_EXTERNAL_AZURE_CLIENT_ID: ${AZURE_CLIENT_ID}+ # GOTRUE_EXTERNAL_AZURE_SECRET: ${AZURE_SECRET}+ # GOTRUE_EXTERNAL_AZURE_REDIRECT_URI: ${API_EXTERNAL_URL}/auth/v1/callback++ # Uncomment to configure SMS delivery (phone auth and phone MFA).+ # GOTRUE_SMS_PROVIDER: ${SMS_PROVIDER}+ # GOTRUE_SMS_OTP_EXP: ${SMS_OTP_EXP}+ # GOTRUE_SMS_OTP_LENGTH: ${SMS_OTP_LENGTH}+ # GOTRUE_SMS_MAX_FREQUENCY: ${SMS_MAX_FREQUENCY}+ # GOTRUE_SMS_TEMPLATE: ${SMS_TEMPLATE}++ # Twilio credentials (when SMS_PROVIDER=twilio)+ # GOTRUE_SMS_TWILIO_ACCOUNT_SID: ${SMS_TWILIO_ACCOUNT_SID}+ # GOTRUE_SMS_TWILIO_AUTH_TOKEN: ${SMS_TWILIO_AUTH_TOKEN}+ # GOTRUE_SMS_TWILIO_MESSAGE_SERVICE_SID: ${SMS_TWILIO_MESSAGE_SERVICE_SID}++ # Test OTP mappings for development+ # GOTRUE_SMS_TEST_OTP: ${SMS_TEST_OTP}++ # Uncomment to configure multi-factor authentication (MFA).+ # GOTRUE_MFA_TOTP_ENROLL_ENABLED: ${MFA_TOTP_ENROLL_ENABLED}+ # GOTRUE_MFA_TOTP_VERIFY_ENABLED: ${MFA_TOTP_VERIFY_ENABLED}+ # GOTRUE_MFA_PHONE_ENROLL_ENABLED: ${MFA_PHONE_ENROLL_ENABLED}+ # GOTRUE_MFA_PHONE_VERIFY_ENABLED: ${MFA_PHONE_VERIFY_ENABLED}+ # GOTRUE_MFA_MAX_ENROLLED_FACTORS: ${MFA_MAX_ENROLLED_FACTORS}++ # Uncomment to enable custom access token hook.+ # See: https://supabase.com/docs/guides/auth/auth-hooks for+ # full list of hooks and additional details about custom_access_token_hook# GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_ENABLED: "true"# GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI: "pg-functions://postgres/public/custom_access_token_hook"