Assignment Tokens

When a client is assigned to a match, it will be provided with a signed JWT containing additional information about the match, such as the chosen map or the team the player has been assigned to. The game client must provide this to the game server.

The encoded and signed token typically looks something like this:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3NpZ24iOnsiY29ubmVjdGlvbiI6IjIwMy40LjExMy40OjI5MDAwIiwiZXh0ZW5zaW9ucyI6eyJ0ZWFtIjp7InRpY2tldFRvVGVhbUluZGV4Ijp7InQxMjM0NTYwMDBhIjowLCJ0MTIzNDU2MDAwYiI6MCwidDEyMzQ1NjAwMGMiOjEsInQxMjM0NTYwMDBkIjoyfX19fSwiYXVkIjoiMjAzLjQuMTEzLjQ6MjkwMCIsImV4cCI6MTYzNDMwMjgwMCwiaWF0IjoxNTk1Nzk0OTIwLCJzdWIiOiJ0MTIzNDU2MDBjIn0.mXXPAa2-2YD9Kqx3ufaa0crrw6klLeOlG1ntzmUBVWIGA3tGlWn6fuKtEobw-XjIOnI3f21pChlWui3CON61bw

(Try pasting the above string into the decoder at JWT.io.)

The content follows this structure:

{
  "assign": {
    "connection": "203.4.113.4:29000",
    "extensions": {
      "team": {
        "ticketToTeamIndex": {
          "t123456000a": 0,
          "t123456000b": 0,
          "t123456000c": 1,
          "t123456000d": 2
        }
      }
    }
  },
  "aud": "203.4.113.4:2900",
  "exp": 1634302800,
  "iat": 1595794920,
  "sub": "t12345600c"
}

Before acting on any of the data contained by the token, the game server must verify it.

Verification

When the game server receives an assignment token from the game client, it should first verify the token is valid. The token will have been signed using the match token JWK defined by the project. A variety of libraries for every programming language are available to do this task - we recommend consulting the list maintained by JWT.io, or ask a friendly IMS Matchmaker engineer for recommendations for your project.

Specifically, the game server should check that the JWT provided by the client is correctly signed by comparing it to the public key part of the JWK. It should also verify that the JWK was received earlier than the given expiry time (exp) and that it matches the server name (aud). If any check fails, the game server should disconnect the client.

If the game server is happy with the JWK provided by the client, it should configure itself for the match described by the token and await the remaining players.

Each game client will receive a slightly different assignment token - notably, the subject (sub) value will differ. The game server should verify that each connecting client has a different sub value, and that this value is assigned a team within the ticketToTeamIndex part of the assignment token.

Team Assignments

If team assignments have been made, the extensions object will contain a team object, within which the ticketToTeamIndex map describes which subject (sub) has been assigned to which team. The server should use this data to assign clients to the appropriate team.

For example, if 6 players queue up for a 3v3 game and are assigned ticket IDs ticket-1, ticket-2... ticket-6 (available in the ClientStatusResponse message and the sub part of the assignment token), the resulting team assignment map provided to the server would resemble a map akin to the following table, splitting the tickets into two teams:

"ticketToTeamIndex": {
  "ticket-1": 0,
  "ticket-2": 0,
  "ticket-3": 1,
  "ticket-4": 0,
  "ticket-5": 1,
  "ticket-6": 1
}

Here, tickets ticket-1, ticket-2 and ticket-4 have been assigned to team 0, whereas ticket-3, ticket-5 and ticket-6 have been assigned to team 1.

Note that while team indices start at 0, the first entry in the ticketToTeamIndex map is not guaranteed to be for team 0.