Skip to main content

Authentication

The IMS Matchmaker supports several authentication methods by which a connecting client can identify themselves.

JWT​

JWT-based authentication is the most flexible of authentication mechanisms, whereby the client must only provide JWT that has been signed with a key known only to you and the Matchmaker.

To configure this authentication mechanism, specify a clientTokenAuth.jwsHs256 block within your Project configuration. It should declare an issuer name (which matches the JWT's iss value), and a signing key (which will be used by your game to sign the JWT, and by the matchmaker to verify it):

{
  "name": "projects/speedy-racer-1999",
  "id": "speedy-racer-1999",
  "title": "Racing Game",
  "active": true,
  "clientTokenAuth": {
    "jwsHs256": {
      "issuer": "mygamestudio.com",
      "signingKey": "superSecretSigningKey"
    }
  },
  "queues": []
}

Typically, the JWT will be generated by a backend server that you trust, to ensure that the signing key is not revealed to clients.

At a minimum, the JWT payload must contain:

  • iss - (issuer) value that matches the issuer key in the Platform configuration
  • exp - (expiration time) value that is a few minutes in the future (such that the client has enough time to use it, but can't use it forever)
{
  "iss": "mygamestudio.com",
  "exp": 1641092645
}

Your game client should ask your backend server to generate the JWT using the HS256 algorithm and return it to the client, such that the client can then provide it to the Matchmaker in the connection handshake:

GET /v1/lobby HTTP/1.1
Host: prd.matchmaker.os.i8e.io
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: json
Sec-WebSocket-Version: 13
Imp-Project: speedy-racer-1999
Authorization: Bearer secret-token:jwt/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJteWdhbWVzdHVkaW8uY29tIiwiZXhwIjoxNjQxMDkyNjQ1fQ.w280Z-ansmPIj_POfQyGX-xjTAj1vUyxoZs9DFYL1s8

If authentication is successful, the client will receive a ClientStatusResponse message after connecting. Otherwise, they will be disconnected.

PlayFab​

If your game client uses PlayFab for authentication, you can use the client's session token with the IMS Matchmaker as a means of authorization. Doing so also unlocks the ability for the Matchmaker to pull data from user data objects, which can then be used as a basis for skill-based matchmaking.

To configure this authentication mechanism, specify a playFabAuth block within your Project configuration, it must declare:

  • titleId - value (the PlayFab ID assigned to your title - typically a 5-character alphanumeric value such as A12B3),
  • secretKey - unique secret key that the Matchmaker will use to authenticate itself with PlayFab (this can be created under Title Settings → Secret Keys within the PlayFab Developer site):
{
  "name": "projects/speedy-racer-1999",
  "id": "speedy-racer-1999",
  "title": "Racing Game",
  "active": true,
  "playFabAuth": {
    "secretKey": "7MLKB63A0F0C51SLC5QZ62MQZJEP65AA5WI5Q740KLL2ETR6GO",
    "titleId": "1A2B3"
  },
  "queues": []
}

Your game client should provide its PlayFab session token within the Authorization header of the WebSocket connection request, prefixed with Bearer secret-token:playfab/. For example, if the session token was ABC123DEF456, the client would issue this connection request:

GET /v1/lobby HTTP/1.1
Host: prd.matchmaker.os.i8e.io
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: json
Sec-WebSocket-Version: 13
Imp-Project: speedy-racer-1999
Authorization: Bearer secret-token:playfab/ABC123DEF456

If authentication is successful, the client will receive a ClientStatusResponse message. Otherwise, they will be disconnected.

AccelByte​

If your game client uses AccelByte for authentication, you can use the client's authentication token with the IMS Matchmaker as a means of authorization. Doing so also unlocks the ability for the Matchmaker to pull data from CloudSave data, which can then be used as a basis for skill-based matchmaking.

You must first create a public or private OAuth client within AccelByte, which will provide you with a client ID that can be used to configure your project. (If you plan to use AccelByte CloudSave data, this client must also specify the CloudSave permission, e.g. ADMIN:NAMESPACE:<your-namespace>:USER:*:CLOUDSAVE:RECORD.)

To configure your project to this authentication mechanism, declare an accelByteAuth block within your Project configuration. It must contain the following properties:

  • baseUrl - the AccelByte API URL for your project, e.g. https://sub.mystudio.accelbyte.io/
  • iamBaseUrl - the AccelByte IAM API URL for your project, often the same as baseUrl, e.g. https://sub.mystudio.accelbyte.io/
  • iamClientId - the ID of the client created above, typically a 32-character hexadecimal string, e.g. 2103cbc82b2459bcac6fa307432bf06e.
  • iamClientSecret - the Secret of the client created above (only required if using a private OAuth client.)

For example:

{
  "name": "projects/speedy-racer-1999",
  "id": "speedy-racer-1999",
  "title": "Racing Game",
  "active": true,
  "accelByteAuth": {
    "baseUrl": "https://sub.mystudio.accelbyte.io/",
    "iamBaseUrl": "https://sub.mystudio.accelbyte.io/",
    "iamClientId": "2103cbc82b2459bcac6fa307432bf06e",
    "iamClientSecret": "b1Rjh1dmkQOXXeom"
  },
  "queues": []
}

Your game client should provide its AccelByte authorization token within the Authorization header of the WebSocket connection request, prefixed with Bearer secret-token:accelbyte/. For example, if the access token was eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfaWQiOiIyMTAzY2JjODJiMjQ1OWJjYWM2ZmEzMDc0MzJiZjA2ZSJ9.TSuoJo1RrSM3n17JVaV75cuEtPIYC7DZPVissbNBabU, the client would issue this connection request:

GET /v1/lobby HTTP/1.1
Host: prd.matchmaker.os.i8e.io
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Protocol: json
Sec-WebSocket-Version: 13
Imp-Project: speedy-racer-1999
Authorization: Bearer secret-token:accelbyte/eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfaWQiOiIyMTAzY2JjODJiMjQ1OWJjYWM2ZmEzMDc0MzJiZjA2ZSJ9.TSuoJo1RrSM3n17JVaV75cuEtPIYC7DZPVissbNBabU

If authentication is successful, the client will receive a ClientStatusResponse message. Otherwise, they will be disconnected.

None (anonymous)​

IMS Matchmaker also supports an anonymous access method whereby no client authentication is required. This is only advised in limited circumstances, for example in early testing and development phases.

To configure this authentication mechanism, specify an empty (non-null) noAuth block within your Project configuration:

{
  "name": "projects/speedy-racer-1999",
  "id": "speedy-racer-1999",
  "title": "Racing Game",
  "active": true,
  "noAuth": {},
  "queues": []
}

With this authentication mechanism, the client does not need to provide an Authentication HTTP header and will receive a ClientStatusResponse message immediately after connecting.