Trimble.ID.Desktop Client SDK Developer Guide

Content

Overview
Authentication with Trimble Identity
Configure the endpoint
Code snippets
FAQ

Overview

Trimble.ID.Desktop is a .NET library that can be used to add authentication to your desktop applications.

Authentication with Trimble Identity

To utilize TID authentication, your identity application must be registered with Trimble Identity. You can conveniently handle the application registration process on Trimble Developer Console.

Configure the endpoint

Configure the well-known URL endpoint is used to retrieve the authorization, token and user info endpoints for Trimble OAuth server.

Well-Known URL	https://id.trimble.com/.well-known/openid-configuration

Create a single instance of the LocalhostAuthenticator which will remain for the lifetime of the application. The LocalhostAuthenticator is responsible for managing the authentication flow and token refresh.

Ensure to configure the https://localhost as a valid redirect URI in the Trimble Developer Console.

const string WELL_KNOWN_ENDPOINT = "https://id.trimble.com/.well-known/openid-configuration";
const string CLIENT_ID = "TID_CLIENT_ID";
var string SCOPES = new [] { "TID_SCOPES" };
IEndpointProvider endpointProvider = new OpenIdEndpointProvider(new Uri(WELL_KNOWN_ENDPOINT, UriKind.Absolute));
IAuthenticator authenticator = new LocalhostAuthenticator(endpointProvider, CLIENT_ID, SCOPES);

Persistent Storage

The SDK uses Isolated storage mechanism for storing the user tokens. The storage is encrypted and is only accessible by the application. The storage is not shared between applications. See below code snippet for configuring the persistent storage with encryption.

   byte[] Salt = { 0xb7, 0xa2, 0x46, 0x53, 0x84, 0xf0, 0x49, 0xc6, 0x4f, 0x9b };
   IAuthenticator authenticator = new LocalhostAuthenticator(OpenIdEndpointProvider.Production, CLIENT_ID, SCOPES)
                                       .WithPersistentStorage(new EncryptedStorage(new IsolatedFileStorage(<"filename.config">), Salt));

NOTE: Token lifetime and refresh are handled automatically. If the client uses persistent storage, our SDK securely stores tokens in isolated storage. This means that any subsequent application launches will trigger automatic silent login with the stored tokens. This enables users to seamlessly access the application without the need to manually enter their credentials.

Offline access

Offline access mode allows you to fetch user information and an access token even when offline, and continue to issue new tokens when a network becomes available. This mode bypasses token expiration checks and allows the issuance of existing tokens and user details from persistent storage. It is particularly useful in offline scenarios where you need to retrieve information without an active network connection.

NOTE: Requires at least one initial sign-in to initialize the token from the cache.

To enable offline access mode, use the following code:

IAuthenticator authenticator = new LocalhostAuthenticator(OpenIdEndpointProvider.Production, CLIENT_ID, SCOPES)
                                        .WithPersistentStorage(new EncryptedStorage(new IsolatedFileStorage(<"filename.config">), Salt))
                                        .WithOfflineAccess();

Please refer here to fetch user information.

Summary

Log the user in. On Login, authenticator launches the browser for user login.

Returns

true if the user was successfully logged in

var isLoggedIn = await authenticator.Login();

Example: How to get an access token

Summary

Retrieves access token of authenticated user. Token lifetime and refresh are handled by the SDK.

Returns

Access token of authenticated user

var accessToken = await authenticator.TokenProvider.RetrieveToken();

Example: How to know logged-in state

Summary

Get the logged in state

var isLoggedIn = authenticator.IsLoggedIn;

Example: How to get logged-in user info

Summary

Validates the ID token and returns user claims

Returns

User claims from the ID token

var userInfo = await authenticator.GetUserInfo();

Example: How to Logout

Summary

Log the user out. Returns

true if the user was successfully logged out

var isLoggedIn = authenticator.Logout(singleSignOut: true);

FAQ

Do you have questions? Do not worry, we have prepared a complete FAQ answering the most common questions.