Auth

Custom Claims & Role-based Access Control (RBAC)

Custom Claims are special attributes attached to a user that you can use to control access to portions of your application. For example:


_10
{
_10
"user_role": "admin",
_10
"plan": "TRIAL",
_10
"user_level": 100,
_10
"group_name": "Super Guild!",
_10
"joined_on": "2022-05-20T14:28:18.217Z",
_10
"group_manager": false,
_10
"items": ["toothpick", "string", "ring"]
_10
}

To implement Role-Based Access Control (RBAC) with custom claims, use a Custom Access Token Auth Hook. This hook runs before a token is issued. You can use it to add additional claims to the user's JWT.

This guide uses the Slack Clone example to demonstrate how to add a user_role claim and use it in your Row Level Security (RLS) policies.

Create a table to track user roles and permissions

In this example, you will implement two user roles with specific permissions:

  • moderator: A moderator can delete all messages but not channels.
  • admin: An admin can delete all messages and channels.
supabase/migrations/init.sql

_21
-- Custom types
_21
create type public.app_permission as enum ('channels.delete', 'messages.delete');
_21
create type public.app_role as enum ('admin', 'moderator');
_21
_21
-- USER ROLES
_21
create table public.user_roles (
_21
id bigint generated by default as identity primary key,
_21
user_id uuid references public.users on delete cascade not null,
_21
role app_role not null,
_21
unique (user_id, role)
_21
);
_21
comment on table public.user_roles is 'Application roles for each user.';
_21
_21
-- ROLE PERMISSIONS
_21
create table public.role_permissions (
_21
id bigint generated by default as identity primary key,
_21
role app_role not null,
_21
permission app_permission not null,
_21
unique (role, permission)
_21
);
_21
comment on table public.role_permissions is 'Application permissions for each role.';

You can now manage your roles and permissions in SQL. For example, to add the mentioned roles and permissions from above, run:

supabase/seed.sql

_10
insert into public.role_permissions (role, permission)
_10
values
_10
('admin', 'channels.delete'),
_10
('admin', 'messages.delete'),
_10
('moderator', 'messages.delete');

Create Auth Hook to apply user role

The Custom Access Token Auth Hook runs before a token is issued. You can use it edit the JWT.

Enable the hook

In the dashboard, navigate to Authentication > Hooks (Beta) and select the appropriate PostgreSQL function from the dropdown menu.

When developing locally, follow the local development instructions.

Accessing custom claims in RLS policies

To utilize Role-Based Access Control (RBAC) in Row Level Security (RLS) policies, create an authorize method that reads the user's role from their JWT and checks the role's permissions:

supabase/migrations/init.sql

_16
create function public.authorize(
_16
requested_permission app_permission
_16
)
_16
returns boolean as $$
_16
declare
_16
bind_permissions int;
_16
begin
_16
select count(*)
_16
from public.role_permissions
_16
where role_permissions.permission = authorize.requested_permission
_16
and (role_permissions.role = (select (auth.jwt() ->> 'user_role')::public.app_role))
_16
into bind_permissions;
_16
_16
return bind_permissions > 0;
_16
end;
_16
$$ language plpgsql security definer set search_path = public;

You can then use the authorize method within your RLS policies. For example, to enable the desired delete access, you would add the following policies:


_10
create policy "Allow authorized delete access" on public.channels for delete using ( authorize('channels.delete') );
_10
create policy "Allow authorized delete access" on public.messages for delete using ( authorize('messages.delete') );

Accessing custom claims in your application

The auth hook will only modify the access token JWT but not the auth response. Therefore, to access the custom claims in your application, e.g. your browser client, or server-side middleware, you will need to decode the access_token JWT on the auth session.

In a JavaScript client application you can for example use the jwt-decode package:


_10
import { jwtDecode } from 'jwt-decode'
_10
_10
const { subscription: authListener } = supabase.auth.onAuthStateChange(async (event, session) => {
_10
if (session) {
_10
const jwt = jwtDecode(session.access_token)
_10
const userRole = jwt.user_role
_10
}
_10
})

For server-side logic you can use packages like express-jwt, koa-jwt, PyJWT, dart_jsonwebtoken, Microsoft.AspNetCore.Authentication.JwtBearer, etc.

Conclusion

You now have a robust system in place to manage user roles and permissions within your database that automatically propagates to Supabase Auth.

More resources