Integrate authentication in your scene

This section explains how to set up your scene to integrate an authentication layer to communicate with Digital Twin services.

An authentication process should retrieve an access token that identifies your application user when calling Digital Twin services. Identity supports the following login flows to retrieve an access token:

Automated flow: A flow often recommended for automated tools, where the user can generate a personal access token (PAT) from the Digital Twin Portal and inject it into the application to avoid a UI.
Preauthenticated flow : A flow that can be used by web-hosted plaforms (Furioos, WebGL) where the host already has a valid access token. In that case, identity can skip the user login flow and directly use the host's access token.
User login flow: A standard flow where the user must fill a login form through a UI.

Prerequisites

Follow the Installation instructions.
Follow the Get started instructions.
Follow the Best practices: dependency injection guide.

Overview

To integrate authentication in your scene, perform the following procedures:

Instantiate a CompositeAuthenticator in PlatformServices
Tie Identity's authentication engine with UI
Leverage the access token to communicate with other Digital Twin services

Instantiate a CompositeAuthenticator in PlatformServices

To instantiate a CompositeAuthenticator in the PlatformServices class, see the following steps:

Add the following references in the PlatformServices class:

A public reference to IInteractiveAuthenticator and IAccessTokenProvider

A private reference to UnityHttpClient and CompositeAuthenticator

   static UnityHttpClient s_HttpClient;
   static CompositeAuthenticator s_CompositeAuthenticator;

   public static IInteractiveAuthenticator InteractiveAuthenticator => s_CompositeAuthenticator;
   public static IAccessTokenProvider AccessTokenProvider => s_CompositeAuthenticator;

Initialize the services in the InitializeAsync method.

    public static async Task InitializeAsync()
    {
        var playerSettings = DigitalTwinsPlayerSettings.Instance;
        s_HttpClient = new UnityHttpClient();
        s_CompositeAuthenticator = new CompositeAuthenticator(s_HttpClient, playerSettings, playerSettings);

        await s_CompositeAuthenticator.InitializeAsync();
    }

Shutdown the services in the Shutdown method.

    public static void Shutdown()
    {
        s_CompositeAuthenticator.Dispose();
        s_CompositeAuthenticator = null;

        s_HttpClient.Dispose();
        s_HttpClient = null;
    }

Tie Identity's authentication engine with UI

Identity's authentication engine doesn't handle any UI, so you must create a login UI and link it to the authentication engine. The authentication engine automatically decides which authentication flow to use based on certain conditions (see Authentication flows). This means some parts of the UI must stay hidden, depending on the situation.

Create Login and Logout buttons in your scene. These buttons are used if the authentication engine uses the user login flow.
Create a LoginManager GameObject and attach a new LoginManager MonoBehaviour to it. This script links your UI with Identity's authentication engine.

Update the LoginManager script so it references your buttons and an IInteractiveAuthenticator.

    public class LoginManager : MonoBehaviour
    {
        [SerializeField]
        Button m_LoginButton;

        [SerializeField]
        Button m_LogoutButton;

        IInteractiveAuthenticator m_Authenticator;
    }

Update the Awake method to do the following:

Retrieve the IInteractiveAuthenticator from PlatformServices.
Subscribe to the AuthenticationStateChanged event.
Subscribe to the buttons' onClick events.

Call ApplyAuthenticationState to update the UI when the scene loads.

   void Awake()
   {
       m_Authenticator = PlatformServices.Authenticator;
       m_Authenticator.AuthenticationStateChanged += ApplyAuthenticationState;

       m_LoginButton.onClick.AddListener(new UnityEngine.Events.UnityAction(OnLoginButtonClick));
       m_LogoutButton.onClick.AddListener(new UnityEngine.Events.UnityAction(OnLogoutButtonClick));

       ApplyAuthenticationState(m_Authenticator.AuthenticationState);
   }

Make sure the subscriptions are cleaned up in OnDestroy.

    void OnDestroy()
    {
        m_Authenticator.AuthenticationStateChanged -= ApplyAuthenticationState;

        m_LoginButton.onClick.RemoveAllListeners();
        m_LogoutButton.onClick.RemoveAllListeners();
    }

Implement the ApplyAuthenticationState method to update your buttons based on the current authentication state. Make your buttons interactive in specific circumstances, otherwise you risk errors and exceptions. To determine if you should display your buttons, rely on the AuthenticationState and the Interactive property that determines whether the UI is relevant in the selected authentication flow.

    void OnAuthenticationStateChanged(AuthenticationState state)
    {
        switch (state)
        {
            case AuthenticationState.LoggedOut:
                m_LoginButton.interactable = m_Authenticator.Interactive;
                m_LogoutButton.interactable = false;
                break;
            case AuthenticationState.LoggedIn:
                m_LoginButton.interactable = false;
                m_LogoutButton.interactable = m_Authenticator.Interactive;
                break;
            case AuthenticationState.AwaitingLogin:
            case AuthenticationState.AwaitingLogout:
                m_LoginButton.interactable = false;
                m_LogoutButton.interactable = false;
                break;
        }
    }

Define the behaviors for your buttons by calling the appropriate methods.

Note: Only the user login flow (when Interactive is set to true) requires these methods. If the flow isn't interactive, calling LoginAsync or LogoutAsync throws exceptions.
```
    async void OnLoginButtonClick()
    {
        await m_Authenticator.LoginAsync();
    }

    async void OnLogoutButtonClick()
    {
        await m_Authenticator.LogoutAsync();
    }
```
Test your scene to see how the buttons update along with the authentication state of the user.

Leverage the access token to communicate with other Digital Twin services

After you set up your login flow, communication with other Digital Twin services is possible. All Digital Twin services expect an instance of IAccessTokenProvider, which the PlatformServices provides.

For an example of a service that expects an IAccessTokenProvider, refer to the Get user information guide.

Authentication flows

The CompositeAuthenticator contains logic to choose an authentication flow based on certain pre-conditions. This section lists the supported flows, their corresponding pre-conditions, and how to use them.

Automated flow

This flow is for automated workflows (for example, unit testing) and isn't interactive. This flow works through a PAT that you generate.

Generate your personal access token

To generate your PAT, see the following steps:

Log into the Digital Twins portal.
Go to the Identity swagger page.

Use POST /api/personal-access-tokens > [Try it out] > Execute. The following is an example of the response:

{
"PersonalAccessToken": "PAT",
"Uid": "uid",
"Comment": "string",
"CreationTicks": 637962807880335700
}

Save your PAT. You can't see it after this step.

Note: The URLs must be slightly adapted if you want to generate an API token on a different cloud environment than production.

Inject the personal access token in your application

The CompositeAuthenticator tries to find a PAT in the following ways:

From a command line argument passed to the application.

    ./MyApp.exe -DT_PERSONAL_ACCESS_TOKEN [MyAccessToken]

From a DT_PERSONAL_ACCESS_TOKEN environment variable set before running the application.

If the CompositeAuthenticator retrieves a PAT from one of the above sources, it automatically launches the automated authentication flow.

Preauthenticated flow

This non-interactive flow is for workflows where authentication happens before launching the application. For example, when using the Furioos system inside the Digital Twin dashboard and the user is already logged into the dashboard, so the existing access token passes to the nested Furioos application.

Note: The CompositeAuthenticator supports only the Furioos flow and some additional code is needed to tie the authentication engine and the Furioos API together (refer to the Furioos sample for more information).

This flow (OAuth 2.0 with PKCE) is the regular login flow where the user uses a login UI to provide their credentials and retrieve an access token. This flow is interactive (which means you expose the login and logout buttons) and used by CompositeAuthenticator by default if none of the pre-conditions listed above is detected.