Get SpatialOS

Sites

Menu
These are the docs for 13.5, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 13.7 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 spatial CLI and the Platform SDK. For example, using the CLI:

spatial project auth dev-auth-token create --description="A development auth token for Friday's playtest"

This returns a token valid for the default time of 30 days. When you no longer need the token, you can invalidate it using:

spatial project auth dev-auth-token expire <dev-auth-token-id>

Any game clients distributed with that token will no longer be able to connect to any deployments.

Development authentication flow

  1. You use the spatial 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 DevelopmentAuthenticationToken.
  3. When your game client starts, it must use the Worker SDK CreateDevelopmentPlayerIdentityTokenAsync method to exchange its hard-coded DevelopmentAuthenticationToken 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,
        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.
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)
Notes
  • Epired 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 --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