Authentication and tokens

Dockli authenticates every user through the Microsoft Authentication Library (MSAL) and the native Windows account broker (WAM). From there, the access token lives entirely inside Dockli’s local service — acquired, refreshed, cached, and encrypted server-side — and is attached to Microsoft Graph calls without ever entering the WebView2 UI.

Sign-in: MSAL through the Windows broker

When a user signs in, Dockli calls MSAL configured to use the Windows broker (WithBroker(BrokerOptions(OperatingSystems.Windows))). The broker is the same native Windows component that handles sign-in for Outlook, Teams, and every other Microsoft 365 app on the machine.

The consequences for security:

• No passwords touch Dockli. The credential exchange — password, MFA, Windows Hello, conditional-access checks — happens inside Windows and Microsoft Entra. Dockli only ever receives the resulting token.
• The interactive prompt is a native Windows dialog, not a page rendered by Dockli. The broker window is anchored to the foreground window so it appears on top of File Explorer, but Dockli never sees what the user types.
• Conditional Access and device compliance apply. Because sign-in flows through the standard broker, your Entra Conditional Access policies (compliant device, managed device, MFA, sign-in risk) are enforced exactly as they are for any other Microsoft 365 app.

The app registration Dockli uses is a multi-tenant Entra application:

Why the UI never sees a token

The token is acquired and held by AuthManager inside the headless local service. When the WebView2 UI needs data, it calls the loopback API at http://localhost:5050; the service acquires (or silently refreshes) the delegated Graph token server-side and attaches it to the outbound Microsoft Graph request. The token value is never returned to the browser.

This is why the app can keep its CORS policy uncredentialed: there is nothing token-shaped in the browser to protect, because the credential lives only server-side. See Security architecture for how the loopback boundary is enforced.

Token cache and encryption at rest

MSAL persists its token cache so a returning user is remembered across restarts without re-authenticating. Dockli writes that cache to:

%LocalAppData%\Dockli\Data\msal_cache.bin

The file is encrypted with the Windows Data Protection API (DPAPI) at the CurrentUser scope. Concretely:

• On write, the serialized MSAL cache is passed through ProtectedData.Protect(..., DataProtectionScope.CurrentUser) before hitting disk.
• On read, it is decrypted with ProtectedData.Unprotect(...).
• If the file is corrupt, or was produced by a different Windows user or a different machine, decryption fails and Dockli starts from a clean, signed-out state rather than trusting foreign bytes.

Silent refresh vs. interactive prompts

Dockli prefers silent token acquisition and only prompts interactively when it has to:

• On startup, the service rehydrates the signed-in account from the encrypted cache (a local read, no network) so the user stays signed in across reboots and relaunches.
• For every Graph call, it calls AcquireTokenSilent, which returns a cached valid token or transparently uses the refresh token to mint a new one.
• Only when silent acquisition fails with MsalUiRequiredException — an expired session, revoked refresh token, or a newly required consent — does Dockli fall back to an interactive broker prompt. When the user explicitly clicks Sign in, the account picker is always shown.

Multiple accounts

Dockli supports adding several Microsoft 365 accounts (across tenants) and switching between them:

• Dockli tracks its own curated list of accounts the user has added, persisted to %LocalAppData%\Dockli\Data\accounts.json (the added account identifiers plus which one is active). It deliberately does not blindly trust every Windows account the broker surfaces — only accounts the user explicitly added to Dockli are used.
• Switching accounts is silent when that account’s refresh token is still valid, and falls back to an interactive prompt for just that one account if it is not.
• All accounts share the one DPAPI-encrypted MSAL cache. Per-account state (such as favorites) is keyed by the account’s stable identifier so switching gives a clean, correctly-scoped view.

Incremental consent tokens

Some capabilities need Graph scopes beyond the base set. Rather than request them all up front, Dockli acquires them incrementally — a separate token, consented the first time the feature is used:

• Sending email (Mail.Send), Teams messaging, and people lookup each acquire their own scoped token on first use.
• SharePoint recycle-bin and permission operations acquire a per-host delegated token (audience = the SharePoint host, e.g. https://contoso.sharepoint.com) carrying AllSites.Write on that host only.

These are kept off the primary scope set on purpose, so an as-yet-unconsented scope can never break the core Graph calls. The full list is in Permissions and scopes.

Sign-out and cache removal

Dockli offers two levels of sign-out:

• Sign out the active account removes just that account from the broker and Dockli’s added-accounts list, then promotes the next remaining account to active. If none remain, the app ends fully signed out.
• Sign out of everything / clear cache removes every account from the MSAL cache, clears the added-accounts list and the active marker, and empties the in-memory token.

Uninstalling Dockli clears its entire local data folder, including the encrypted token cache, and releases the user’s licensed seat back to the organization. See Data handling and residency for exactly what is stored and removed.