mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
docs: add user and identity management sections (#18767)
* docs: add user management section * Update apps/docs/pages/guides/auth/auth-user-management.mdx Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com> * Update apps/docs/pages/guides/auth/auth-user-management.mdx Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com> * Update apps/docs/pages/guides/auth/auth-user-management.mdx Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com> * docs: add identity linking guide * Update apps/docs/pages/guides/auth/auth-identity-linking.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Update apps/docs/pages/guides/auth/auth-identity-linking.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * Update apps/docs/pages/guides/auth/auth-identity-linking.mdx Co-authored-by: Charis <26616127+charislam@users.noreply.github.com> * docs: update unlinkIdentity example * docs: add js client lib references --------- Co-authored-by: Joel Lee <lee.yi.jie.joel@gmail.com> Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>
This commit is contained in:
4 files changed
+174
No files matched your search
@@ -542,6 +542,16 @@ export const auth = {
|
||||
name: 'User Sessions',
|
||||
url: '/guides/auth/sessions',
|
||||
},
|
||||
{
|
||||
name: 'User Management',
|
||||
url: '/guides/auth/auth-user-management',
|
||||
items: [
|
||||
{
|
||||
name: 'Identity Linking',
|
||||
url: '/guides/auth/auth-identity-linking',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
name: 'Enterprise SSO',
|
||||
url: '/guides/auth/enterprise-sso',
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
import Layout from '~/layouts/DefaultGuideLayout'
|
||||
|
||||
export const meta = {
|
||||
id: 'auth-identity-linking',
|
||||
title: 'Identity Linking',
|
||||
description: 'Manage the identities associated with your user',
|
||||
subtitle: 'Manage the identities associated with your user',
|
||||
}
|
||||
|
||||
## The User Identity
|
||||
|
||||
The user identity represents an authentication method associated to the user. For example, if a user signs in using their email, an email identity will be associated with the user.
|
||||
|
||||
The user identity object contains the following attributes:
|
||||
|
||||
| Attributes | Type | Description |
|
||||
| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| id | `string` | The provider id returned by the provider. If the provider is an OAuth provider, the id refers to the user's account with the OAuth provider. If the provider is `email` or `phone`, the id is the user's id from the `auth.users` table. |
|
||||
| user_id | `string` | The user's id that the identity is linked to. |
|
||||
| identity_data | `object` | The identity metadata. |
|
||||
| identity_id | `string` | The unique id of the identity. |
|
||||
| provider | `string` | The provider name. |
|
||||
| created_at | `string` | The timestamp that the identity was created. |
|
||||
| last_sign_in_at | `string` | The timestamp that the identity was last used to sign in. |
|
||||
| updated_at | `string` | The timestamp that the identity was last updated. |
|
||||
|
||||
## Identity linking strategies
|
||||
|
||||
Currently, Supabase Auth supports 2 strategies to link an identity to a user:
|
||||
|
||||
1. [Automatic Linking](#automatic-linking)
|
||||
2. [Manual Linking](#manual-linking-beta)
|
||||
|
||||
### Automatic linking
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Users that signed up with [SAML SSO](/docs/guides/auth/sso/auth-sso-saml) will not be considered as targets for automatic linking.
|
||||
|
||||
### Manual linking (Beta)
|
||||
|
||||
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()`](/docs/reference/javascript/auth-linkidentity):
|
||||
|
||||
```js
|
||||
const { data, error } = await supabase.auth.linkIdentity({ provider: 'google' })
|
||||
```
|
||||
|
||||
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](/dashboard/project/_/settings/auth).
|
||||
|
||||
## Unlink an identity
|
||||
|
||||
You can use [`getUserIdentities()`](/docs/reference/javascript/auth-getuseridentities) to fetch all the identities linked to a user. Then, call [`unlinkIdentity()`](/docs/reference/javascript/auth-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.
|
||||
|
||||
```js
|
||||
// retrieve all identities linked to a user
|
||||
const {
|
||||
data: { identities },
|
||||
} = await supabase.auth.getUserIdentities()
|
||||
|
||||
// find the google identity linked to the user
|
||||
const googleIdentity = identities.find((identity) => identity.provider === 'google')
|
||||
|
||||
// unlink the google identity from the user
|
||||
const { data, error } = await supabase.auth.unlinkIdentity(googleIdentity)
|
||||
```
|
||||
|
||||
export const Page = ({ children }) => <Layout meta={meta} children={children} />
|
||||
|
||||
export default Page
|
||||
@@ -0,0 +1,87 @@
|
||||
import Layout from '~/layouts/DefaultGuideLayout'
|
||||
|
||||
export const meta = {
|
||||
id: 'auth-user-management',
|
||||
title: 'User Management',
|
||||
description: 'Manage your users with Supabase Auth',
|
||||
subtitle: 'Manage your users with Supabase Auth',
|
||||
}
|
||||
|
||||
## The User Object
|
||||
|
||||
The user object stores all the information related to a user in your application. The user object can be retrieved using one of these methods:
|
||||
|
||||
1. [`supabase.auth.getUser()`](/docs/reference/javascript/auth-getuser)
|
||||
2. Retrieve a user object as an admin using [`supabase.auth.admin.getUserById()`](/docs/reference/javascript/auth-admin-listusers)
|
||||
|
||||
A user can sign in with one of the following methods:
|
||||
|
||||
- Password-based method (with email or phone)
|
||||
- Passwordless method (with email or phone)
|
||||
- OAuth
|
||||
- SAML SSO
|
||||
|
||||
An identity describes the authentication method that a user can use to sign in. A user can have multiple identities. These are the types of identities supported:
|
||||
|
||||
- Email
|
||||
- Phone
|
||||
- OAuth
|
||||
- SAML
|
||||
|
||||
<Admonition type="note">
|
||||
|
||||
A user with an email or phone identity will be able to sign in with either a password or passwordless method (e.g. use a one-time password (OTP) or magiclink). By default, a user with an unverified email or phone number will not be able to sign in.
|
||||
|
||||
</Admonition>
|
||||
|
||||
The user object contains the following attributes:
|
||||
|
||||
| Attributes | Type | Description |
|
||||
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| id | `string` | The unique id of the identity of the user. |
|
||||
| aud | `string` | The audience claim. |
|
||||
| role | `string` | The role claim used by Postgres to perform Role Level Security (RLS) checks. |
|
||||
| email | `string` | The user's email address. |
|
||||
| email_confirmed_at | `string` | The timestamp that the user's email was confirmed. If null, it means that the user's email is not confirmed. |
|
||||
| phone | `string` | The user's phone number. |
|
||||
| phone_confirmed_at | `string` | The timestamp that the user's phone was confirmed. If null, it means that the user's phone is not confirmed. |
|
||||
| confirmed_at | `string` | The timestamp that either the user's email or phone was confirmed. If null, it means that the user does not have a confirmed email address and phone number. |
|
||||
| last_sign_in_at | `string` | The timestamp that the user last signed in. |
|
||||
| app_metadata | `object` | The `provider` attribute indicates the first provider that the user used to sign up with. The `providers` attribute indicates the list of providers that the user can use to login with. |
|
||||
| user_metadata | `object` | Defaults to the first provider's identity data but can contain additional custom user metadata if specified. Refer to [**User Identity**](/docs/guides/auth/auth-identity-linking#the-user-identity) for more information about the identity object. |
|
||||
| identities | `UserIdentity[]` | Contains an object array of identities linked to the user. |
|
||||
| created_at | `string` | The timestamp that the user was created. |
|
||||
| updated_at | `string` | The timestamp that the user was last updated. |
|
||||
|
||||
## Configuration
|
||||
|
||||
Supabase Auth provides these [configuration options](/dashboard/project/_/settings/auth) to control user access to your application:
|
||||
|
||||
- **Allow new users to sign up**: Users will be able to sign up. If this config is disabled, only existing users can sign in.
|
||||
- **Allow unverified email sign in**: Users will not need to have a verified email address to sign in.
|
||||
|
||||
- If enabled, you can structure your RLS policies to provide different access controls to a user with an unverified email and a user with a verified email. For example,
|
||||
|
||||
```sql
|
||||
-- Allows a user to read all posts regardless of whether they have a verified email address
|
||||
create policy "policy_name"
|
||||
ON public.posts
|
||||
for select to authenticated using (
|
||||
true
|
||||
);
|
||||
|
||||
-- Only allow users with a verified email address to insert posts
|
||||
create policy "policy_name"
|
||||
ON public.posts
|
||||
for insert to authenticated with check (
|
||||
auth.jwt()->>'email_verified' is true
|
||||
);
|
||||
```
|
||||
|
||||
- **Confirm Email (Deprecated)**: Users will need to confirm their email address before signing in for the first time.
|
||||
- Having **Confirm Email** disabled assumes that the user's email does not need to be verified in order to login and implicitly confirms the user's email in the database.
|
||||
- If you previously relied on this config to autoconfirm a user's email address, you can switch to use **Allow unverified email sign in** instead. This new option allows the user to sign in with an unverified email which you can keep track of through the user object. It provides more versatility if you require your users to verify their email address in the future since you can structure your RLS policies to check the user's `email_verified` field.
|
||||
|
||||
export const Page = ({ children }) => <Layout meta={meta} children={children} />
|
||||
|
||||
export default Page
|
||||
@@ -639,9 +639,15 @@ functions:
|
||||
isSpotlight: true
|
||||
code: |
|
||||
```js
|
||||
// retrieve all identites linked to a user
|
||||
const identities = await supabase.auth.getUserIdentities()
|
||||
|
||||
// find the google identity
|
||||
const googleIdentity = identities.find(
|
||||
identity => identity.provider === 'google'
|
||||
)
|
||||
|
||||
// unlink the google identity
|
||||
const { data, error } = await supabase.auth.unlinkIdentity(googleIdentity)
|
||||
```
|
||||
- id: send-password-reauthentication
|
||||
|
||||
Reference in new issue
Block a user