Set up an authentication server with the Platform SDK (alpha)


This functionality is in alpha.

Page 2 of 2

See Create an authentication server with the Platform SDK before following the steps on this page.


  • Until you have completed an implementation of your authentication server, your game client can use of the Improbable development authentication services described here. Once you have set up your own authentication server, you can migrate your game client to instead authenticate with your own server.

  • Using your own authentication server and third-party authentication provider is only available to select customers for testing. If you'd like access, raise a support request (for customers with a service agreement) or ask on our forums.

To set up client authentication, follow the steps below.

1. Obtain a service account with the necessary permissions

In order to issue PlayerIdentityTokens and LoginTokens, your authentication/login server must have a service account with read and write access for the {prj, <project_name>, playerauth} path.

Your login server also needs read access for the {prj, <project_name>, dpl, * path to be able to list currently running deployments.

You can create a service account with these permissions using the Platform SDK service account service.

2. Generate a PlayerIdentityToken

Once your authentication server has verified a client's identity, you must call the PlayerAuthService's CreatePlayerIdentityToken method with the player's unique identifier, your SpatialOS cloud project name, and a provider name. This provider can be any string and allows you to identify (for example, on your login server) where a player acquired their PlayerIdentityToken.

The PlayerIdentityToken is a signed token which the game client can use as its identity when making requests to SpatialOS services. By default, this token is valid for 24 hours, after which the client must re-authenticate with your authentication server.

Note: The player's unique identifier is whatever you use to uniquely identify the player, such as their database ID, account ID from a third-party provider, or a GUID that's unique to them.

Using the C# Platform SDK a PlayerIdentityToken can be created like so:

PlayerAuthServiceClient playerAuthServiceClient = PlayerAuthServiceClient.Create(credentials: CredentialWithProvidedToken);
var playerIdentityTokenResponse = playerAuthServiceClient.CreatePlayerIdentityToken(
    new CreatePlayerIdentityTokenRequest
        Provider = "your_provider",
        PlayerIdentifier = "unqiue_player_identifier",
        ProjectName = "your_project_name"

3. Generate a LoginToken

Once the client has received a PlayerIdentityToken from your authentication server and sent it in a request to your login server, they now need to be assigned to a specific deployment.

The first step your login server should do is use the Platform SDK DecodePlayerIdentityToken method to read the contents of the PlayerIdentityToken. The login server should verify the validity of the token using the decoded fields. This includes, as a minimum, ensuring that the provider and project associated with the token match the values set by your authentication server, and that the token has not expired.

At this point, you can implement business logic to, for example, perform matchmaking of players, allow players to select the deployment they want to join, or to host a queue for players to wait in before they can play. This decision can be based on the player identifier and metadata fields present in the PlayerIdentityToken (see the API documentation for PlayerIdentifier and Metadata, under CreatePlayerIdentityTokenRequest > Properties).

For example, you may have a set of deployments running newer builds of your game that should only be accessible to players who have signed up to your beta tester program.

Once your login server has decided on a specific deployment for a client to join, it must call the PlayerAuthService's CreateLoginToken method to create a signed LoginToken. This LoginToken is short-lived (by default, valid for 15 minutes) and proves to SpatialOS services that a given game client (identified by their PlayerIdentityToken) is permitted to join a given deployment.

Using the C# Platform SDK:

PlayerAuthServiceClient playerAuthServiceClient = PlayerAuthServiceClient.Create(credentials: CredentialWithProvidedToken);
var decodePlayerIdentityTokenResponse = playerAuthServiceClient.DecodePlayerIdentityToken(
    new DecodePlayerIdentityTokenRequest
        PlayerIdentityToken = playerIdentityTokenFromGameClient

// Here you should verify that the decoded PlayerIdentityToken's provider and cloud project name match
// the values set by your authentication server and that the token has not expired

var createLoginTokenResponse = playerAuthServiceClient.CreateLoginToken(
    new CreateLoginTokenRequest
        PlayerIdentityToken = playerIdentityTokenFromGameClient,
        DeploymentId = chosenDeploymentId,
        WorkerType = "game_client" // This should match the worker type of the game client

PlayerIdentityToken and LoginToken best practice

  • Use the shortest time possible lifetime for each token, within the constraints of your implementation, by setting the LifetimeDuration property (see the PlayerIdentityToken API docs and LoginToken API docs).
  • After Improbable issues a PlayerIdentityToken or LoginToken, avoid any additional processing and instead pass the token directly to the game client.

4. Connect to the deployment

Once your game client has received both a PlayerIdentityToken and a LoginToken it can connect to the deployment using the Worker SDK. This is done through the Locator.

Set the LocatorParameters (C#/C++)'s PlayerIdentity to a PlayerIdentityCredentials value containing the PlayerIdentityToken and LoginToken obtained from your authentication/login server in the previous steps.

When using your own authentication, any queuing should be implemented by your login server before it issues a LoginToken. Once a client has a LoginToken it will be able to immediately connect to the deployment (assuming that the maximum capacity and join rate of the deployment have not been reached).

Using the Worker SDK in C#:

var locatorParameters = new LocatorParameters {
	PlayerIdentity = new PlayerIdentityCredentials {
		PlayerIdentityToken = playerIdentityTokenResponse.PlayerIdentityToken,
		LoginToken = createLoginTokenResponse.LoginToken
var locator = new Locator(LocatorServerAddress, LocatorServerPort, locatorParameters);
using(var connectionFuture = locator.ConnectAsync(new ConnectionParameters {
	WorkerType = "game_client", // This should match the worker type of your game client
	Network = {
		ConnectionType = NetworkConnectionType.Tcp,
		UseExternalIp = true
})) {
	var connFuture = connectionFuture.Get(Convert.ToUInt32(Defaults.ConnectionTimeoutMillis));
	if (!connFuture.HasValue || !connFuture.Value.IsConnected)
	    throw new Exception("No connection or connection not established");
	Console.WriteLine($"Assigned worker ID: {connFuture.Value.GetWorkerId()}");

Updated about a year ago

Set up an authentication server with the Platform SDK (alpha)

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.