Identity samples

The samples available as part of the Identity package demonstrate how to retrieve a valid access token for a user. The key components will show you how to initialize the services required to fetch this token, as well as how to then use this token to retrieve information about the user.

Prerequisites

Authentication sample

The Authentication sample demonstrates an interactive user login flow. When clicking the login button, the sample will open a browser page allowing you to log in to your account. Once successfully logged in, you can return to the sample scene and see your login status.

Once logged in, a refresh token is stored on your device until you log out. This allows the Identity service to attempt to automatically log you back in when relaunching the sample.

Installation

Importing the package samples is done via the Package Manager window, which will automatically copy the necessary assets into your base project.

  1. Inside your Unity project, go to Window > Package Manager and select the Digital Twins Identity package
  2. Expand the Samples section in the package window, and click Import on the Authentication sample.
    The samples import section of the package manager window
  3. Wait for the import process to complete, and view the imported assets under Assets/Samples/Digital Twins Identity.
    The imported sample

Running the sample

Running the Authentication sample is done via the AuthenticationSample scene.

  1. Open the sample at Assets/Samples/Digital Twins Identity/<package-version>/Authentication/AuthenticationSample.unity and run the scene.
  2. If you are not logged in, you should see an enabled Login button, and a message indicating no user is logged in.
    User is logged out
  3. Click the Login button. You should see the status has been updated to "Awaiting login..." and all buttons should be disabled.
    Awaiting login
  4. A browser window should launch allowing you to login via your Unity ID account. Follow the steps, and once successfully logged in, you should see the following browser message.

    Browser message
  5. Return to the sample scene, and see that you should now be logged in.
    User is logged in
  6. [Optional] You can test the automatic login via refresh token by simply relaunching the sample at this point (without logging out). You will see that the sample automatically enters the "Awaiting login..." state on launch, and should log you back in.

Key Components

If you're interested in seeing how the sample is built, below is a short description of the key components that should demonstrate how to use the Identity services to retrieve an access token.

Login Manager

File Location: Assets/Samples/Digital Twins Identity/<package-version>/Common/Scripts/LoginManager.cs

This is the main entry point for the sample. The LoginManager gets a handle on a IInteractiveAuthenticator, which is used to call the login/logout methods.

The authenticator also exposes an AuthenticationStateChanged event. This event is used by the LoginManager to update the state of the UI.

Platform Services

File Location: Assets/Samples/Digital Twins Identity/<package-version>/Common/Scripts/PlatformServices.cs

This class is responsible for initializing and disposing of the IInteractiveAuthenticator, as well as all the dependencies it requires. It exposes the authenticator via a property such that any component which needs authentication (i.e. the LoginManager) can retrieve it.

The accompanying classes, PlatformServicesInitialization and PlatformServicesShutdown are components which are used to call the initialization and shutdown methods through Unity's standard Monobehaviour methods: Awake() and OnDestroy().

Get user information sample

The Get User Information sample is an extension on Authentication sample, and demonstrates how the to use the Identity service to retrieve information about the logged-in user.

Installation

  1. Inside your Unity project, go to Window > Package Manager and select the Digital Twins Identity package
  2. Expand the Samples section in the package window, and click Import on the Get User Information sample.
    The samples import section of the package manager window
  3. Wait for the import process to complete, and view the imported assets under Assets/Samples/Digital Twins Identity.
    The imported user info sample

Running the sample

Running this sample is virtually identical to the Authentication sample. They main difference is you should also see your username appear once successfully logged in.
A logged in user

Key Components

This sample adds one important component to the Authentication sample, which handles fetching the user info for the logged in user.

User Name Updater

File Location: Assets/Samples/Digital Twins Identity/<package-version>/Get User Information/Scripts/UserNameUpdater.cs

This additional component has a handle on both an IAuthenticator as well as an IUserInfoProvider, initialized via the PlatformServices class. Once a user is logged in, the UserInfoProvider can be used to get the UserInfo for the logged in user, from which the user's name can be retrieved. The UI can then be updated accordingly.