配置社交登录（OAuth）提供商

本指南介绍了在使用 Docker Compose 运行的自托管 Supabase 实例上启用社交登录提供商所需的服务器端配置。这适用于所有基于 OAuth 和 OIDC 的提供商，包括像 Keycloak 这样的第三方身份提供商。

🌐 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:

• 一个可用的自托管 Supabase 安装。请参阅 使用 Docker 自托管。
• API_EXTERNAL_URL 设置为你 Supabase 实例的可公开访问的 URL（例如，https://<your-domain>/auth/v1）。

你的 OAuth 回调 URL 应该看起来像下面这样：

🌐 Your OAuth callback URL should look like the following:

1
https://<your-domain>/auth/v1/callback

你需要在每个 OAuth 提供商那里注册这个 URL。

🌐 You will have to register this URL with each OAuth provider.

OAuth 请求流程 #

🌐 OAuth request flow

当用户使用 OAuth 提供商登录时，会发生以下流程：

🌐 When a user signs in with an OAuth provider, the following flow occurs:

1. 你的应用调用了 supabase.auth.signInWithOAuth()，然后浏览器会重定向到认证服务
2. API 网关会将请求路由到 Auth 容器（/auth/v1/authorize）
3. Auth 会将用户重定向到 OAuth 提供商（例如 Google）以获取同意
4. 提供商会重定向回 https://<your-domain>/auth/v1/callback
5. Auth 用授权码换取令牌，然后将用户重定向到你的 SITE_URL 或允许的重定向 URL

认证环境变量 #

🌐 Auth environment variables

Auth 服务（GoTrue）在所有 OAuth 配置中都会使用前缀 GOTRUE_EXTERNAL_，后面跟上提供商的名称。例如，使用 Google 时：

🌐 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

默认的 .env.example 和 docker-compose.yml 包含为 Google、GitHub 和 Azure 注释掉的占位符。

🌐 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. 去 OAuth 提供商的开发者控制台创建一个应用吧。
2. 设置授权重定向 URL，例如 https://<your-domain>/auth/v1/callback
3. 把客户端ID和客户端密钥复制到你的.env文件里。

步骤 2：配置环境变量 #

🌐 Step 2: Configure environment variables

取消注释 .env 中你提供商的行，并添加你的客户端 ID 和密钥，例如，对 Google：

🌐 Uncomment the lines for your provider in .env and add your client ID and secret, e.g., for Google:

1
GOOGLE_ENABLED=true
2
GOOGLE_CLIENT_ID=your-client-id
3
GOOGLE_SECRET=your-client-secret

步骤 3：在 Docker Compose 配置中启用匹配的行 #

🌐 Step 3: Enable the matching lines in Docker Compose configuration

取消注释 auth 服务的 environment 中相应的 GOTRUE_EXTERNAL_ 行：

🌐 Uncomment the corresponding GOTRUE_EXTERNAL_ lines in the auth service's environment:

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}
5
    GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
6
    GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}
7
    GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

第4步：重启认证服务 #

🌐 Step 4: Restart the auth service

1
sh run.sh recreate auth

步骤5：核实配置 #

🌐 Step 5: Verify the configuration

检查一下提供者是否已启用：

🌐 Check that the provider is enabled:

1
curl -H 'apikey: your-anon-key' https://<your-domain>/auth/v1/settings

回复中应在 external 下包括你的提供者：

🌐 The response should include your provider under external:

1
{
2
  "external": {
3
    "google": true
4
  }
5
}

供应商特定设置 #

🌐 Provider-specific setup

1
GOOGLE_ENABLED=true
2
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
3
GOOGLE_SECRET=your-google-client-secret

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}
5
    GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
6
    GOTRUE_EXTERNAL_GOOGLE_SECRET: ${GOOGLE_SECRET}
7
    GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI: ${API_EXTERNAL_URL}/callback

其他支持的提供商 #

🌐 Other supported providers

Supabase Auth 支持以下 OAuth 提供商：

🌐 Supabase Auth supports the following OAuth providers:

对于每个提供者，你至少需要在 .env 和 docker-compose.yml 中有 ENABLED、CLIENT_ID、SECRET 和 REDIRECT_URI。

🌐 For each provider, you need at minimum ENABLED, CLIENT_ID, SECRET, and REDIRECT_URI in .env and docker-compose.yml.

测试登录流程 #

🌐 Test the login flow

你可以用下面这个最简 HTML 页面来测试 OAuth：

🌐 You can test OAuth with the following minimal HTML page:

• 把下面的代码保存到 index.html
• 在同一目录下启动 python -m http.server 3000
• 确保在你自托管的 Supabase .env 配置中将 SITE_URL 设置为 http://localhost:3000
• 打开你的浏览器，然后访问 http://localhost:3000

1
<!doctype html>
2
<html>
3
  <body>
4
    <h1>Supabase OAuth Test</h1>
5
    <button id="loginBtn">Sign in with Google</button>
6
    <pre id="result"></pre>
7
8
    <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
9
    <script>
10
      document.addEventListener('DOMContentLoaded', function () {
11
        const SUPABASE_URL = 'https://<your-domain>'
12
        const SUPABASE_ANON_KEY = 'your-anon-key'
13
14
        const supabase = window.supabase.createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
15
16
        const button = document.getElementById('loginBtn')
17
18
        button.addEventListener('click', async () => {
19
          const { error } = await supabase.auth.signInWithOAuth({
20
            provider: 'google',
21
          })
22
23
          if (error) {
24
            document.getElementById('result').textContent = JSON.stringify(error, null, 2)
25
          }
26
        })
27
28
        supabase.auth.getSession().then(({ data }) => {
29
          if (data.session) {
30
            document.getElementById('result').textContent =
31
              'Logged in as: ' + data.session.user.email
32
          }
33
        })
34
      })
35
    </script>
36
  </body>
37
</html>

有关详细的客户端集成，请参见 社交登录。

🌐 For detailed client-side integration, see Social Login.

故障排除 #

🌐 Troubleshooting

“提供者未启用”或在设置中看到提供者为假 #

🌐 "Provider not enabled" or provider seen as false in settings

• 检查一下 docker-compose.yml 中的 GOTRUE_EXTERNAL_*_ENABLED 是否设置为 true
• 确认 .env 变量不为空，比如用 sh run.sh printenv auth | grep GOOGLE 检查

变量已经添加到环境中了，但提供程序还是不工作 #

🌐 Variables added to the environment but provider still not working

.env 的配置变量不会自动在容器内可用，除非 docker-compose.yml 中有匹配的透传定义。可以检查，例如:

🌐 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:

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_EXTERNAL_GOOGLE_ENABLED: ${GOOGLE_ENABLED}

运行 sh run.sh printenv auth | grep GOTRUE_EXTERNAL 来验证变量是否到达容器。

🌐 Run sh run.sh printenv auth | grep GOTRUE_EXTERNAL to verify the variables are reaching the container.

登录后网站网址或重定向网址错误 #

🌐 Site URL or redirect URL errors after login

在成功的 OAuth 登录后，认证服务会重定向到 SITE_URL 或来自 ADDITIONAL_REDIRECT_URLS 的 URL。请确保：

🌐 After a successful OAuth login, the Auth service redirects to SITE_URL or a URL from ADDITIONAL_REDIRECT_URLS. Ensure:

• .env 中的 SITE_URL 设置为你的 应用的网址
• 如果你的应用使用了不同的重定向 URL，把它添加到 ADDITIONAL_REDIRECT_URLS（用逗号分隔）

手机上随机数检查失败（使用谷歌登录） #

🌐 Nonce check failure on mobile (Google Sign In)

在移动设备上使用带有 ID 令牌的 Google 登录时，nonce 验证可能会失败，因为移动 SDK 并不总是支持身份验证服务所期望的 nonce 流程。

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

要启用它，请取消注释 docker-compose.yml 中的以下行：

🌐 To enable it, uncomment the following line in docker-compose.yml:

1
auth:
2
  environment:
3
    # ... existing variables ...
4
    GOTRUE_EXTERNAL_SKIP_NONCE_CHECK: 'true'

认证服务无法启动 #

🌐 Auth service fails to start

查看认证容器日志：

🌐 Check the auth container logs:

1
docker compose logs auth

常见原因：

🌐 Common causes:

• 缺少必要的环境变量（例如，CLIENT_ID 或 SECRET 为空）
• 无效的 API_EXTERNAL_URL（必须是有效的 URL——包括协议并以 /auth/v1 结尾）

环境变量引用 #

🌐 Environment variable reference

docker-compose.yml 中 auth 服务的所有 OAuth 相关环境变量：

🌐 All OAuth-related environment variables for the auth service in docker-compose.yml:

额外资源 #

🌐 Additional resources

• 重定向网址
• GitHub上的认证服务器（查看README和 example.env）