Part Three: Policies

About#

How to restrict table access to authenticated users, row level policies, and email domain based access.

Watch#

User based row level policies#

Now that we know how to restrict access to tables based on JWT roles, we can combine this with user management to give us much more control over what data your users can read to and write from your database.

We'll start with how user sessions work in Supabase, and later move on to writing user-centric policies.

Let's say we're signing a user up to our service for the first time. The typical way to do this is by invoking the following method in supabase-js:

1// see full api reference here: /docs/reference/javascript/auth-signup
2supabase.auth.signUp({ email, password })

By default this will send a confirmation email to the user. When the user clicks the link in the email, they will be redirected to your site (you need to provide your site url in Auth > Settings on the dashboard. By default this is http://localhost:3000) and the full URL including query params will look something like this:

http://localhost:3000/#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjE2NDI5MDY0LCJzdWIiOiI1YTQzNjVlNy03YzdkLTRlYWYtYThlZS05ZWM5NDMyOTE3Y2EiLCJlbWFpbCI6ImFudEBzdXBhYmFzZS5pbyIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6ImVtYWlsIn0sInVzZXJfbWV0YWRhdGEiOnt9LCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.4IFzn4eymqUNYYo2AHLxNRL8m08G93Qcg3_fblGqDjo&expires_in=3600&refresh_token=RuioJv2eLV05lgH5AlJwTw&token_type=bearer&type=signup

Let's break this up so that it's easier to read:

1// the base url - whatever you set in the Auth Settings in app.supabase.com dashboard
2http://localhost:3000/
3
4// note we use the '#' (fragment) instead of '?' query param
5// the access token is a JWT issued to the user
6#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhdXRoZW50aWNhdGVkIiwiZXhwIjoxNjE2NDI5MDY0LCJzdWIiOiI1YTQzNjVlNy03YzdkLTRlYWYtYThlZS05ZWM5NDMyOTE3Y2EiLCJlbWFpbCI6ImFudEBzdXBhYmFzZS5pbyIsImFwcF9tZXRhZGF0YSI6eyJwcm92aWRlciI6ImVtYWlsIn0sInVzZXJfbWV0YWRhdGEiOnt9LCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.4IFzn4eymqUNYYo2AHLxNRL8m08G93Qcg3_fblGqDjo
7
8// valid for 60 minutes by default
9&expires_in=3600
10
11// use to get a new access_token before 60 minutes expires
12&refresh_token=RuioJv2eLV05lgH5AlJwTw
13
14// can use as the Authorization: Bearer header in requests to your API
15&token_type=bearer
16
17// why was this token issued? was it a signup, login, password reset, or magic link?
18&type=signup

If we put the access_token into https://jwt.io we'll see it decodes to:

1{
2  "aud": "authenticated",
3  "exp": 1616429064,
4  "sub": "5a4365e7-7c7d-4eaf-a8ee-9ec9432917ca",
5  "email": "ant@supabase.io",
6  "app_metadata": {
7    "provider": "email"
8  },
9  "user_metadata": {},
10  "role": "authenticated"
11}

The authenticated role is special in Supabase, it tells the API that this is an authenticated user and will know to compare the JWT against any policies you've added to the requested resource (table or row).

The sub claim is usually what we use to match the JWT to rows in your database, since by default it is the unique identifier of the user in the auth.users table (as a side note - it's generally not recommended to alter the auth schema in any way in your Supabase database since the Auth API relies on it to function correctly).

For the curious, try heading to the SQL editor and querying:

1select * from auth.users;

If supabase-js is loaded on your site (in this case http://localhost:3000) it automatically plucks the access_token out of the URL and initiates a session. You can retrieve the session to see if there is a valid session:

1console.log(supabase.auth.getSession())

Now that we can use methods to issue JWTs to users, we want to start fetching resources specific to that user. So let's make some. Go to the SQL editor and run:

1create table my_scores (
2    name text,
3    score int,
4    user_id uuid not null
5);
6
7ALTER TABLE my_scores ENABLE ROW LEVEL SECURITY;
8
9insert into my_scores(name, score, user_id)
10values
11  ('Paul', 100, '5a4365e7-7c7d-4eaf-a8ee-9ec9432917ca'),
12  ('Paul', 200, '5a4365e7-7c7d-4eaf-a8ee-9ec9432917ca'),
13  ('Leto', 50,  '9ec94326-2e2d-2ea2-22e3-3a535a4365e7');
14
15-- use UUIDs from the auth.users table if you want to try it
16-- for yourself

Now we'll write our policy, again in SQL, but note it's also possible to add via the dashboard in Auth > Policies:

1CREATE POLICY user_update_own_scores ON my_scores
2    FOR ALL
3    USING (auth.uid() = user_id);

Now, assuming you have an active session in your javascript/supabase-js environment you can do:

1supabase.from('my_scores').select('*').then(console.log)

and you should only receive scores belonging to the current logged in user. Alternatively you can use Bash like:

curl 'https://sjvwsaokcugktsdaxxze.supabase.co/rest/v1/my_scores?select=*' \
-H "apikey: <ANON_KEY>" \
-H "Authorization: Bearer <ACCESS_TOKEN>"

Note that the anon key (or service role key) is always needed to get past the API gateway. This can be passed in the apikey header or in a query param named apikey. It is passed automatically in supabase-js as long as you used it to instantiate the client.

There are some more notes here on how to structure your schema to best integrate with the auth.users table.

Once you get the hang of policies you can start to get a little bit fancy. Let's say I work at Blizzard and I only want Blizzard staff members to be able to update people's high scores, I can write something like:

1create policy "Only Blizzard staff can update leaderboard"
2  on my_scores
3  for update using (
4    right(auth.jwt() ->> 'email', 13) = '@blizzard.com'
5  );

Supabase comes with two built-in helper functions: auth.uid() and auth.jwt().

See the full PostgreSQL policy docs here: https://www.postgresql.org/docs/12/sql-createpolicy.html

You can get as creative as you like with these policies.

Resources#

Next steps#