AuthenticationRoom Authentication

Room Authentication

You can authenticate your users using the onAuth method in your room. This method is called before onJoin, and it is responsible for validating the client’s request to join a room.

  • If onAuth() returns a truthy value, onJoin() is going to be called with the returned value as the third argument.
  • If onAuth() returns a falsy value, the client is immediatelly rejected, causing the matchmaking function call from the client-side to fail.
  • You may also throw a ServerError to expose a custom error to be handled in the client-side.

If left non-implemented, it always returns true - allowing any client to connect.

Server-side: onAuth method

The static onAuth is recommended because it does not require the room instance to be created before authenticating the client.

If you need to access the room instance during the authentication process, you can use the instance onAuth method instance.

src/rooms/MyRoom.ts
import { Room } from "colyseus";
import { JWT } from "@colyseus/auth";
 
class MyRoom extends Room {
    static async onAuth (token, options, context) {
        // validate the token
        const userdata = await JWT.verify(token);
 
        // return userdata
        return userdata;
    }
}

Server-side: onJoin method

Get the user data during the onJoin method via the client.auth property.

src/rooms/MyRoom.ts
import { Room } from "colyseus";
// ...
class MyRoom extends Room {
    // ...
    async onJoin (client, options) {
        client.auth // contains the userdata
    }
}

Client-side: Setting the auth token

The client.auth.token property is used to set the authentication token. This token will be sent as an Authorization header in all HTTP requests to the server.

client.js
// set the auth token
client.auth.token = "YOUR AUTH TOKEN";

If you are using the @colyseus/auth module, this token is managed automatically. See Authentication → Module.

Client-side: Requesting to join a Room

Match-making requests will contain the auth token.

client.js
client.joinOrCreate("my_room").then((room) => {
    console.log(room);
});

onAuth Context

The third argument of the onAuth method is the context object. Both static onAuth and onAuth methods receive the same context object as the third argument.

The context object has the following properties:

  • context.token - the authentication token sent by the client.
  • context.headers - the headers sent by the client.
  • context.ip - the IP address of the client.

Accessing the Auth Token

The authentication token is available in the context.token property.

src/rooms/MyRoom.ts
// ...
async onAuth(client, options, context) {
    console.log(context.token);
}
// ...

Accessing the request headers

The request headers are available in the context.headers property.

src/rooms/MyRoom.ts
// ...
async onAuth(client, options, context) {
    console.log(context.headers);
}
// ...

Accessing the client IP address

The client IP address is available in the context.ip property.

src/rooms/MyRoom.ts
// ...
async onAuth(client, options, context) {
    console.log(context.ip);
}
// ...

It contains the value of the X-Real-IP header, if available. If not, it falls back to the X-Forwarded-For header, and finally to the request object’s remoteAddress property.

Last updated on
AuthenticationHTTP Middleware