自定义 OAuth/OIDC 提供者

自定义 OAuth/OIDC 提供商让你可以将任何符合标准的身份提供商与 Supabase Auth 集成，而不仅仅是 Supabase 开箱即用支持的那些。

🌐 Custom OAuth/OIDC providers let you integrate any standards-compliant identity provider with Supabase Auth, beyond the ones Supabase supports out of the box.

每个自定义提供者在其标识符中都使用 custom: 前缀（例如，custom:my-idp 或 custom:github-enterprise）。这个前缀可以将自定义提供者和内置提供者区分开来。

🌐 Each custom provider uses a custom: prefix in its identifier (for example, custom:my-idp or custom:github-enterprise). This prefix distinguishes custom providers from built-in providers.

有两种供应商类型：

🌐 There are two provider types:

• OAuth2：适用于通用 OAuth2 提供商，你需要手动提供授权、令牌和用户信息端点。
• OIDC：适用于支持 OpenID Connect 发现的提供者。你只需提供发行者 URL，端点会自动解析。

创建一个提供者 #

🌐 Creating a provider

创建表单会显示一个只读的 回调 URL。复制这个 URL，并在完成设置前，将其配置为你外部身份提供者中的重定向/回调 URI。

🌐 The create form displays a read-only Callback URL. Copy this URL and configure it as the redirect/callback URI in your external identity provider before completing setup.

OAuth2 提供者 #

🌐 OAuth2 provider

当你的身份提供者不支持 OpenID Connect 发现时，使用 OAuth2 提供者。你必须明确提供授权、令牌和用户信息端点的 URL。

🌐 Use an OAuth2 provider when your identity provider does not support OpenID Connect discovery. You must supply the authorization, token, and userinfo endpoint URLs explicitly.

OIDC 提供者 #

🌐 OIDC provider

当你的身份提供者支持 OpenID Connect 时，使用 OIDC 提供者。提供 issuer URL，发现文档、JWKS 和端点会自动解析。

🌐 Use an OIDC provider when your identity provider supports OpenID Connect. Supply the issuer URL and the discovery document, JWKS, and endpoints are resolved automatically.

OIDC 提供者有以下自动行为：

🌐 OIDC providers have the following automatic behavior:

• 发现文档是从 {issuer}/.well-known/openid-configuration 获取的（如果设置了，则从 discovery_url 获取）。
• openid 范围总是包含的。如果在 scopes 数组中缺失，它会自动添加。
• ID 令牌会通过提供者的 JWKS（从发现文档的 jwks_uri 获取）进行验证。

提供者标识 #

🌐 Provider identifiers

每个自定义提供商标识必须以 custom: 前缀开头。标识长度为 2–50 个字符，可包含小写字母、数字、连字符和冒号。例如：

🌐 Every custom provider identifier must start with the custom: prefix. Identifiers are 2–50 characters, lowercase alphanumeric with hyphens and colons allowed. Examples:

• custom:my-provider
• custom:github-enterprise

用户登录 #

🌐 User sign-in

一旦创建并启用自定义提供商，用户就可以通过标准的 OAuth 授权端点登录：

🌐 Once a custom provider is created and enabled, users sign in via the standard OAuth authorize endpoint:

1
GET https://your-project.supabase.co/auth/v1/authorize?provider=custom:my-provider

或者使用 Supabase 客户端库：

🌐 Or using the Supabase client libraries:

1
const { data, error } = await supabase.auth.signInWithOAuth({
2
  provider: 'custom:my-provider',
3
})

管理供应商 #

🌐 Managing providers

列出提供商 #

🌐 List providers

更新供应商 #

🌐 Update a provider

更新除了 provider_type 和 identifier 之外的任何提供者字段。只会更改提供的字段（部分更新）。要轮换客户端密钥，只更新 client_secret 字段。

🌐 Update any provider fields except provider_type and identifier. Only provided fields are changed (partial update). To rotate a client secret, update only the client_secret field.

删除供应商 #

🌐 Delete a provider

高级设置 #

🌐 Advanced configuration

PKCE#

PKCE（代码交换证明）默认对所有自定义提供者启用（pkce_enabled: true）。在授权流程中，认证服务器会自动生成代码挑战和验证器，从而防止授权码被截取。这完全由服务器端处理，不需要客户端的 PKCE 逻辑。

🌐 PKCE (Proof Key for Code Exchange) is enabled by default (pkce_enabled: true) for all custom providers. The auth server automatically generates a code challenge and verifier during the authorization flow, protecting against authorization code interception attacks. This is handled entirely server-side, no client-side PKCE logic is needed.

要为特定提供商禁用 PKCE，在创建或更新它时设置 pkce_enabled: false。除非身份提供商不支持 PKCE，否则不推荐这样做。

🌐 To disable PKCE for a specific provider, set pkce_enabled: false when creating or updating it. This is not recommended unless the identity provider does not support PKCE.

授权参数 #

🌐 Authorization params

在 OAuth 流程中附加到提供者授权 URL 的额外查询参数。所有值都必须是字符串。

🌐 Extra query parameters appended to the provider's authorization URL during the OAuth flow. All values must be strings.

1
{
2
  "prompt": "consent",
3
  "access_type": "offline",
4
  "login_hint": "user@example.com"
5
}

以下保留参数由认证服务器管理，无法被覆盖：client_id、client_secret、redirect_uri、response_type、state、code_challenge、code_challenge_method、code_verifier、nonce。

🌐 The following reserved parameters are managed by the auth server and cannot be overridden: client_id, client_secret, redirect_uri, response_type, state, code_challenge, code_challenge_method, code_verifier, nonce.

多平台应用 #

🌐 Multi-platform apps

如果你的应用在不同平台上使用不同的客户端 ID（例如，Web 和移动端），使用 acceptable_client_ids 来列出应该被接受用于 OIDC ID 令牌中的受众验证的其他客户端 ID：

🌐 If your app uses different client IDs for different platforms (for example, web vs mobile), use acceptable_client_ids to list additional client IDs that should be accepted for audience validation in OIDC ID tokens:

1
const { data, error } = await supabase.auth.admin.customProviders.createProvider({
2
  provider_type: 'oidc',
3
  identifier: 'custom:multi-platform-app',
4
  name: 'Multi-Platform App',
5
  client_id: 'web-client-id',
6
  client_secret: 'your-client-secret',
7
  issuer: 'https://app.example.com',
8
  scopes: ['openid', 'profile', 'email'],
9
  acceptable_client_ids: ['ios-client-id', 'android-client-id'],
10
})

可选电子邮件供应商 #

🌐 Email-optional providers

默认情况下，提供者必须返回电子邮件地址。在创建或更新提供者时，将 email_optional 设置为 true 可以允许没有电子邮件的登录。这适用于 OAuth2 和 OIDC 提供者。

🌐 By default, providers must return an email address. Set email_optional to true when creating or updating a provider to allow sign-in without an email. This applies to both OAuth2 and OIDC providers.

OIDC 专用选项 #

🌐 OIDC-specific options

错误参考 #

🌐 Error reference