We're releasing Authorization for Realtime's Broadcast and Presence.
For context, Supabase includes three useful extensions for building real-time applications.
- Broadcast: Send ephemeral, low-latency messages between users.
- Presence: Show when users are online and share state between users.
- Postgres Changes: Listen to Postgres database changes.
This release introduces authorization for Broadcast and Presence using Row Level Security policies:
More of a visual learner? Check out the video!
To facilitate this, Realtime creates and manages a messages
table in your Database's realtime
schema:
You can then write RLS Policies for this table and Realtime will then allow or deny clients' access to your Broadcast and Presence Channels:
-
SELECT
Policies - Allow/Deny receiving messages -
INSERT
Policies - Allow/Deny sending messages
How Realtime works without Authorization
When you want to connect to a Realtime Channel, you can do the following:
import { createClient } from '@supabase/supabase-js'
// Prepare client with authenticated user
const client = createClient('<url>', '<anon_key>')
client.realtime.setAuth(token)
// Prepare the realtime channel
const channel = client.channel('topic')
channel
.subscribe((status: string, err: any) => {
if (status === 'SUBSCRIBED') {
console.log('Connected')
}
})
Without Authorization, any authenticated client can subscribe to any public Channel, to send and receive any messages.
Adding Authorization to Realtime Channels
You can convert this into an authorized Channel (one that verifies RLS policies) in two steps:
- Create RLS Policies
Create RLS Policies
We'll keep it simple with this example. Let's allow authenticated users to:
- Broadcast: send and receive messages (full access)
- Presence: sync, track, and untrack (full access)
create policy "authenticated user listen to all"
on "realtime"."messages"
as permissive
for select -- receive
to authenticated
using ( true );
create policy "authenticated user write to all"
on "realtime"."messages"
as permissive
for insert -- send
to authenticated
with check ( true );
We also have a new database function called realtime.topic()
. You can use this to access the name of the Channel inside your Policies:
create policy "authenticated users can only read from 'locked' topic"
on "realtime"."messages"
as permissive
for select -- read only
to authenticated
using (
realtime.topic() = 'locked' -- access the topic name
);
You can use the extension
column in the messages
table to allow/deny specify the Realtime extension:
create policy "read access to broadcast and presence"
on "realtime"."messages"
as permissive
for select
to authenticated
using (
realtime.messages.extension in ('broadcast', 'presence') -- specify the topic name
);
Reference our Github Discussion for more complex use cases.
- Enabling Authorization on Channels
We've introduced a new configuration parameter private to signal to Realtime servers that you want to check authorization on the channel.
If you try to subscribe with an unauthorized user you will get a new error message informing the user that they do not have permission to access the topic.
// With anon user
supabase.realtime
.channel('locked', { config: { private: true } })
.subscribe((status: string, err: any) => {
if (status === 'SUBSCRIBED') {
console.log('Connected!')
} else {
console.error(err.message)
}
})
// Outputs the following code:
// "You do not have permissions to read from this Topic"
But if you connect with an authorized user you will be able to listen to all messages from the “locked” topic
// With an authenticated user
supabase.realtime.setAuth(token)
supabase.realtime
.channel('locked', { config: { private: true } })
.subscribe((status: string, err: any) => {
if (status === 'SUBSCRIBED') {
console.log('Connected!')
} else {
console.error(err.message)
}
})
// Outputs the following code:
// "Connected!"
Advanced examples
You can find a more complex example in the Next.js Authorization Demo where we are using this feature to build chat rooms with restricted access or you could check the Flutter Figma Clone to see how you can secure realtime communication between users.
How does it work?
We decided on an approach that keeps your database and RLS policies at the heart of this new authorization strategy.
Database as a source of security
To achieve Realtime authorization, we looked into our current solutions, namely how Storage handles Access Control. Due to the nature of Realtime, our primitives are different as we have no assets stored in the database. So how did we achieve it?
On Channel subscription you are able to inform Realtime to use a private Channel and we will do the required checks.
The checks are done by running SELECT and INSERT queries on the new realtime.messages
table which are then rolled backed so nothing is persisted. Then, based on the query result, we can determine the policies the user has for a given extension.
As a result, in the server, we create a map of policies per connected socket so we can keep them in memory associated with the user's connection.
%Policies{
broadcast: %BroadcastPolicies{read: false, write: false},
presence: %PresencePolicies{read: false, write: false}
}
One user, one context, one connection
Now that we have set up everything on the database side, let's understand how it works and how we can verify authorization via RLS policies.
Realtime uses the private flag client's define when creating channel, takes the headers used to upgrade to the WebSocket connection, claims from your verified JSON Web Token (JWT), loads them into a Postgres transaction using set_config
, verifies them by querying the realtime.messages
table, and stores the output as a group of policies within the context of the user's channel on the server.
How is this approach performant?
Realtime checks RLS policies against your database on Channel subscription, so expect a small latency increase initially, but will be cached on the server so all messages will pass from client to server to clients with minimal latency.
Latency between geographically close users is very important for a product like Realtime. To deliver messages as fast as possible between users on our global network, we cache the policies.
We can maintain high throughput and low latency on a Realtime Channel with Broadcast and Presence authorization because:
- the policy is only generated when a user connects to a Channel
- the policy cached in memory is close to your users
- the policy is cached for the duration of the connection, until the JWT expires, or when the user sends a new refresh token
If a user does not have access to a given Channel they won't be able to connect at all and their connections will be rejected.
Refreshing your Policies
Realtime will check RLS policies against your database whenever the user connects or there's a new refresh token to make sure that it continues to be authorized despite any changes to its claims. Be aware of your token expiration time to ensure users policies are checked regularly.
Postgres Changes Support
This method for Realtime Authorization currently only supports Broadcast and Presence. Postgres Changes already adheres to RLS policies on the tables you're listening to so you can continue using that authorization scheme for getting changes from your database.
Availability
Broadcast and Presence Authorization is available in Public Beta. We are looking for feedback so please do share it in the GitHub discussion.
Future Work
We're excited to make Realtime more secure, performant, and stable.
We'll take your feedback, expand this approach, and continue to improve the developer experience as you implement Realtime Authorization for your use cases.
Top comments (0)