Developerguide Preview

Preview version Available

Preview version Available (beta-20251028) - Offline authentication using passkey & Multi user account management workflow

Trimble Identity .NET MAUI SDK Developer Guide

Contents

1. Overview
2. Authentication with Trimble Identity
3. Platform differences
4. Configure Client
   • Configure MobileAuthenticator
   • Platform Specific Setup
   • Persistent Storage
   • Enabling Offline authentication
   • Multi-User account management
5. Code Snippets
   • Example: How to Login
   • Example: How to Logout
   • Example: How to get an access token
   • Example: How to know the logged-in state
   • Example: How to get the logged-in user info
   • Examples: Multi-user account management
     • Initialize manager
     • Add account
     • Switch account
     • List accounts
     • Get active account
     • Remove account
     • Check capacity
6. Samples
7. FAQ

Overview

The Trimble Identity MAUI SDK is a .NET MAUI Class Library that implements the PKCE OAuth grant, which is used to secure authorization codes in public clients with custom URI scheme redirects (Android/iOS) and http scheme redirects (Windows).

.NET MAUI TID SDK MobileAuthenticator lets you start the authentication flow and listens to callback to a specific redirect URI registered in the application.

This SDK helps to authenticate users by exposing functionalities like,

• Login
• Logout
• Handling redirect
• Retrieve Access Token
• Retrieve User Information
• Know a Logged in state

Once the authorization flow is completed in the browser, application will redirect to a URI specified as part of the authorization request, providing the response via query parameters. In order for your app to capture this response:

• Android/iOS: uses a custom scheme based redirect URI (scheme://path)
• Windows: uses a http scheme based redirect URI (http://localhost:port/callback)
  • For example: http://localhost/callback, http://127.0.0.1:3000/login

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.

Platform differences

This section explains the platform-specific differences in MobileAuthenticator when authentication is launched in a browser.

=== “Android” Custom Tabs are used whenever available, otherwise the system browser is used as a fallback.

=== “iOS” Depending on the iOS version, behavior differs:

- <b>iOS 12 or higher:</b>
ASWebAuthenticationSession is used.
- <b>iOS 11:</b>
SFAuthenticationSession is used.
- <b>Older iOS versions:</b> SFSafariViewController is used if available; otherwise Safari is used.

=== “Windows” The default system browser is used.

Configure Client

Configure MobileAuthenticator

Create a single instance of the MobileAuthenticator which will remain for the lifetime of the application. The registration of this object requiring dependency injection should be performed in the CreateMauiApp method of MauiProgram class.

Client configuration

var options = new MobileAuthenticatorOptions
{
    EndpointProvider = "<ENDPOINT_PROVIDER>", // OpenIdEndpointProvider.Staging or OpenIdEndpointProvider.Production
    ClientId = "<CLIENT_ID>",
    Scopes = new[] { "<SCOPES>" },
#if WINDOWS
    RedirectUri = "<LOCALHOST_REDIRECT_URI>", // eg: http://localhost/callback
#else
    RedirectUri = "<CUSTOM_REDIRECT_URI>",  // eg: com.trimble.sample://oauth2redirect
#endif
    EnableTokenPersistence = true
};

builder.Services.AddSingleton(new MobileAuthenticator(options))

Note

Windows supports only localhost redirection and does not support any custom URI.

Platform Specific Setup

Note

In the current version, setting up custom view controllers is no longer required. Methods like mobileAuthenticator.WithActivity(activity) and mobileAuthenticator.WithViewController(viewController) are now deprecated and will be removed in future releases.

To access the MobileAuthenticator functionality, the following platform-specific setup is required.

=== “Android” Android requires an Intent Filter setup to handle your callback URI. This is accomplished by inheriting from the WebAuthenticatorCallbackActivity class: :::note[Android] ```csharp using Android.App; using Android.Content.PM;

namespace YourNameSpace;

[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(new[] { Android.Content.Intent.ActionView },
            Categories = new[] { Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable },
            DataScheme = CALLBACK_SCHEME)]
public class WebAuthenticationCallbackActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
{
    const string CALLBACK_SCHEME = "<CUSTOM_URI_SCHEME>";
}
```

If your project's Target Android version is set to Android 11 (R API 30) or higher, you must update your Android Manifest with queries that use Android's package visibility requirements.

In the Platforms/Android/AndroidManifest.xml file, add the following queries/intent nodes in the manifest node:

```xml
<queries>
<intent>
    <action android:name="android.support.customtabs.action.CustomTabsService" />
</intent>
</queries>
```
:::

=== “iOS”

:::note[iOS]
Add your app's callback URI pattern to the Platforms/iOS/Info.plist and Platforms/MacCatalyst/Info.plist files:

```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>App Name</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>CUSTOM_URI_SCHEME</string>
        </array>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
    </dict>
</array>
```
:::

=== “Windows”

:::note[Windows]
No platform-specific setup is required. The SDK internally handles the redirect.

SDK starts a `LocalhostListener` and listens for callback on the specified localhost redirect uri. When callback is received SDK internally validates the code and returns `isLoggedIn` as true if login was successful.
:::

Enabling Offline authentication

Enable offline authentication by setting EnableOfflineAuthentication = true in MobileAuthenticatorOptions (default: false).

• When enabled, mobileAuthenticator.Login() presents an offline sign‑in page that lets users authenticate with their previously registered passkey (biometric/PIN).
• On success, the SDK restores the user session and serves tokens from the secure cache created during an earlier online sign-in.

Prerequisite

• At least one successful online login on the device (to register the passkey and cache tokens).

Offline auth

var options = new MobileAuthenticatorOptions
{
    EndpointProvider = "<ENDPOINT_PROVIDER>",
    ClientId = "<CLIENT_ID>",
    Scopes = new[] { "<SCOPES>" },
#if WINDOWS
    RedirectUri = "<LOCALHOST_REDIRECT_URI>",
#else
    RedirectUri = "<CUSTOM_REDIRECT_URI>",
#endif
    EnableTokenPersistence = true,
    EnableOfflineAuthentication = true
};

var mobileAuthenticator = new MobileAuthenticator(options);

Multi-User account management

This SDK supports multi-user workflows and offline authentication with passkeys, enabling secure login without an active internet connection. You can:

• Switch between users
• Add or remove user accounts
• Work seamlessly across online and offline states

Supported operations

• AddAccount requires the device to be online; operation observes timeoutInMs and can be cancelled.
• SwitchAccount prompts the user to re-authenticate; throws if the target account does not exist.
• GetAccounts, RemoveAccount, and GetActiveAccount require that a user is logged in.
• Configure maximum accounts when creating MultiUserAccountManager (default: 5, Allowed range: 1–10).

A logged-in user is required to perform any of these operations.

Persistent Storage

The SDK uses Secure Storage for token persistence. It stores data in key and value pairs and gets deleted once the app is uninstalled. Each platform uses the platform provided native API’s for storing data securely:

• Android: Encryption keys are stored in KeyStore and encrypted data is stored in a named shared preference container (PackageId.Microsoft.Maui.Essentials). As a best practice, you can choose to disable Auto Backup for your application, or You can create a custom rule set to exclude Secure Store items from being backed up.

• iOS: Data is stored in KeyChain. When developing on the iOS simulator, enable the Keychain entitlement and add a keychain access group for the application’s bundle identifier. For more details refer secure storage on iOS Simulator

• Windows: DataProtectionProvider is used to encrypt values and it is stored in ApplicationData.Current.LocalSettings, inside a container with a name of [YOUR-APP-ID].microsoft.maui.essentials.preferences.

To disable Secure storage, set EnableTokenPersistence to false in MobileAuthenticatorOptions while instantiating MobileAuthenticator.

Code Snippets

Example: How to Login

Summary

Log the user in. On Login, MobileAuthenticator launches the browser and listens to a callback redirect by invoking OnReceive() to complete authorization flow.

Returns

true if the user was successfully logged in

Login

var isLoggedIn = mobileAuthenticator.Login();

Example: How to Logout

Summary

Log the user out.

Returns

true if the user was successfully logged out

Logout

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

Set singleSignOut to true to sign out of all SSO session. On Logout, MobileAuthenticator launches the browser and listens for callback redirect using OnReceive() to complete Logout when singleSignOut = true . The same OnReceive() method handles redirect for Login and Logout.

By default singleSignOut is set to false when Logout() is invoked which helps user to logout without clearing the browser session.

Example: How to get an access token

Summary

Retrieves access token of authenticated user.

NOTE: If the access token has expired, then the SDK refreshes the access token internally and returns the new access token.

Returns

Access token of authenticated user

Example access token

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

Example: How to know the logged-in state

Summary

Get the logged in state

Example loggedin state

var isLoggedIn = mobileAuthenticator.IsLoggedIn;

Example: How to get the logged-in user info

Summary

Validates the ID token and returns user claims

Returns

User claims from the ID token

Example user info

var userInfo = await mobileAuthenticator.GetUserInfo();

Examples: Multi-user account management

MultiUserAccountManager is responsible for managing user accounts in a multi-user environment

Use the links below to jump to a specific operation:

• Initialize manager
• Add account
• Switch account
• List accounts
• Get active account
• Remove account
• Check capacity

Initialize manager

Initializes a new instance of the MultiUserAccountManager class.

Example mua init

var authenticator = builder.Services.GetService<MobileAuthenticator>();
var accountManager = new MultiUserAccountManager(authenticator, maxUserAccounts: 5);

Add account

Add a new account.

Example mua add

var added = await accountManager.AddAccount(); // requires online connection

Switch account

Switch to an existing account.

Example mua switch

var switched = await accountManager.SwitchAccount(userId: "user-123"); // prompts re-authentication

List accounts

Retrieve a list of all stored accounts.

Example mua list

var accounts = await accountManager.GetAccounts();

Get active account

Retrieve the currently active account.

Example mua active

var active = await accountManager.GetActiveAccount();

Remove account

Remove a specific account by its Id.

Example mua remove

var removed = await accountManager.RemoveAccount(userId: "user-123");

Check capacity

Check if more accounts can be added.

Example mua capacity

var canAdd = await accountManager.CanAddAccounts();

Samples

Explore working examples in the repository:

• MauiSampleApp: samples/identity/MauiSampleApp
• MauiMultiUserAccountSampleApp: samples/identity/MauiMultiUserAccountSampleApp

FAQ

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