Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

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.ts
index 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 imports
import { 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.mdx
index 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 t
See 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 Assistant
Configuring 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.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.example
index 3e1e2dc35e6..af4a4d34e9a 100644
--- a/docker/.env.example
+++ b/docker/.env.example
@@ -143,6 +143,56 @@ ENABLE_ANONYMOUS_USERS=false
ENABLE_PHONE_SIGNUP=true
ENABLE_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 Storage
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 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"