How to Add Authentication

Room Service uses short-lived session tokens. If you want allow a user to do something in Room Service, you need to create a new token for them. Tokens last for 6 hours and each token is associated with permissions that the user is allowed to do during that session.

Diagram showing your Backend asks Room Service to create a token for a user.

In order for the browser clients to open a connection to Room Service, you'll need to give it this token.

Diagram showing your backend giving your browser the token

The most common way to do this is to create an "Auth Webhook" that the browser client can call whenever it tries to connect to a room. That's just a POST endpoint on your server that provisions a new token for a user and returns it back to the browser. Let's walk through an example of how this is done.

An Auth Webhook

This example uses Node.js on the server, but this is possible in any language.

When you connect to a room, Room Service will check if that's ok.

If the check isn't successful (the user isn't authorized), this line will throw an error. If that check is successful, the user will have full read-write access to the room.

Need more granular auth? We're working on this and would love to hear from you!

You give Room Service a function to call to make the check.

In the simplest case, this function creates a POST request to an endpoint you setup on your backend. This endpoint can have any structure you'd like, so if you need a custom body or custom headers, that's fine. It's your endpoint.

The request should send the name of the room.

This is how your server will recognize what room this user is trying to access. In this example, params.room will be "express-minimal".

If there's an issue, throw an error.

You can then wrap your service.room with a try/catch to catch anything that goes wrong.

On the server, capture the POST request

Setup an endpoint that accepts the request we just sent from the browser. This example is in Node.js with Express, but you can do this in any language.

If unauthorized, send back a 401.

Use whatever system you have currently to determine if a user is logged in and allowed to access this particular room. In this example, we're showing a prototype for cookie auth, but you're free to implement this however you'd like.

To create a token, send a POST request to the `/provision` API route.

This route allows a user to access particular resources. In the simplest case, we'll just allow this user to access a single room.

This is your user ID.

Whatever you pass in here, we'll send back to you on the client to distinguish users by.

You can send the body of the provisioner back to your client

The provisioner will return a body that looks like this:

{
  // The user id you gave us
  "user": "your-user-id",

  // The resources you generated, with Room Service specific
  // information attached.
  "resources": [{...}],

  // The token associated with this session
  "token": "tok_123"
}

Return the result of the result of your request from your auth function

Your endpoint needs to send back a user id, a resources object (which we'll get to in a moment), and the token to the browser client.

See on Github

Room Service