Projects

A project is typically analogous to an individual game title, and defines both the queues available to that game, and how those game clients can authenticate themselves when connecting to the client API.

The simplest example of a Project configuration is below, which defines a project named speedy-racer-1999 that requires no authentication details from clients:

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

A more secure project that requires clients to provide a signed JWT when they connect, would be as follows:

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

See the Client Authentication guide for more details on client authentication methods and configuration.

Match Token JWK

When a match is found, clients will receive an Assignment Token containing information about the match, which they should provide to the server when they connect. This token will be a signed JWT, and the game server must verify the JWT is valid before acting on the data within it.

The JWT will have been signed using a JSON Web Key (JWK) defined in your project, for example:

{
  "name": "projects/speedy-racer-1999",
  "id": "speedy-racer-1999",
  "title": "Racing Game",
  "active": true,
  "clientTokenAuth": {
    "jwsHs256": {
      "issuer": "example.org",
      "signingKey": "c3VwZXJzZWNyZXQK"
    }
  },
  "match_token_jwk": {
    "kty": "EC",
    "d": "G0-Fr-lbywzpUDZl8-73Ukya05JpBTjEhwN1HxnezZc",
    "use": "sig",
    "crv": "P-256",
    "kid": "donotuse",
    "x": "xHuXQZrRZsisinglN97qwo_Sy2if4At5uFOfHbwQjhg",
    "y": "92pP5p8MlDIpExXwKGBU9hmP0vKSh71ahNttNP8mnPw",
    "alg": "ES256"
  },
  "queues": []
}

The IMS Matchmaker supports both RSA and EC (Elliptical Curve) JWKs for the purpose of signing assignment tokens.

Generating a JWK

You can generate your own JWK using a service such as mkjwk.org. We recommend using the EC (Elliptical Curve) type, with a P-256 curve and ES256 algorithm. The key use must be set to Signature. (The Key ID value can be set to anything, for example a timestamp.)

This service will generate a public and private keypair and show you the resulting JWKs.

Your project should be configured with the "Public and Private Keypair" per the example above, as the private key is required by the Matchmaker to sign the JWT before providing it to the client.

Note: Take care to never share the combined "Public and Private Keypair" with clients or users, as this could be exploited to create illegitimate matches.

You should embed the "Public Key" value into your game server code, and use this to verify the JWT provided to it by game clients. See the assignment token documentation for further information on parsing it within your server code.