Custom Providers（自定义身份认证提供商）允许您通过标准 OAuth 2.0 或 OIDC 协议，将任意第三方身份认证服务配置为 Supabase Auth 的登录提供商。本文介绍如何在 Supabase 控制台中创建和管理自定义 Auth Provider。 ## 背景信息 Supabase Auth 内置了微信、企业微信、CAS、钉钉、飞书等常见登录提供商。当您的业务使用其他身份认证服务（如 Authing、Auth0、Firebase Auth 等）时，可通过 Custom Providers 功能接入任意支持 OAuth 2.0 或 OIDC 协议的第三方提供商，无需等待官方适配。 Custom Providers 支持两种协议类型： * **OIDC**：OpenID Connect 协议，支持自动发现模式，通过 Issuer URL 自动获取 OAuth 端点配置。 * **OAuth2**：OAuth 2.0 协议，需手动填写授权端点、Token 端点、用户信息端点等配置。相关概念可参考 Supabase 官方文档：[Custom OAuth/OIDC Providers](https://supabase.com/docs/guides/auth/custom-oauth-providers)。 ## 前提条件 * 已创建使用 Supabase 引擎的 Workspace，且 Workspace 状态为运行中。关于创建 Workspace 的更多详细信息，请参见[创建 Workspace](https://docs.volcengine.com/docs/87275/2105817?lang=zh)。 * 已通过目标 Workspace 成功登录 Supabase 控制台。关于登录控制台的详细信息，请参见[登录 Supabase 控制台](https://docs.volcengine.com/docs/87275/2105837?lang=zh)。 * 已在第三方身份认证平台完成应用创建，并能获取以下信息： * Client ID 和 Client Secret * Issuer URL（OIDC 自动发现模式）或 OAuth 端点地址（手动配置模式） * 所需的 Scopes（如 openid、email、profile） * 已在第三方身份认证平台的应用配置中，将 Supabase 的 Callback URL 添加到回调地址白名单。 ## 在 Supabase 控制台管理自定义 Auth Provider ### 功能概览在 Supabase 控制台的 Sign In / Providers 页面中，Auth Providers 列表下方新增了 Custom Providers 管理区域。该区域包含以下功能： * **搜索框**：按名称或标识符搜索已配置的自定义提供商。 * **Provider Type 筛选器**：按协议类型筛选，可选值为 OIDC 和 OAuth2。 * **Status 筛选器**：按启用状态筛选，可选值为 Enabled 和 Disabled。 * **+ New Provider 按钮**：创建新的自定义 Auth Provider。 ### 创建自定义 Auth Provider 1. 登录 Supabase 控制台。 2. 在左侧导航栏中选择 **Authentication**。 3. 进入 **Sign In / Providers** 页面。 4. 在 **Custom Providers** 区域，单击 **+ New Provider**。 |**配置项** |**是否必填** |**说明** | |---|---|---| |Provider Identifier

|是 |提供商唯一标识符。前缀固定为 `custom:`，输入部分仅支持小写字母、数字和连字符（\-）。例如输入 `authing`，则完整标识符为 `custom:authing`。在应用端调用时使用该标识符作为 provider 参数。 | |Display Name |是 |提供商的显示名称，展示在提供商列表的 NAME 列中。 | |Configuration Method |是 |配置方式，可选值：

* **Auto\-discovery**（推荐）：通过 Issuer URL 自动获取 OAuth 端点配置。选择该模式时，OAuth Endpoints 部分显示 Issuer URL 和 Discovery URL 字段，适用于标准 OIDC 提供商。配置时，请填写 Issuer URL。系统会在保存时自动访问标准 Discovery 路径获取端点配置。

> **说明**

> 如果提供商使用非标准 Discovery 路径，请在 Discovery URL 字段中填写完整路径；如果留空，则使用标准 Discovery 路径。

* **Manual configuration**：手动填写 OAuth 端点信息。选择该模式时，OAuth Endpoints 部分显示 Issuer URL、Authorization URL、Token URL、Userinfo URL 和 JWKS URI 字段，适用于非标准 OAuth 2.0 或无法通过 Discovery 自动获取端点的提供商。 | |Issuer URL |是 |OAuth 提供商的 Base URL。选择 Auto\-discovery 模式时必填，保存时系统会自动执行 Discovery 并获取端点配置。 | |Discovery URL |否（Auto\-discovery 模式） |OIDC Discovery 端点地址。留空时使用标准路径 `{issuer}/.well-known/openid-configuration`。仅在提供商使用非标准 discovery 路径时填写。 | |Authorization URL |是（Manual configuration 模式） |仅在选择 Manual configuration 时显示。OAuth 授权端点地址，用于跳转到第三方身份认证平台完成用户授权。示例：`https://auth.company.com/oauth/authorize`。 | |Token URL |是（Manual configuration 模式） |仅在选择 Manual configuration 时显示。OAuth Token 端点地址，用于使用授权码换取 Access Token。示例：`https://auth.company.com/oauth/token`。 | |Userinfo URL |是（Manual configuration 模式） |仅在选择 Manual configuration 时显示。用户信息端点地址，用于获取第三方账号的用户信息。示例：`https://auth.company.com/oauth/userinfo`。 | |JWKS URI |是（Manual configuration 模式） |仅在选择 Manual configuration 时显示。JWKS 地址，用于 ID token verification。示例：`https://auth.company.com/.well-known/jwks.json`。 | |Client ID |是 |在第三方身份认证平台创建应用时获取的 Client ID。 | |Client Secret |是 |在第三方身份认证平台创建应用时获取的 Client Secret。 | |Scopes |否 |OAuth 授权范围，多个值以逗号分隔。常见值：openid、email、profile。对于标准 OAuth 2.0 服务，至少需包含 openid。 | |Allow users without email |否 |是否允许提供商不返回邮箱地址时仍可登录。默认关闭，开启后用户即使无邮箱也能完成注册和登录。 | |Callback URL |— |只读字段，系统自动生成。格式如：`https://{workspace-domain}/auth/v1/callback`。需在第三方身份认证平台的应用配置中，将该地址添加到回调 URL 白名单。 | ### 编辑自定义 Auth Provider 1. **在 Sign In / Providers** 页面的 **Custom Providers** 区域，找到目标 Provider。 2. 单击目标 Provider 右侧的更多操作菜单（⋮），选择 **Update**，进入 **Update Custom Auth Provider** 页面。 3. 按需修改 Provider 配置。编辑页字段与新建时相同，但 Provider Identifier 和 Configuration Method 不可修改。 4. 单击 **Update provider** 保存修改。如需放弃修改，单击 **Cancel**。 ### 禁用自定义 Auth Provider 1. **在 Custom Providers 列表中，找到目标 Provider。** 2. 单击目标 Provider 右侧的更多操作菜单（⋮），选择 **Disable**。 3. 在确认弹窗中确认信息无误后，单击 **Confirm disable**。如需取消操作，单击 **Cancel**。 > **注意** > 禁用后，用户将无法通过该 Provider 登录。已有会话不受影响，但在重新启用该 Provider 前，新的登录请求会失败。禁用前，请确认使用该 Provider 登录的用户和依赖该 Provider 的应用已完成相应处理。 ### 删除自定义 Auth Provider 1. **在 Custom Providers 列表中，找到目标 Provider。** 2. 单击目标 Provider 右侧的更多操作菜单（⋮），选择 **Delete**。 3. 在确认弹窗中确认信息无误后，单击 **Confirm delete**。如需取消操作，单击 **Cancel**。 > **注意** > 删除操作不可撤销。如需恢复已删除的自定义 Auth Provider，需要重新创建。删除前，请确认使用该 Provider 登录的用户访问影响，并确认该 Provider 不再被任何应用使用。 ## 通过 Admin API 管理自定义 Auth Provider ### 创建自定义 Auth Provider `POST /auth/v1/admin/custom-providers` OIDC 完整参数示例： ```Bash curl -X POST "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider_type": "oidc", "identifier": "custom:company", "name": "Company SSO", "client_id": "your-client-id", "client_secret": "your-client-secret", "acceptable_client_ids": [], "scopes": ["openid", "email", "profile"], "pkce_enabled": true, "attribute_mapping": {"email": "email", "name": "name"}, "custom_claims_allowlist": ["groups", "org_id"], "authorization_params": {"prompt": "login"}, "enabled": true, "email_optional": false, "issuer": "https://sso.example.com", "discovery_url": "https://sso.example.com/.well-known/openid-configuration", "skip_nonce_check": false }' ``` OAuth 2.0 完整参数示例： ```Bash curl -X POST "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider_type": "oauth2", "identifier": "custom:company", "name": "Company OAuth", "client_id": "your-client-id", "client_secret": "your-client-secret", "acceptable_client_ids": [], "scopes": ["email", "profile"], "pkce_enabled": true, "attribute_mapping": {"email": "email", "name": "name"}, "custom_claims_allowlist": ["groups", "org_id"], "authorization_params": {"prompt": "login"}, "enabled": true, "email_optional": false, "authorization_url": "https://sso.example.com/oauth/authorize", "token_url": "https://sso.example.com/oauth/token", "userinfo_url": "https://sso.example.com/oauth/userinfo", "jwks_uri": "https://sso.example.com/.well-known/jwks.json" }' ``` ### 查询自定义 Auth Provider `GET /auth/v1/admin/custom-providers/{identifier}` ```Bash curl -X GET "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers/custom:company" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" ``` ### 查询自定义 Auth Provider 列表 `GET /auth/v1/admin/custom-providers` `type` 可取 `oidc` 或 `oauth2`，不传则查询全部。 ```Bash curl -X GET "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers?type=oidc" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" ``` ### 修改自定义 Auth Provider `PUT /auth/v1/admin/custom-providers/{identifier}` OIDC 示例： ```Bash curl -X PUT "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers/custom:company" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Company SSO", "client_id": "your-client-id", "client_secret": "new-client-secret", "acceptable_client_ids": [], "scopes": ["openid", "email", "profile"], "pkce_enabled": true, "attribute_mapping": {"email": "email", "name": "name"}, "custom_claims_allowlist": ["groups", "org_id"], "authorization_params": {"prompt": "login"}, "enabled": true, "email_optional": false, "issuer": "https://sso.example.com", "discovery_url": "https://sso.example.com/.well-known/openid-configuration", "skip_nonce_check": false }' ``` OAuth 2.0 示例： ```Bash curl -X PUT "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers/custom:company" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Company OAuth", "client_id": "your-client-id", "client_secret": "new-client-secret", "acceptable_client_ids": [], "scopes": ["email", "profile"], "pkce_enabled": true, "attribute_mapping": {"email": "email", "name": "name"}, "custom_claims_allowlist": ["groups", "org_id"], "authorization_params": {"prompt": "login"}, "enabled": true, "email_optional": false, "authorization_url": "https://sso.example.com/oauth/authorize", "token_url": "https://sso.example.com/oauth/token", "userinfo_url": "https://sso.example.com/oauth/userinfo", "jwks_uri": "https://sso.example.com/.well-known/jwks.json" }' ``` ### 删除自定义 Auth Provider `DELETE /auth/v1/admin/custom-providers/{identifier}` ```Bash curl -X DELETE "$SUPABASE_BASE_URL/auth/v1/admin/custom-providers/custom:company" \ -H "apikey: $SERVICE_ROLE_KEY" \ -H "Authorization: Bearer $SERVICE_ROLE_KEY" ``` ## 在第三方平台配置回调地址创建自定义 Auth Provider 时，系统会生成一个 Callback URL（格式如 `https://{workspace-domain}/auth/v1/callback`）。您需要将此地址配置到第三方身份认证平台的回调 URL 白名单中。

AI 原生 BaaS 平台 Supabase 版