Realtime Broadcast and Presence Authorization

[filipecabaco]

Overview

⚠️ If you want to test this feature please to request it to our Support team to enable it for you and we will do it in due time.

This post explains how authorization works for Realtime Broadcast and Realtime Presence.

This allows you (the developer) to control access to Realtime Channels. We use Postgres Row Level Security to manage access. Developers create “Policies” which allow or deny access for your users.

Usage

Creating Realtime Policies

In your Supabase Studio

1. Select Authentication
2. Select Policies
3. Change the schema to he the realtime schema
4. Click Create a new policy

Now if we wanted to create channels that are only usable by authenticated users we would have the following rules:

Channels rule to connect the channel

-- Set permissions for channels
CREATE POLICY authenticated_read_channel
ON realtime.channels FOR SELECT
TO authenticated
USING ( true );

-- Set permissions for broadcasts
CREATE POLICY authenticated_read_broadcast
ON realtime.broadcasts FOR SELECT
TO authenticated
USING ( true );

CREATE POLICY authenticated_write_broadcast
ON realtime.broadcasts FOR UPDATE
TO authenticated
USING ( true );

-- Set permissions for presences
CREATE POLICY authenticated_read_presence
ON realtime.presences FOR SELECT
TO authenticated
USING ( true );

CREATE POLICY authenticated_write_presence
ON realtime.presences FOR UPDATE
TO authenticated
USING ( true );

The Policies screen will now have the policies you set for each table

Since you are using RLS policies you can do more complex examples.

In a scenario where you have a schema with a table for rooms and one that creates an association between rooms and users.

Example schema to be used in RLS policies

We can build more complex RLS rules using this information:

-- Set permissions for channels
CREATE POLICY authenticated_read_channel
ON realtime.channels FOR SELECT
TO authenticated
USING ( 
	exists(
      select 1
      from public.rooms r join public.rooms_users ru on r.id = ru.room_id
      where ru.user_id = auth.uid()
        and r.name = realtime.channel_name()
  )
);

-- Set permissions for broadcasts
CREATE POLICY authenticated_read_broadcast
ON realtime.broadcasts FOR SELECT
TO authenticated
USING ( 
	exists(
      select 1
      from public.rooms r join public.rooms_users ru on r.id = ru.room_id
      where ru.user_id = auth.uid()
        and r.name = realtime.channel_name()
  )
);

CREATE POLICY authenticated_write_broadcast
ON realtime.broadcasts FOR UPDATE
TO authenticated
USING ( 
	exists(
	  select 1
    from public.rooms r join public.rooms_users ru on r.id = ru.room_id
    where ru.user_id = auth.uid()
      and r.name = realtime.channel_name()
  )
)

-- Set permissions for presences
CREATE POLICY authenticated_write_presence
ON realtime.presences FOR UPDATE
TO authenticated
USING ( 
	exists(
    select 1
    from public.rooms r join public.rooms_users ru on r.id = ru.room_id
    where ru.user_id = auth.uid()
      and r.name = realtime.channel_name()
  )
);

CREATE POLICY authenticated_read_presence
ON realtime.presences FOR SELECT
TO authenticated
USING ( 
	exists(
    select 1
    from public.rooms r join public.rooms_users ru on r.id = ru.room_id
    where ru.user_id = auth.uid()
      and r.name = realtime.channel_name()
  ) 
);

And we can imagine other use cases like checking the role of the user to match a certain value:

-- Policy where only authenticated users with the role admin would be able to broadcast

CREATE POLICY authenticated_write_broadcast
ON realtime.broadcasts FOR UPDATE
TO authenticated
USING ( 
	exists(
	  select 1
    from public.rooms r join public.rooms_users ru on r.id = ru.room_id
    where ru.user_id = auth.uid()
      and r.name = realtime.channel_name()
      and ru.role = 'admin'
  )
);

Creating Authorized channels

Now using your service_role token you can create a channel against our API and this will enable authz checking for channel_1:

curl -v -X POST 'https://<project_ref>.supabase.co/realtime/v1/api/channels'\
 --header 'apikey: <service_role_token>'\
 --header 'Content-Type: application/json'\
 --data-raw '{ "name": "channel_1" }'

Testing Authorization

Now to test it we can use a quick deno script by creating a index.ts

// Run with deno run --allow-net --allow-env --allow-read --allow-ffi index.ts
import { createClient } from "npm:@supabase/supabase-js@2.38.5";
const url = "https://<project_ref>.supabase.com";
const apikey = "<api_key>";

const client = createClient(url, apikey);

const channel = client.channel("channel_1", {
  config: { broadcast: { self: true } },
});
channel
  .on("broadcast", { event: "test" }, (payload) => console.log(payload))
  .on("presence", { event: "join" }, (payload) => console.log(payload))
  .on("presence", { event: "leave" }, (payload) => console.log(payload))
  .subscribe((status: string, err: any) => {
    if (status === "SUBSCRIBED") {
      console.log("Connected!");
    } else {
      console.error(err);
    }
  });

This will return an error with the message You do not have permissions to read from this Channel

But if we change our code to pass along an authenticated user, then we will be able to connect and receive / send messages.

import { createClient } from "npm:@supabase/supabase-js@2.38.5";
const url = "https://wqcmxcvbtvplofojjnqw.supabase.co";
const apikey = "<api_key>";

const client = createClient(url, apikey);

await client.auth.signInWithPassword({
  email: "<email>",
  password: "<password>",
});

client.realtime.setAuth(
  (await client.auth.getSession()).data.session.access_token
);
const channel = client.channel("channel_1", {
  config: { broadcast: { self: true } },
});
channel
  .on("broadcast", { event: "test" }, (payload) => console.log(payload))
  .on("presence", { event: "join" }, (payload) => console.log(payload))
  .on("presence", { event: "leave" }, (payload) => console.log(payload))
  .subscribe((status: string, err: any) => {
    if (status === "SUBSCRIBED") {
      console.log("Connected!");
    } else {
      console.error(err);
    }
  });

Do not forget that RLS policies can use other tables in them so this will give you all the flexibility you need to better fit your use case but be aware of the performance impact of heavy RLS queries or non-indexed fields

Migrating from Public Channels

We infer the behaviour you desire by checking if the realtime.channels table includes an entry for the given channel name meaning that migrating from an unprotected channel to one that follows this new method you would need to:

• Create your RLS rules according to your use case for the realtime.channels, realtime.broadcasts and realtime.presencestables
• Create a new entry with the channel name using the client lib or calling the endpoints directly.

New Endpoints

Due to this new changes, if you want to use this feature, you will need to preemptively create a channel. For this effect we have added new endpoints for Realtime.

This endpoints will respect RLS rules from the given Bearer token.

List all channels
Method: GET
URL: https://<project_ref>.supabase.co/realtime/v1/api/channels

Create channels
Method: POST
URL: https://<project_ref>.supabase.co/realtime/v1/api/channels
body: `{"name":"<channel_name>"}`

Update an existing channel
Method: PUT
URL: https://<project_ref>.supabase.co/realtime/v1/api/channels/<channel_name>
body: `{"name":"<new_channel_name>"}`

Delete existing channel
Method: DELETE
URL: https://<project_ref>.supabase.co/realtime/v1/api/channels/<channel_name>

Client library

We’re working on the next version actively so we can provide a good developer experience.

Please check the latest next version at https://www.npmjs.com/package/@supabase/realtime-js?activeTab=versions

This library provides an easy way to manage your channels (CRUD operations). Be aware that for channel creation you need to add either use the service_role key or create the RLS policies to allow channel creation:

CREATE POLICY authenticated_all_channels_write
ON realtime.channels FOR INSERT
TO authenticated
WITH CHECK ( true );

The operations are:

new RealtimeClient('').createChannel(name: string)
new RealtimeClient('').deleteChannel(name: string)
new RealtimeClient('').updateChannel(name: string, new_name: string)
new RealtimeClient('').listChannels()

All this requests will also respect the user doing the RLS call, meaning that the listChannels method will only show the allowed channels based on the calling user policies.

Finally this is still heavily WIP as we want to ensure that we provide a good developer experience hence being in next instead of a new release or a RC.

How it works (technically)

Connection context

When you connect with Realtime we set a connection configuration with your JWT, Channel Name and Headers using the following query:

SELECT
	set_config('role', $1, true),
	set_config('realtime.channel_name', $2, true),
	set_config('request.jwt', $4, true),
	set_config('request.jwt.claims', $6, true),
	set_config('request.headers', $7, true)

This query is only run when you connect to a channel.

Applying RLS Policies

To achieve RLS checks on your Realtime connection we created new tables in the realtime schema to which you will be able to write RLS rules against it to control your channel features.

Relevant tables that you can use for your RLS checks

The rules will be applied to three elements:

• channels - determines if the user is able to connect to the channel created
• broadcasts - determines if the user can receive or send broadcast messages
• presences - determines if the user can receive and post presence messages

Which means that your RLS rules should be able to comply with the following rules:

• Channel
  • With a channel set in the context, if user select query returns the channel, they have read permissions
  • With a channel set in the context, if user update query changes the check column, they have write permissions
  • Without a channel set in the context, if user is able to insert into realtime.channels they have write permissions
• Broadcasts - will always require a channel in the context
  • If user select query returns the row associated with the channel in the context, they have read permissions
  • If user update query is able to update check column in row associated with the channel in the context, they have write permissions
• Presence - will always require a channel in the context
  • If user select query returns the row associated with the channel in the context, they have read permissions
  • If user update query is able to update check column in row associated with the channel in the context, they have write permissions

We will explore some examples in the section below named How to use

Do not use it with Postgres Changes

We still do not have this fully implemented for Postgres Changes but be aware that we use the same Channels concept so this changes can impact the Postgres Changes feature.

Avoid using this method whenever you want to use Postgres Changes meaning that you should avoid creating a Channel for Channels that use Postgres Changes.

Call for feedback

Please do try out this feature and provide your feedback, we hope to be able to provide all the answers and we hope you will enjoy this feature.

[psteinroe]

hey @filipecabaco, great work + write up!

I know this is for a future iteration, but please integrate postgres changes with this concept, so that a user can define a "publisher" for a channel. right now, realtime + rls is hammering our database resources and this would finally solve it.

[psteinroe]

@chasers @filipecabaco thanks for the input! excited for this to land. just this week I landed a pr to replace realtime with a custom solution that uses a db trigger with pg_net and socketio. with this, I can at least ditch socketio again until wal can be routed to a channel within realtime. highly appreciate your work on this!

[chasers]

This is on prod right now so play with it and let us know how it feels.

jfyi you can POST to Broadcast like:

curl -X "POST" "https://REF.supabase.co/realtime/v1/api/broadcast" \
     -H 'Authorization: Bearer ANON_OR_SERVICE_OR_AUTHENTICATED_ROLE' \
     -H 'apikey: ANON_OR_SERVICE_ROLE' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "messages": [
    {
      "event": "broadcast",
      "payload": {
        "message_text": "Hi there!",
        "from": "chasers"
      },
      "topic": "messages"
    }
  ]
}'

[chasers]

Also to reiterate: this won't break anything for you UNTIL you create a channel. If you create a channel with the same name as one you're using already it will start checking RLS for it.

[psteinroe]

@chasers looking into migrating back to realtime with rls now. just to be sure: how is the channel policy related to the broadcast policies? the former is just for managing channels themselves right? So in my use case where I want to send a subset of the WAL data as a service role client to the frontend, I need to create a channel for every socket io room, and create a policy for select broadcast to check whether the user can receive messages via the channel?

I compare it with my current socketio-based approach where I use rooms to easily authorise. A room maps to a channel in realtime I guess. Is there any way to auto-create a channel when it does not exist yet? Channels are quite dynamic in my case, and I cannot send the create channel request every time a new message needs to be processed.

[GaryAustin1]

Sort of related on setting up channels...
Do the API calls just add entries to the realtime schema tables, or is there something in the realtime server itself?
The approach I'm looking at it would be best to just create rows in the channel and broadcast table with SQL for the channels.

[GaryAustin1]

Sort of fuzzy (quick read) is this RLS only applied on the channel connection (and maybe token refresh) or is the database call made for every message and RLS has to run on the table(tables for joins) for each message. The latter would open up alot of need for performance testing with RLS policies.

[silentworks]

If this happens only on connect would this mean that if the app owner decides to change a RLS rule while someone already has a websocket connection going they wouldn't be affected by this rule change? I'm thinking of someone writing a rule to prohibit users with a certain role from accessing some broadcasts, but then later on the business requirements change and the user is now given access to that broadcast.

[filipecabaco]

for that we will need to advice users to keep expiration tokens low and at a later stage we need to add that "kill all connections in channel X" functionality so they have a quick way to ensure their rules are applied

[GaryAustin1]

I'm just using changes on a single client. Without the client running I have 1 connection from supabase_admin role.
When I start the client it goes to 14 running the realtime query I've seen it do for polling.

Another user reported this here: https://discord.com/channels/839993398554656828/1228290205690368010 and I am confirming it seems odd mainly as I don't recall seeing this level of connections before, but I could have missed it.

[psteinroe]

I can also confirm that something is wrong with connections - we received a few "max connection limit reached" today which never happened before.

[chasers]

Handled in our contributor Slack but for comms, this is fixed.

Realtime has a pool of connections to your db used for various purposes. You can see which connections Realtime is using with the query:

select usename, application_name from pg_stat_activity where application_name ilike 'realtime_%';

Realtime uses the application_name realtime_connect to check RLS policies as clients connect to a Channel or hit the Broadcast API endpoint.

Now, the default for this is 1 connection (decreased from 5) and it is configurable. With more Channel joins or Broacast POSTs per second you will need more connections available to check RLS policies.

Contact support to increase this config.