Authentication¶
To authenticate clients, you can bring your own token validation logic by implementing the onAuth()
method in your room.
Authentication module
The new Authentication module provides a set of tools to help you authenticate your players into your application. (Currently in beta, feedback is welcome on colyseus/colyseus#657)
Room authentication¶
To authenticate clients into a room, you must implement the static onAuth()
method in your room. This method is called before onCreate()
or onJoin()
, and it is responsible for validating the client's authentication token.
Client-side¶
The authentication token set on client.auth.token
will be sent as Authorization
header in all http requests to the server, including matchmaking requests.
// set the auth token
client.auth.token = "YOUR AUTH TOKEN";
// matchmaking requests will contain the auth token
client.joinOrCreate("my_room").then((room) => {
console.log(room);
});
// http requests will contain the auth token
client.http.get("/profile").then((response) => {
console.log(response.data);
});
Server-side¶
onAuth (client, options, request)
- Soon to be deprecated¶
onAuth
as instance method will be deprecated
Since version 0.15.14
, it is preferred to use the static version onAuth()
method. You can still the onAuth
as instance method, but it will be deprecated in the future. See the reasoning behind this change on colyseus/colyseus#657
The onAuth()
method will be executed before onJoin()
. It can be used to verify authenticity of a client joining the 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.
Getting player's IP address
You can use the request
variable to retrieve the user's IP address, http headers, and more. E.g.: request.headers['x-forwarded-for'] || request.socket.remoteAddress
Implementations examples
import { Room, ServerError } from "colyseus";
class MyRoom extends Room {
async onAuth (client, options, request) {
/**
* Alternatively, you can use `async` / `await`,
* which will return a `Promise` under the hood.
*/
const userData = await validateToken(options.accessToken);
if (userData) {
return userData;
} else {
throw new ServerError(400, "bad access token");
}
}
}
import { Room } from "colyseus";
class MyRoom extends Room {
onAuth (client, options, request): Promise<any> {
/**
* You can return a `Promise`, and perform some asynchronous task to validate the client.
*/
return new Promise((resolve, reject) => {
validateToken(options.accessToken, (err, userData) => {
if (!err) {
resolve(userData);
} else {
reject(new ServerError(400, "bad access token"));
}
});
});
}
}
Client-side examples
From the client-side, you may call the matchmaking method (join
, joinOrCreate
, etc) with a token from some authentication service of your choice (i. e. Facebook):