身份关联

Manage the identities associated with your user

身份关联策略 #

🌐 Identity linking strategies

目前，Supabase Auth 支持两种策略将身份与用户关联：

🌐 Currently, Supabase Auth supports 2 strategies to link an identity to a user:

自动链接
手动链接

SSO 账户不进行身份关联

为了安全起见，通过 SAML SSO 注册的用户将不会被视为身份关联（自动或手动）的对象。

🌐 Users that signed up with SAML SSO will not be considered as targets for identity linking (automatic or manual) for security reasons.

自动链接 #

🌐 Automatic linking

Supabase Auth 会自动把使用相同邮箱地址的身份绑定到同一个用户。这在提供多个 OAuth 登录选项时可以提升用户体验，因为用户不需要记住自己是用哪个 OAuth 账号注册的。当新用户通过 OAuth 登录时，Supabase Auth 会尝试查找是否已有使用相同邮箱的用户。如果找到匹配，就会把新的身份绑定到该用户上。

🌐 Supabase Auth automatically links identities with the same email address to a single user. This helps to improve the user experience when multiple OAuth login options are presented since the user does not need to remember which OAuth account they used to sign up with. When a new user signs in with OAuth, Supabase Auth will attempt to look for an existing user that uses the same email address. If a match is found, the new identity is linked to the user.

为了让自动关联正确识别要关联的用户，Supabase Auth 需要确保所有用户的邮箱都是唯一的。同时，自动将身份关联到未验证邮箱的用户也是不安全的，因为这可能导致预先账户接管攻击。为防止这种情况发生，当一个新身份可以关联到已有用户时，Supabase Auth 会移除所有其他未确认的、已关联到该用户的身份。

🌐 In order for automatic linking to correctly identify the user for linking, Supabase Auth needs to ensure that all user emails are unique. It would also be an insecure practice to automatically link an identity to a user with an unverified email address since that could lead to pre-account takeover attacks. To prevent this from happening, when a new identity can be linked to an existing user, Supabase Auth will remove any other unconfirmed identities linked to an existing user.

手动链接（测试版） #

🌐 Manual linking (beta)

Supabase Auth 允许用户在登录时使用不同的电子邮件地址发起身份绑定。要将 OAuth 身份绑定到用户，请调用 linkIdentity()：

🌐 Supabase Auth allows a user to initiate identity linking with a different email address when they are logged in. To link an OAuth identity to the user, call linkIdentity():

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
4
5
// ---cut---
6
const { data, error } = await supabase.auth.linkIdentity({ provider: 'google' })

在上面的例子中，用户会被重定向到 Google 来完成 OAuth2.0 流程。一旦 OAuth2.0 流程成功完成，用户会被重定向回应用，并且 Google 身份将与用户关联。你可以通过项目的认证配置选项启用手动关联，或者在自托管时设置环境变量 GOTRUE_SECURITY_MANUAL_LINKING_ENABLED: true。

🌐 In the example above, the user will be redirected to Google to complete the OAuth2.0 flow. Once the OAuth2.0 flow has completed successfully, the user will be redirected back to the application and the Google identity will be linked to the user. You can enable manual linking from your project's authentication configuration options or by setting the environment variable GOTRUE_SECURITY_MANUAL_LINKING_ENABLED: true when self-hosting.

将身份与本地 OAuth（ID 令牌）关联 #

🌐 Link identity with native OAuth (ID token)

对于原生移动应用，你可以使用从第三方 OAuth 提供商获取的 ID 令牌来关联身份。当你想使用原生的 OAuth 流程（比如 Google 登录或 Apple 登录）而不是基于网页的 OAuth 重定向时，这会很有用。

🌐 For native mobile applications, you can link an identity using an ID token obtained from a third-party OAuth provider. This is useful when you want to use native OAuth flows (like Google Sign-In or Sign in with Apple) rather than web-based OAuth redirects.

1
// Example with Google Sign-In (using a native Google Sign-In library)
2
const idToken = 'ID_TOKEN_FROM_GOOGLE'
3
const accessToken = 'ACCESS_TOKEN_FROM_GOOGLE'
4
5
const { data, error } = await supabase.auth.linkIdentity({
6
  provider: 'google',
7
  token: idToken,
8
  access_token: accessToken,
9
})

解除身份绑定 #

🌐 Unlink an identity

你可以使用 getUserIdentities() 来获取与用户关联的所有身份。然后，调用 unlinkIdentity() 来解绑身份。用户需要登录，并且至少有两个已绑定的身份才能解绑现有身份。

🌐 You can use getUserIdentities() to fetch all the identities linked to a user. Then, call unlinkIdentity() to unlink the identity. The user needs to be logged in and have at least 2 linked identities in order to unlink an existing identity.

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
4
5
// ---cut---
6
// retrieve all identities linked to a user
7
const { data: identities, error: identitiesError } = await supabase.auth.getUserIdentities()
8
9
if (!identitiesError) {
10
  // find the google identity linked to the user
11
  const googleIdentity = identities.identities.find((identity) => identity.provider === 'google')
12
13
  if (googleIdentity) {
14
    // unlink the google identity from the user
15
    const { data, error } = await supabase.auth.unlinkIdentity(googleIdentity)
16
  }
17
}

常见问题 #

🌐 Frequently asked questions

🌐 How to add email/password login to an OAuth account?

调用 updateUser({ password: 'validpassword'}) 为使用 OAuth 提供商（Google、GitHub 等）创建的账户添加带密码认证的邮箱。

🌐 Call the updateUser({ password: 'validpassword'}) to add email with password authentication to an account created with an OAuth provider (Google, GitHub, etc.).

🌐 Can you sign up with email if already using OAuth?

如果你尝试用同一个邮箱在之前通过 OAuth 注册过之后创建一个邮箱账户，你会收到一个被混淆的用户响应，并且不会发送验证邮件。这可以防止用户枚举攻击。

🌐 If you try to create an email account after previously signing up with OAuth using the same email, you'll receive an obfuscated user response with no verification email sent. This prevents user enumeration attacks.