Skip to content

Latest commit

 

History

History
133 lines (88 loc) · 4.86 KB

DeveloperGuide.md

File metadata and controls

133 lines (88 loc) · 4.86 KB
Raw

Trimble.ID.Desktop Client SDK Developer Guide

Content

  1. Overview
  2. Authentication with Trimble Identity
  3. Configure the endpoint
  4. Code snippets
  5. 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

Code snippets

Configure LocalhostAuthenticator

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.

Example: How to Login

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 = authenticator.Login();

Example: How to get an access token

Summary

Retrieves access token of authenticated user

Returns

Access token of authenticated user

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

NOTE: Token lifetime and refresh are handled by the SDK.

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.