Docs / Guides

Authentication

For connecting Microsoft admin accounts to several tenants in the Local Workbench, see Add tenants with Microsoft sign-in. Those encrypted, per-operator Graph connections are separate from the workbench login described below.

The operator plane -- who is allowed to use the bridge, and against which tenants -- is independent of the Microsoft plane (direct tenant admin connections or the optional partner SAM connection; see Architecture). This page covers the operator plane's three modes, and the self-service account model that ships with the local one.

Three modes

Set with Auth:Mode. Controllers share the same authentication plumbing, but access rules differ by mode: Local accounts use explicit tenant grants, while OIDC retains the all-access operator model described below.

Local accounts: open signup, scoped power

After setup, registration (POST /api/auth/register) is deliberately open: no invite code, no admin approval queue. On a Local Workbench's first run, the exe's single-use setup ticket is required before creating the first account. A fresh account starts with zero tenant access. It can log in and see the app shell, but can't run a single workflow or deployment against a customer tenant until someone shares that tenant with it.

Delegating instance administration

Instance roles govern shared bridge configuration, not customer data. An Administrator can use the Security screen's Instance access card to combine the narrow delegated roles below. Role changes take effect on the next request even for an already-issued login token or MCP PAT; roles are resolved from the database rather than trusted from stale token claims.

Owning a tenant

An Administrator becomes a tenant's Owner automatically when bringing it into the system, two ways:

• Add it directly -- POST /api/tenants (the "Add a tenant" form on the Tenants screen) if you already have the GDAP relationship and just want to start automating against it.
• Sync from Partner Center -- running an Administrator-only sync grants you Owner on any newly discovered tenant. A tenant the system already knew about just gets its name and domain refreshed; ownership is untouched.

Sharing (the collab model)

An Owner can grant another registered user access to that tenant, self-service, from the Tenants screen -- no central admin has to be the bottleneck for every hand-off:

Grants can carry an optional expiry -- useful for a contractor or a temporary engagement.

Two-factor authentication (TOTP)

Any local account can enable RFC 6238 TOTP from the Security screen. Enrollment is a two-step confirm: the app shows a secret (and an otpauth:// URI you can paste into most authenticator apps -- there's no QR code rendered client-side, deliberately: a live TOTP secret isn't something to hand to a third-party QR image service), and enabling only completes once you prove you captured it by entering a live code. Ten single-use recovery codes are shown exactly once at that point.

Once enabled, a password login returns an MFA challenge instead of a token; the account isn't considered logged in until the second factor clears. A wrong code doesn't burn the challenge -- it's retryable (bounded) within its short server-side lifetime, so a typo doesn't force you back through your password. A successful passkey login skips this step entirely: WebAuthn possession-plus-verification is already MFA-equivalent.

Passkeys (primary sign-in)

Passkeys are the primary way to sign in, not a bolt-on: registered as discoverable (resident) credentials, so the login screen's "Sign in with a passkey" button needs no email typed first -- the browser/authenticator presents whichever passkeys it holds for the site and the user picks one. Password stays the permanent fallback credential; it's never removable from an account, so a lost device or a browser without WebAuthn support can't lock anyone out.

Passkey ceremonies (/api/auth/passkey/*) are standard WebAuthn/FIDO2 via Fido2NetLib -- no proprietary protocol, works with platform authenticators (Windows Hello, Touch ID) and roaming ones (security keys) alike.

On the Local Workbench, the relying-party id is fixed to localhost and the one allowed origin is http://localhost:<port> -- WebAuthn ties a passkey to the RP id it was registered under, so this only works because every request is normalized onto that single canonical origin first (a request addressed to 127.0.0.1 or [::1] is redirected there before auth runs at all; see the canonical origin). A server deployment instead sets Auth:Local:Passkey:RelyingPartyId to its real domain and Origins to its HTTPS origin, per the configuration reference below.

MCP personal access tokens

A fourth credential type, layered on top of Local mode rather than a fourth Auth:Mode: a personal access token (PAT) is a long-lived, individually revocable JWT for machine callers -- specifically, an MCP client that can't do an interactive browser login. Mint one from the Security screen's "MCP access tokens" panel; it carries your identity while current roles, tenant grants, account status, and token revocation are checked from the database on every request. Revoke it immediately if the client using it is decommissioned or compromised.

Audit trail

Every security-relevant event is recorded to an append-only AuditEvents table: registration, login success/failure, logout, TOTP enable/disable, a recovery code being spent, passkeys added/removed, and every tenant-access grant or revoke -- who, when, and (for access changes) what role. Mutations to sensitive entities (accounts, tenants, contracts, templates, deployments, tenant grants) are captured automatically by an EF Core save-changes interceptor, so logging isn't something a future controller can forget to do. This is in addition to, not instead of, the workflow-run history described in Architecture.

Configuration reference