0.15.15

[endel]

Introducing Authentication Module

Documentation | Live demo | Demo Source Code

Server-side: onAuth() changes

• static onAuth(token, req) method should be implemented as static from now on
• onAuth(client, options, req) as an instance method still works, but will be deprecated in the future.

This change allows validating the token earlier in the connection process, without needing an instance of the room available.

This way the auth token is read from the first matchmaking request header instead of as query param in the second WebSocket connection.

Server-side: The @colyseus/auth module

• Uses JWT to secure communication with client SDK
• Provides authentication via express routes:
  • /auth/register - user registration (email + password)
  • /auth/login - login (email + password)
  • /auth/anonymous - anonymous login
  • /auth/userdata - fetch user data
• Provides OAuth express routes (Thanks to @simov's work on grant module - a MIT-licensed "OAuth Proxy")
  • /auth/provider/:providerId - redirect to provider
  • /auth/provider/:providerId/callback - reply callback from the provider

Database interaction must be implemented by end-user

End-user should implement the following callbacks:

• auth.settings.onFindUserByEmail = async (email) => {/* query user by email */}
• auth.settings.onRegisterWithEmailAndPassword = async (email, password, options) => {/* insert user */}
• auth.settings.onRegisterAnonymously = async (options: T) => {/* insert anonymous user */}
• auth.oauth.onCallback(async (data, provider) => {/* query or insert user by OAuth provider */})

End-user may customize the following callbacks. (They come with a default implementation.)

• auth.settings.onParseToken = (jwt: JwtPayload) => jwt
• auth.settings.onGenerateToken = async (userdata: unknown) => await JWT.sign(userdata)
• auth.settings.onHashPassword = async (password: string) => Hash.make(password)

Server-side Usage

import { auth } from "@colyseus/auth";

auth.settings.onFindUserByEmail = async (email) => {
  //
  // Your database query to find user by email address
  //
}

auth.settings.onRegisterWithEmailAndPassword = async (email, password, options) => {
  // 
  // Your database query to insert the user with email + password
  // (The "password" is already hashed here)
  //
}

// Configure Discord as OAuth provider
auth.oauth.addProvider('discord', {
  key: "YOUR_DISCORD_KEY",
  secret: "YOUR_DISCORD_SECRET",
  scope: ['identify', 'email'],
});

auth.oauth.onCallback(async (data, provider) => {
  //
  // Your database query/insert. This callback must return the userdata.
  //   data.raw -> { token_type, access_token, expires_in, refresh_token, scope }
  //   data.profile -> { id, username, avatar, discriminator, public_flags, premium_type, flags, banner, accent_color, global_name, avatar_decoration_data, banner_color, mfa_enabled, locale, email }
  //
});

//
// app.config.ts: bind auth express routes
//

initializeExpress: (app) => {
  // bind auth + oauth express routes
  app.use(auth.prefix, auth.routes());

  // custom protected request
  app.get("/profile", auth.middleware(), (req: Request, res) => {
    res.json(req.auth);
  });
},

---

Client-side: client.auth API:

• client.auth.registerWithEmailAndPassword(email, password, options?)
• client.auth.signInWithEmailAndPassword(email, password)
• client.auth.signInAnonymously(options?)
• client.auth.signInWithProvider(providerName) - open popup for OAuth provider
• client.auth.sendPasswordResetEmail(email)
• client.auth.getUserData() - requests /auth/userdata from the server
• client.auth.onChange(callback) - define a callback that is triggered when internal auth state changes (it only triggers as a response from client.auth method calls, there's no realtime subscription here!)
• client.auth.signOut() - clear local auth token
• client.auth.token - auth token getter and setter

Client-side: client.http API:

If client.auth.token is set, requests from client.http will forward it as "Authentication: Bearer {token}" header. The match-making requests are now using client.http as well.

• client.http.get(path, options)
• client.http.post(path, options)
• client.http.del(path, options)
• client.http.put(path, options)

---

Playground update (@colyseus/playground)

The playground tool has been updated to allow customizing the client's "Auth Token".

(PRs introducing the authentication module #657, colyseus/colyseus.js#133, colyseus/docs#150)

---

Smaller fixes

A big thanks to @afrokick for fixing all these below 👏

• simulateLatency doesn't go back (Issue: simulateLatency doesn't go back  #570, PR: Fix simulateLatency #663)
• BunWebSockets transport not setting CORS headers on matchmaking requests (Issue: [Bug]: BunWebSockets transport not setting CORS headers on matchmaking requests #662, PR: BunWebSockets - set headers for get and posts requests #664)
• Wrong type on RelayRoom (Issue: [Bug]: RelayRoom.ts public name:boolean #665, PR: fix type definition for Player.name in RelayRoom #667)
• Changing room to private doesn't update realtime listing (Issue: [Bug]: Changing room to private doesn't update realtime listing #617, PR: [LobbyRoom] Update listed rooms on the client after rooms are marked as private #668)

---

This discussion was created from the release 0.15.15.