Sites

Menu
These are the docs for 13.6, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.0 is the newest →

Using the development authentication flow (alpha)

While developing your game you may want your game clients to use the proper authentication flow without already having developed your own authentication and login servers (following the process described here). To facilitate this, Improbable hosts both a development authentication service and a development login service for use in early-stage game development.

The development authentication flow looks very similar to the flow outlined here, with a number of small changes:

  • Rather than talking to your own authentication/login servers, game clients use the Worker SDK to talk directly to the DevelopmentAuthenticationService and DevelopmentLoginService.
  • Rather than use any kind of authentication specific to your game, clients use a long-lived DevelopmentAuthenticationToken that can be hardcoded into the game client.

You can create and manage these DevelopmentAuthenticationTokens using both the SpatialOS CLI and the Platform SDK.

Development authentication flow

  1. You use the SpatialOS CLI or Platform SDK PlayerAuthService to create a DevelopmentAuthenticationToken. The token can be valid for up to 90 days and can be used by clients to create PlayerIdentityTokens for your project.
  2. You build a version of your game client containing a hard-coded TokenSecret of a DevelopmentAuthenticationToken.
  3. When your game client starts, it must use the Worker SDK CreateDevelopmentPlayerIdentityTokenAsync method to exchange its hard-coded TokenSecret for a PlayerIdentityToken.

    PlayerIdentityTokens obtained through the development authentication flow have the provider improbable_devauth to indicate they are development PlayerIdentityTokens and should not be trusted in a production game.

  4. Once the game client has a PlayerIdentityToken, it uses the Worker SDK CreateDevelopmentLoginTokensAsync method to acquire a list of deployments and their associated LoginTokens.

    To prevent users from logging into any deployment, only deployments with the dev_login tag are returned in the development authentication flow.

  5. The game client then uses its PlayerIdentityToken and its chosen deployment’s LoginToken to connect to the chosen deployment using the method described here.

Using the development authentication flow

Exchanging a DevelopmentAuthenticationToken for a PlayerIdentityToken

Using the Worker SDK, a game client can exchange a valid DevelopmentAuthenticationToken for a PlayerIdentityToken using the CreateDevelopmentPlayerIdentityTokenAsync method. The returned token will have a special provider improbable_devauth to distinguish it from authenticated tokens created using the regular authentication flow.

Fields such as player identifier and display name can be chosen by the game client. These values are not validated by the development authentication service and therefore should not be trusted outside of game testing. If you would like validation of the identity of the clients, you should follow the instructions here here to create your own authentication server.

You can use the C# Worker SDK to create a PlayerIdentityToken with a PlayerIdentityTokenRequest like so:

var pitFuture = DevelopmentAuthentication.CreateDevelopmentPlayerIdentityTokenAsync("locator.improbable.io", 444,
    new PlayerIdentityTokenRequest
    {
        DevelopmentAuthenticationTokenId = DAT_TokenSecret,
        PlayerId = "id_for_this_client",
        DisplayName = "Client display name",
        Metadata = "{'data': '1', 'example': 'true'}"
    });
PlayerIdentityTokenResponse pitResp = pitFuture.Get();

Your production login server should always decode a player’s PIT using the Platform SDK and check that the Provider field matches the value set by your authentication server. This stops players from being able to use development tokens as identity in your production deployments.

Creating development LoginTokens

Using the Worker SDK, a game client can exchange a PlayerIdentityToken for a list of LoginTokens for deployments in that SpatialOS project. The returned list contains up to 10 running deployments with the dev_login tag and a LoginToken for each.

You can use the C# Worker SDK to create a list of LoginTokens with a LoginTokensRequest like so:

var ltFuture = DevelopmentAuthentication.CreateDevelopmentLoginTokensAsync("locator.improbable.io", 444,
    new LoginTokensRequest
    {
        PlayerIdentityToken = pitResp.PlayerIdentityToken,
        WorkerType = WorkerType
    });
LoginTokensResponse ltResp = ltFuture.Get();

Your game client can now pick one of the deployments in the response and connect using its PlayerIdentityToken and the corresponding LoginToken.

The list of deployments and login tokens returned by the CreateDevelopmentLoginTokens method is capped at a maximum of 10 entries. If you have more than 10 running deployments with the dev_login tag then we do not guarantee which will be returned.

DevelopmentAuthenticationToken maintenance

Create a DevelopmentAuthenticationToken

spatial project auth dev-auth-token create --description="my description" --lifetime="24h10m20s"
Parameters
  • description (mandatory): Must not be empty or exceed 200 characters.
  • lifetime (optional, default is 30 days): Must not exceed 90 days.

This returns a DevelopmentAuthenticationToken and TokenSecret. Make a note of the TokenSecret as there is no way to retrieve it afterwards; if you lose it, you will have to create a new DevelopmentAuthenticationToken.

The TokenSecret allows access to your deployments, so you should treat it as securely as a password. Do not store it in a database or check it into version control in cleartext, and be mindful about who has access to it and to the code, repository and binaries. We also recommend you explicitly set the expiry time to the shortest duration possible for your requirements.

Notes
  • You can extend the lifetime of a DevelopmentAuthenticationToken using the update command.

Expire a DevelopmentAuthenticationToken

spatial project auth dev-auth-token expire --id="my DevelopmentAuthenticationToken id as returned by the create command"
Parameters
  • id (mandatory)

Make sure you expire DevelopmentAuthenticationTokens as soon as you no longer need them, and regularly check if you have any unused ones that you can expire.

Notes
  • Expired DevelopmentAuthenticationTokens persist for one more week after expiry, and are then permanently deleted. You can make an expired DevelopmentAuthenticationToken valid again during that week using the update command.

Get a DevelopmentAuthenticationToken

spatial project auth dev-auth-token get --id="my DevelopmentAuthenticationToken id as returned by the create command"
Parameters
  • id (mandatory)

List your DevelopmentAuthenticationTokens

spatial project auth dev-auth-token list --include_expired="false" --limit="20"
Parameters
  • include_expired (optional, default is false)
  • limit (optional, default is 20): Maximum number of DevelopmentAuthenticationTokens to list. Must not exceed 50. If there are more DevelopmentAuthenticationTokens than limit, a random subset of existing DevelopmentAuthenticationTokens is returned.

Update a DevelopmentAuthenticationToken

spatial project auth dev-auth-token update --id="my DevelopmentAuthenticationToken id" --updated_description="my new description" --updated_lifetime="24h10m20s"
Parameters
  • id (mandatory)
  • updated_description (optional): Must not exceed 200 characters.
  • updated_lifetime (optional): Must not exceed 90 days. The lifetime of your DevelopmentAuthenticationToken will now expire updated_lifetime in the future starting from the moment this command was invoked.
Notes
  • You can repeatedly extend the lifetime of a DevelopmentAuthenticationToken to prevent it from expiring.
  • Expired DevelopmentAuthenticationTokens persist for one more week after expiry and are then permanently deleted. You can use this command to make an expired DevelopmentAuthenticationToken valid again during that week.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums