Skip to content
Self-Hosting

配置通行密钥认证

Set up passkey authentication for self-hosted Supabase.

概览 #

🌐 Overview

Passkeys 是基于 WebAuthn 标准的无密码、防网络钓鱼凭证。本指南介绍了在自托管 Supabase 实例中启用 passkey 身份验证的服务器端配置。有关 passkeys 的工作原理以及如何在客户端使用它们，请参阅 Passkey 身份验证 指南。

启用密码密钥认证 #

🌐 Enable passkey authentication

对于自托管的 Supabase，密码密钥认证是通过传递给 docker-compose.yml 中认证服务的环境变量来配置的。下面的变量控制密码密钥认证和 WebAuthn 配置。

🌐 For self-hosted Supabase, passkey authentication is configured through environment variables passed to the auth service in docker-compose.yml. The variables below control passkey authentication and WebAuthn configuration.

变量描述默认
GOTRUE_PASSKEY_ENABLED启用密码密钥认证。false
GOTRUE_PASSKEY_MAX_PASSKEYS_PER_USER单个用户可以注册的最大通行密钥数量。10
GOTRUE_WEBAUTHN_RP_ID你应用的裸域名（WebAuthn 受信方 ID）。不要包含协议、端口或路径。这决定了可以使用哪些通行密钥。启用通行密钥认证时必填。-
GOTRUE_WEBAUTHN_RP_DISPLAY_NAME你的应用的可读名称，会在通行密钥提示时显示。启用通行密钥认证时必填。-
GOTRUE_WEBAUTHN_RP_ORIGINS允许的来源列表，用逗号分隔（例如，https://example.com,https://app.example.com）。启用密钥验证时必填。-
GOTRUE_WEBAUTHN_CHALLENGE_EXPIRY_DURATIONWebAuthn 挑战有效的时间。如果在这个时间内没有完成认证流程，客户端必须请求一个新的挑战。5m

配置认证服务 #

🌐 Configure the Auth service

将环境变量添加到你在 docker-compose.yml 中的 auth 服务：

🌐 Add the environment variables to the auth service in your docker-compose.yml:

docker-compose.yml
services:
  auth:
    environment:
      # ... existing variables ...
      GOTRUE_PASSKEY_ENABLED: true
      GOTRUE_PASSKEY_MAX_PASSKEYS_PER_USER: 10 # optional - default is 10
      GOTRUE_WEBAUTHN_RP_ID: example.com
      GOTRUE_WEBAUTHN_RP_DISPLAY_NAME: my-app
      GOTRUE_WEBAUTHN_RP_ORIGINS: https://example.com,https://app.example.com
      GOTRUE_WEBAUTHN_CHALLENGE_EXPIRY_DURATION: 5m # optional - default is 5 minutes

WebAuthn 需要安全环境，所以在设置 GOTRUE_WEBAUTHN_RP_ORIGINS 时，请记住以下要求：

🌐 WebAuthn requires a secure context, so when setting GOTRUE_WEBAUTHN_RP_ORIGINS, keep the following requirements in mind:

  • 源必须使用 HTTPS，除非是回环地址（localhost、127.0.0.1、[::1]）。
  • 每个来源的主机名必须与 GOTRUE_WEBAUTHN_RP_ID 匹配或是其子域名。
  • Android 原生应用可以使用形式为 android:apk-key-hash:<base64url SHA-256 of the signing certificate> 的应用来源。

本地测试时，将 GOTRUE_WEBAUTHN_RP_ID 设置为 localhost，并使用 http://localhost:3000 作为来源。

🌐 For local testing, set GOTRUE_WEBAUTHN_RP_ID to localhost and use http://localhost:3000 as the origin.

重新启动认证服务 #

🌐 Relaunch the Auth service

更新环境变量后，重启认证服务让更改生效：

🌐 After updating the environment variables, relaunch the auth service for the changes to take effect:

sh run.sh recreate auth

确认已启用密钥 #

🌐 Verify passkeys are enabled

请求一个身份验证挑战，以确认认证服务已经获取了配置：

🌐 Request an authentication challenge to confirm the auth service picked up the configuration:

curl -X POST 'http://<your-domain>/auth/v1/passkeys/authentication/options' \
  -H 'apikey: your-supabase-publishable-key'

一个包含 challenge_id 的 200 响应表明已启用密码密钥认证。passkey_disabled 错误意味着认证服务没有检测到配置。

🌐 A 200 response containing a challenge_id confirms that passkey authentication is enabled. A passkey_disabled error means the auth service did not pick up the configuration.

管理用户的密钥 #

🌐 Manage a user's passkeys

使用 Auth 管理 API 从受信任的服务器检查或撤销用户的通行密钥，例如移除丢失的设备。这些调用需要你项目的密钥 SUPABASE_SECRET_KEY，来自你的 .env 文件，并且绝对不能在客户端代码中运行。

🌐 Use the Auth admin API to inspect or revoke a user's passkeys from a trusted server, for example to remove a lost device. These calls require your project's secret key, SUPABASE_SECRET_KEY, from your .env file and must never run in client code.

客户端指南中介绍的 管理 API 针对的是 api.supabase.com，并不适用于自托管部署。请使用上面提到的环境变量配置通行密钥，并通过下面的管理端点管理单个通行密钥。

🌐 The Management API covered in the client guide targets api.supabase.com and isn't available for self-hosted deployments. Configure passkeys with the environment variables above, and manage individual passkeys with the admin endpoints below.

列出用户的密钥 #

🌐 List a user's passkeys

curl 'http://<your-domain>/auth/v1/admin/users/{user_id}/passkeys' \
  -H 'apikey: your-supabase-secret-key'

删除用户的密钥 #

🌐 Delete a user's passkey

curl -X DELETE 'http://<your-domain>/auth/v1/admin/users/{user_id}/passkeys/{passkey_id}' \
  -H 'apikey: your-supabase-secret-key'

删除用户的最后一个通行密钥会让他们无法用通行密钥登录，直到他们注册一个新的为止。

🌐 Deleting a user's last passkey removes their ability to sign in with a passkey until they register a new one.

下一步 #

🌐 Next steps

在你在自托管的 Auth 服务中启用密钥后，像设置托管项目一样配置客户端：创建 Supabase 客户端时选择加入，注册密钥，然后登录。查看 在客户端启用 。

🌐 After you enable passkeys in your self-hosted Auth service, configure the client exactly as you would for a hosted project: opt in when you create the Supabase client, register a passkey, and sign in. See Enable in the client.