Custom ID sign-in

Provide a Custom ID sign-in option to enable players to authenticate using your custom identity system in your game.

Read time 2 minutes

Last updated 7 months ago

Minimum SDK version: 3.1.0

If you already have an existing player management system that creates player IDs, you can use the Custom ID provider to link the identities. The Custom ID providers works by having game clients make requests to your game backend. Your backend uses Service Account credentials to generate tokens for the players with custom IDs and returns it to them for use with UGS services. Since the Unity Authentication service is not in control of the provided player IDs, it needs to rely on a server-authoritative backend and cannot allow game clients to request their own tokens. This article guides you through the following scenarios to set up authentication for players in your game with a Custom ID provider:

Set up Custom ID Provider sign-in.
Sign in a returning user or create a new user.

Add Custom ID as an ID provider for Unity:
1. In the Unity Editor select Services > Authentication > Configure from the navigation menu.
2. Set ID Providers to Custom ID, then select Add.
Create a Service Account and add project role Player Authentication Token Issuer. These credentials will be used by your backend to make requests to the Unity Authentication service.

Client-side setup

Together with the server side sign in set up further below, an access token has to be retrieved from your backend and processed with the

AuthenticationService

ProcessAuthenticationTokens

is used to process Unity Authentication Service Tokens and makes them available to other UGS SDKs integrated into the game that require the player to be authenticated. This results in the player being effectively signed in using the tokens provided. You should call

ProcessAuthenticationTokens

with both the access token and the session token. The Unity Authentication SDK refreshes the access token before it expires to keep the player's session active. Refer to the page on session management for more details. Alternatively you can call

ProcessAuthenticationTokens

with only the access token. However since access tokens expire after 1 hour you must manually refresh the access token and call

ProcessAuthenticationTokens

with the new access token.


using Unity.Services.Authentication;async Task SignInUserWithCustomID(){    try    {        // Check if a cached player already exists by checking if the session token exists        if (AuthenticationService.Instance.SessionTokenExists)        {            // This call will sign in the cached player.            await AuthenticationService.Instance.SignInAnonymouslyAsync();            Debug.Log("Cached user sign in succeeded!");        }        else        {            var userTokens = ; // Fetch the user tokens using method calls to your backend            AuthenticationService.Instance.ProcessAuthenticationTokens(userTokens.AccessToken, userTokens.SessionToken);        }        // Shows how to get the playerID        Debug.Log($"PlayerID: {AuthenticationService.Instance.PlayerId}");    }    catch (AuthenticationException ex)    {        // Compare error code to AuthenticationErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (RequestFailedException ex)    {        // Compare error code to CommonErrorCodes        // Notify the player with the proper error message        Debug.LogException(ex);    }    catch (Exception ex) {        // Handle exceptions from your method call        Debug.LogException(ex);    }}

Note that the sample code is a method only, not a class. The access and session tokens need to be retrieved from your backend. Refer to the Server-side setup below for more information on that.

Server-side setup

During the player sign-in process on your backend, each player is signed up with Unity Authentication service using their custom ID and granted a

accessToken

and

sessionToken

. Your backend uses the Service Account credentials to perform the requests to sign up the players with Unity Authentication.

Call the Token Exchange API to retrieve a stateless token.
Call the Sign In With Custom ID API:


curl --location 'https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id' \--header 'Content-Type: application/json' \--header 'UnityEnvironment: <ENVIRONMENT_NAME>' \--header 'Authorization: Bearer <STATELESS_TOKEN' \--data '{    "externalId": "YOUR_CUSTOM_PLAYER_ID"}'

The response of this request will contain an

idToken

and a

sessionToken

that you have to return to the game client for initializing the

AuthenticationService

. The

idToken

can be used as the

accessToken

in this context.

Linking an existing player

If the player already has a Unity Authentication account, they can be linked by providing the existing access token to the Custom ID sign-in request. The access token will need to be provided either by the player in their request to your backend, or requested by your backend if it knows which existng Unity player ID they want to be linked to:


curl --location 'https://player-auth.services.api.unity.com/v1/projects/<PROJECT_ID>/authentication/server/custom-id' \--header 'Content-Type: application/json' \--header 'UnityEnvironment: <ENVIRONMENT_NAME>' \--header 'Authorization: Bearer <STATELESS_TOKEN' \--data '{    "externalId": "YOUR_CUSTOM_PLAYER_ID"    "accessToken": "EXISTING_PLAYER_ACCESS_TOKEN"}'

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Authentication

Get started

Authentication

Custom ID sign-in

Minimum SDK version: 3.1.0

Client-side setup

Server-side setup

Linking an existing player

Custom ID sign-in

Minimum SDK version: 3.1.0

Set up a Custom ID Sign In

Client-side setup

Server-side setup

Linking an existing player