Connection flow

The connection flow (or allocation flow) is the process by which the Allocation service allocates players to a Relay server for a game matchIn the Relay service, a game session is an active match between multiple players connected through a Relay server. One player is the host player to which the other connecting players communicate using the Relay message protocol..

Host player requests an allocation in a region

The Allocations service allows players to request an allocationA logical session on a Relay server that multiple players can connect to if the players are properly authenticated with a join code. to a Relay server for a game session in a specific region and for a maximum number of playersAn integer that indicates the maximum number of connections that the client allows to communicate with them. This is also used to find a Relay with sufficient capacity to host a game session..

For a host playerA player that creates a game match and then generates a join code to share with other players. There is only one host player per game match. to communicate with connecting playersPlayers that receive a join code from the host player and use the join code to join a game match., the host player must request an allocation from the Allocations service with a maximum connection parameter that indicates the maximum number of connecting players that can join the game match. The request must also contain the region of the Relay server. The Allocations service uses the maximum connections parameter and the region to find the most appropriate Relay server.

Allocations service selects a Relay server

After receiving the allocation request, the Allocations service locates the most appropriate Relay server based on the maximum number of connections and the region specified by the allocation request.

When the Allocations service finds a Relay server, it makes a call to allocate or reserve a space on the Relay server for the game session. At this point, the Relay server also generates a unique secret keyA shared secret key is generated by the Relay server and is used by the game client to sign an HMAC that contains the connection data.. The Relay server returns the secret key to the Allocations service, in addition to the Relay server IP, the Relay server ports, and the connection data.

The Allocations service selects a Relay server

Allocations service sends the connection details to the host player

The Allocations service sends the Relay server connection data to the host player's game clientA player that creates a game match and then generates a join code to share with other players. There is only one host player per game match.. When the host game client receives the connection data, it uses it to send a bind message to the Relay server to establish a connection. The bind message contains the connection data, an accept mode of AUTO (other accept modes are reserved for future updates), a nonceA nonce, or cryptographic nonce, is an incrementing number that is used in cryptographic communication to ensure previous messages cannot be resent arbitrarily. Each subsequent message should increment the nonce. This way, if a bad actor tries to use a previous message in a replay attack, the service can reject the message. In the Relay service, you use nonces as part of the HMAC creation process., and an HMACAn HMAC, or hash-based message authentication code, is a type of message authentication code that uses a cryptographic hash function and keys to authenticate messages.. The HMAC contains the player's connection data concatenated with the nonce, signed by the shared secret keyA shared secret key is generated by the Relay server and is used by the game client to sign an HMAC that contains the connection data. from the Allocations service.

This allows the Relay server to verify that the API call originated from the same clientClients, or game clients, are executable programs that players use to play a game. In multiplayer games, clients allow players to connect to other players to participate in a game match. Game clients using the Relay service should facilitate players joining a game session by using a Relay server. that requested the allocation. The allocation request is sent over HTTPS to prevent an attacker from observing the traffic from impersonating the client.

The game client should increment the supplied nonce on each bind message. Relay servers reject any packets that contain a nonce smaller than the previous nonce, which prevents attackers from replaying messages to the Relay server.

When the Relay server verifies the data in the bind request, it sends an acknowledgment message to the requesting host player that contains the connection data.

The Allocations service sends the Relay server connection data to the host player

Host player binds to the Relay server

The hostA player that creates a game match and then generates a join code to share with other players. There is only one host player per game match. uses the information from the response to send a bind message to the Relay that contains the connection data, accept mode, nonce, and HMACAn HMAC, or hash-based message authentication code, is a type of message authentication code that uses a cryptographic hash function and keys to authenticate messages.. If the host doesn’t send the bind message within 10 seconds after making the allocationA logical session on a Relay server that multiple players can connect to if the players are properly authenticated with a join code., the allocation times out because of inactivity.

If the information in the request is accurate, the Relay server sends an acknowledgment “bind received” message to the host player.

The host player is now bound to the Relay server and can request a join codeA simple, randomly generated code that allows connecting players to join a host player's game. from the Allocations service.

Allocations service generates a join code

After receiving the acknowledgment from the Relay server, the host sends a join code request to the Allocations service to generate the join code for the game sessionIn the Relay service, a game session is an active match between multiple players connected through a Relay server. One player is the host player to which the other connecting players communicate using the Relay message protocol.. The Allocations service generates a join code and sends it to the host. When the host player has the join code, they can share it with their friendsPlayers that receive a join code from the host player and use the join code to join a game match. by using any method, including verbally, through a text message, or through a Lobby.

See Relay vs Lobby.

Connecting player uses the join code

When a connecting player has the join code from the host player, they can send a join request with the join code to the Allocations service. The Allocations service sends a message to the player that contains the Relay IP, the ports, the secret key, the connection data, the allocation IDA unique identifier of a player’s allocation on a Relay server., and the host connection data.

Allocations service locates the correct Relay server

For a connecting player to communicate with the host playerA player that creates a game match and then generates a join code to share with other players. There is only one host player per game match., the connecting playerPlayers that receive a join code from the host player and use the join code to join a game match. must send a join request with the join code they received from the host player to the Allocations service.

The Allocations service looks up the host player information from the data store by using the join code and then retrieves the Relay server’s information about the host player. Once it has the details of the Relay server, it sends a message to the connecting player that contains the Relay IP, the Relay ports, the secret key, the connection data, the allocation ID, and the encrypted host connection data, which the player can use to connect to the host.

Connecting player binds to the Relay server

The connecting player uses the connection data to send a bind request to the Relay server.

The connecting player binds to the Relay server

Connecting player connects to the host player

When the connecting player is bound to the Relay server through a bind message, their game clientClients, or game clients, are executable programs that players use to play a game. In multiplayer games, clients allow players to connect to other players to participate in a game match. Game clients using the Relay service should facilitate players joining a game session by using a Relay server. can use the connection data to request a connection to the Relay server.

The Relay server validates the connection data, checks the number of active connections to ensure they don’t exceed the maximum, and then returns the host player's allocation ID to the connecting player.

The connecting player binds to the host player

The connecting player's game client can then use the host player's allocation ID to send messages to the host player through the Relay server.