apps/www/_blog/2023-12-14-supabase-auth-identity-linking-hooks.mdx
We're excited to announce four new features for Supabase Auth:
When a user signs in, an identity is created with the authentication method and sign-in provider. Historically, Supabase Auth has been automatically linking identities to a user if the identity shares the same verified email as the user. This is convenient to de-duplicate user accounts. However, some developers also need the flexibility to link accounts that don’t share the same email.
Today we are launching Identity Linking, which developers can use to manually link two separate identities. We’ve added two new endpoints for developers to manage the identity linking process:
Once a user is signed in, use linkIdentity() to link an OAuth identity:
const { data, error } = await supabase.auth.linkIdentity({
provider: 'google',
})
Use unlinkIdentity() to unlink an identity:
// 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(({ provider }) => provider === 'google')
// unlink the google identity from the user
const { data, error } = await supabase.auth.unlinkIdentity(googleIdentity)
Currently, these methods support linking an OAuth identity. To link an email or phone identity to the user, you can use the updateUser()method.
Manual linking is disabled by default. You can enable it for your project in the dashboard Auth settings.
<Admonition>See the Identity Linking docs for more information.
</Admonition>Supabase Auth manages the full session lifecycle from the moment your user signs into your application. This involves the following steps:
For developers who want finer control over their users’ sessions, we have exposed 3 new settings:
These session control settings are available on the Pro Plan and above.
<Admonition>See the Session Management docs for more information.
</Admonition>Passwords can be inherently insecure due to common user behaviors like choosing guessable passwords or reusing them across different platforms.
Even though OAuth and magiclinks are more secure, we recognize passwords are here to stay. We want to make the potential pitfalls less user-prone. To accomplish that, we have integrated the HaveIBeenPwned.org Pwned Passwords API in Supabase Auth to prevent users from using leaked passwords.
<Admonition type="note" label="Go library">ℹ️ We have open-sourced a Go library for interacting with the HaveIBeenPwned.org Pwned Passwords API that we use in our Auth server. Check out the repository and feel free to contribute!
</Admonition>As an additional step, we have added the ability to specify password requirements for your users. This can be configured from your project’s Auth settings in the dashboard:
<Admonition>See the password docs for more information.
</Admonition>We’ve received a ton of feedback asking for ways to customize Auth, like:
We aim to maintain a straightforward and seamless Supabase Auth experience. It should work effortlessly for most developers, requiring no customization. However, recognizing the diversity of apps, you can now extend standard Auth features through Auth Hooks.
Auth Hooks are simply Postgres functions that run synchronously at key points in the Auth lifecycle, to change the outcome of the action.
For example, to customize the JWT claims with Auth Hooks, you can create a Postgres function that accepts the JWT claims in the first argument and returns the JWT you wish to be used by Supabase Auth.
Suppose you’re creating a gamified application and you wish to attach the user’s level to the JWT as a custom claim:
create function custom_access_token_hook(event jsonb)
returns jsonb
language plpgsql
as $$
declare
user_level jsonb;
begin
-- fetch the current user's level
select
to_jsonb(level) into user_level
from profiles
where
user_id = event->>'user_id'::uuid;
-- change the event.claims.level
return jsonb_set(
event,
'{claims,level}',
user_level);
end;
$$
Once you’ve created the function in the database, you only need to register it with Supabase Auth:
Currently, you can register an Auth Hook for the following points in the flow:
And if writing PL/pgSQL functions is not your forte, you can always use pg_net to send out requests to your backend APIs instead, or use plv8 to manipulate JSON more easily by writing your function in JavaScript.
Auth Hooks is available today for self-hosting and will be rolled out to the platform next month. Reach out to us via support if you need access sooner!
That’s not all! Postgres functions aren’t the only way to write hooks.
Supabase is a founding contributor of Standard Webhooks, a set of open source tools and guidelines about sending and receiving webhooks easily, securely, and reliably. Naturally, Auth Hooks will be supporting webhooks in Q1 of 2024.
If you’ve been following us from the start, you will know that Supabase Auth started by forking Netlify’s GoTrue server. A lot has changed since then and we’ve diverged from the upstream repository. At this stage it makes sense to rename the project to something else (cues drumroll) — Auth.
This simply means that the repositories will be renamed from using gotrue to auth. But don’t worry! Docker images and libraries like @supabase/gotrue-js will continue to be published and you can use @supabase/auth-js interchangeably for the current v2 version for as long as it is supported. All of the classes and methods remain in place. No breaking changes here!
Thanks for reading till the end! We hope you enjoyed the Supabase Auth updates for Launch Week X: Identity Linking, Session Control, Leaked Password Protection, and Auth Hooks with Postgres functions.
We are looking forward to seeing what you build with these new features, and, of course, your feedback to make them even better.