Development authentication flow

The following instructions cover Windows and macOS operating systems unless otherwise stated.

Use the development authentication flow when you do not have your own authentication service, and have no access to the Launcher, such as when you are working with:

  • Mobile connection to cloud deployments
  • PIE / Launch on Device in the Unreal Editor

This workflow is intended for development only. You need to replace it with your own authentication service for production.

The GDK gives you the following options for using the development authentication flow: PIE / Launch on Device and ClientTravel:

PIE / Launch on Device

To connect a client-worker instance to a cloud deployment, you need to enable the development authentication flow inside the Unreal Editor.

Prerequisites

Ensure that there is no local deployment running.

Image: If you can see the Start Deployment button in the GDK toolbar, there is no local deployment running.

Workflow

  1. In the Unreal Editor, from the GDK toolbar, select the dropdown next to the Start a deployment button and ensure that Connect to cloud deployment is selected.

  2. In the Cloud Deployment Name field, enter the name of the cloud deployment you want to connect to.

If you don’t specify which deployment to connect to, the client-worker instance connects to a random running deployment that has the dev_login tag in your SpatialOS project.

  1. Select Play to start the game in PIE, or select Launch on your mobile device. The client-worker instance connects to your cloud deployment.

ClientTravel

Open a terminal window and run the following:

spatial project auth dev-auth-token create --description="my test token"

The response looks like this:

{"developmentAuthenticationToken":{"id":"<MY_DEV_AUTH_TOKEN_ID","projectName":"your_project_name","description":"my test token","creationTime":"2020-05-29T07:32:49.103463678Z","expirationTime":"2020-06-28T07:32:49.103463678Z"},"tokenSecret":"<MY_DEV_AUTH_TOKEN>"}

The response contains a field called tokenSecret. Copy and save the value of this field. In this example, it is <MY_DEV_AUTH_TOKEN>.

Travel URL

Here is a list of all Map URL options that you can use with the development authentication flow.

Option name
Type
Optional?
Description

devauth

flag

no

If you set this option, your client-worker instance connects using the development authentication flow.

devauthtoken

string

yes

This stores the development authentication token that the client-worker instance uses to authenticate against SpatialOS.

deployment

string

yes

The deployment that the client-worker instance should connect to. If not specified, the client-worker instance tries to connect to the first deployment available.

playerid

string

yes

The ID of the player that is connecting.

displayname

string

yes

User-defined player display name.

metadata

string

yes

Any metadata that you want to associate with the player.

customLocator

flag

yes

If set, it is used as the Locator host. Use this to connect to a Locator service that is not hosted at locator.improbable.io.

Refer to the Map travel URL options section for all possible URL options.

To specify the travel URL, use the following code snippet. Replace MY_DEV_AUTH_TOKEN with the tokenSecret that you received previously.

FURL TravelURL;
TravelURL.Host = TEXT("locator.improbable.io");
TravelURL.AddOption(TEXT("devauth"));
TravelURL.AddOption(TEXT("devAuthToken=MY_DEV_AUTH_TOKEN"));
TravelURL.AddOption(TEXT("deployment=MY_TARGET_DEPLOYMENT")); // optional 
TravelURL.AddOption(TEXT("playerid=MY_PLAYER_ID")); // optional 
TravelURL.AddOption(TEXT("displayname=MY_DISPLAY_NAME")); // optional 
TravelURL.AddOption(TEXT("metadata=MY_META_DATA")); // optional 
PlayerController->ClientTravel(TravelURL.ToString(), TRAVEL_Absolute, false /*bSeamless*/);

Command-line arguments

You can also trigger the development authentication flow by passing in command line arguments when you start your game. The first argument is the travel URL, and the others specify how to connect to the deployment. Only the devAuthToken argument is mandatory.

<MY_GAME_EXECUTABLE> connect.to.spatialos +devAuthToken <MY_DEV_AUTH_TOKEN> +deployment <TARGET_DEPLOYMENT> +playerId <MY_PLAYER_ID> +displayName <MY_DISPLAY_NAME> +metaData <MY_META_DATA> +locatorHost locator.improbable.io

2020-07-14 Restructure page content
2020-06-15 Page added with editorial review

Updated about a year ago


Development authentication flow


Suggested Edits are limited on API Reference Pages

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