Custom ID sign-in#

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.

Set up a Custom ID Sign In#

1. 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.

2. 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.

1. Call the Token Exchange API to retrieve a stateless token.
2. 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"
}'