Portal Authentication And Account Management

Purpose

This functional area manages how human users access the Portal and maintain their own account security.

It covers both local platform authentication and federated sign-in through external identity providers such as Microsoft Entra ID and Keycloak.

Main Capabilities

username and password login
refresh-token based session continuation
logout
MFA setup, enablement, verification, and disablement
backup code generation and regeneration
tenant selection when users belong to multiple tenants
self-service account profile updates
self-service password change
password-change-required enforcement for local accounts
active session review and session revocation
light and dark display mode switching

Local Authentication

The Portal supports direct credential-based authentication for platform users.

Functionally this includes:

validating a user’s credentials
issuing authenticated portal sessions
guiding the user through tenant selection when multiple tenant assignments are valid
refreshing sessions without forcing repeated logins
terminating sessions on logout

This is the core sign-in path for platform-managed accounts.

Before validating credentials, the sign-in pipeline checks the user’s authentication mode. If the account is set to External only, local sign-in is blocked immediately and the user receives a clear error indicating that they must use their organisation’s identity provider. This check does not count towards brute-force lockout counters, because it is a configuration gate rather than a credential failure.

Repeated failed credential attempts for a local account result in a sign-in lockout, deterring brute-force password guessing. A locked-out account cannot authenticate until an administrator clears the lockout through the Users page. See Portal Tenant And User Administration for details.

Failed-attempt tracking is designed to remain accurate and consistent even under concurrent or high-volume attempts, so the lockout threshold cannot be bypassed by simultaneous requests.

Authentication enforcement fails closed: the platform does not continue a local sign-in or MFA verification when it cannot reliably establish whether a lockout applies, and such failures are captured for operational monitoring.

Stored passwords are hashed with PBKDF2-SHA256 at the current OWASP-recommended work factor. The work factor is recorded with each hash, so an account created under an older factor is rehashed at its next successful sign-in rather than being left behind — and without treating that as a password change, which would otherwise reset the user's rotation clock. A hash claiming a work factor below the platform's floor is rejected outright.

For local sign-in, the platform can also require a password change before normal portal access continues. This typically happens when an administrator has set a new password for the user or when password rotation policy requires remediation. In that state, the user can authenticate but is restricted to the password-change flow until a compliant new password is chosen.

Bootstrap Administration

The platform includes a first-run bootstrap seeding mechanism that creates the initial super-admin account when none exists.

The bootstrap administrator password is not hardcoded in the platform. It must be supplied by the operator through environment configuration before the platform starts for the first time. If the password is absent or matches a known placeholder, the platform refuses to start in a production environment.

The bootstrap super-admin account is created with a mandatory password-change flag. The operator must choose a new, unique password on the first sign-in before accessing any other portal feature. This ensures that the initial credentials used during setup are never retained as a long-lived access path.

Multi-Factor Authentication

The Portal includes built-in MFA capabilities to strengthen operator sign-in.

Supported MFA functions include:

TOTP-based setup
verification during login
MFA enablement after setup
MFA disablement with verification
backup code issuance
backup code regeneration

This allows the platform to enforce stronger authentication for administrative users.

The Portal supports federated sign-in through external identity providers using the OIDC Authorization Code + PKCE flow.

Supported external identity providers include:

Microsoft Entra ID
Keycloak

Functionally this includes:

login provider discovery
challenge creation for browser redirect flows
callback processing
tenant-aware provider resolution
tenant selection when users belong to multiple tenants
optional email-based account linking

This lets organizations integrate the Portal with enterprise identity infrastructure instead of relying only on local credentials.

During external sign-in, the pipeline checks the user's authentication mode after resolving the account. If the account is set to Local only, external sign-in is blocked and the user receives a meaningful message explaining that only local credentials are permitted for their account.

Account Self-Service

Authenticated users can manage their own account profile through the Portal.

Supported self-service actions include:

view current account details
update account profile fields
change password
review effective role assignments for the current session context
manage MFA state

Session Management

The Portal provides session visibility and session control.

Users can:

list their active sessions, paginated, with the session the request is currently authenticated with labeled "This device"
revoke a specific session
select several sessions and revoke them together
revoke every other active session in one action, leaving the current device signed in

Super-admin users can also review and revoke sessions for other users when required by governance or security operations.

Revoking a session takes effect immediately and everywhere: once a session is revoked, its access is rejected on its very next use, whether presented back to the Portal or to the Runtime, without waiting for any token to expire naturally. This applies to every kind of session, including the RFC 8628 device flow and OAuth-client sessions described below. If the platform detects signs that a session's credentials may have been compromised or reused improperly, it automatically revokes every other active session for that account as a precaution.

Password changes and session revocations are also written into governance audit records as portal-auth configuration events so operators can trace administrative account security actions alongside normal sign-in activity.

Silent Access Token Renewal

The Portal SPA keeps its access token refreshed without interrupting the user. Two mechanisms work together:

Proactive renewal — as soon as a session is established, the SPA schedules a refresh a minute ahead of the access token's own expiry, so an ordinary click almost never has to wait on a refresh round-trip or race an about-to-expire token.
Renewal on return to the tab — background/inactive browser tabs throttle or suspend JavaScript timers, so the proactive schedule above cannot be relied on by itself. Whenever the tab regains visibility or focus, the SPA re-checks the token's expiry immediately and refreshes right away if it is already due.

A reactive fallback still exists for the rare case both of the above miss: if a request is sent with an expired token anyway, the API responds 401, the SPA transparently refreshes and retries the request once, and only signs the user out if that refresh itself fails (e.g. the refresh token has also expired). The net effect is that an expired access token is renewed behind the scenes rather than surfacing to the user as an unexpected redirect to the login page.

Device Authorization Grant

The Portal supports the OAuth 2.0 Device Authorization Grant (RFC 8628), which lets AI agents and CLI tools authenticate without running a browser themselves.

This flow is used when an agent is running in an environment that cannot receive browser redirects, such as a terminal, a background service, or an automated pipeline.

Functionally the flow works as follows:

the agent calls the platform initiation endpoint and receives a short alphanumeric user code and a verification URL
the agent displays the code and URL to the operator and begins polling for a token
the operator opens the verification URL in a browser and is prompted to enter the code, or the code is passed automatically in the URL so the page pre-fills it
if the operator is not already signed into the Portal, they are redirected to the login page and then returned to the device page after authentication
the operator reviews the request and either approves or denies it
once the operator approves, the agent's next poll receives an access token and refresh token with the same permissions as the operator's portal session
if the operator denies the request, the agent receives an access denied response on the next poll

The platform enforces a minimum polling interval to prevent excessive load. If the agent polls too frequently it receives a slow_down response and should increase its wait before retrying.

Device flow sessions have a fixed expiry window. If the operator does not act before the session expires, the agent receives an expired_token response.

Device Verification Page

The Portal Web application hosts a dedicated verification page at /device. This page is intentionally accessible without authentication so that the operator can land on it directly from a browser without signing in first.

If the operator is not signed in when they reach the page, the page shows the session details and a sign-in prompt. After the operator authenticates, they are returned to the device page with the code pre-filled and can immediately review and act on the request.

If the operator arrives with the code pre-filled in the URL query string, the page performs an automatic lookup of the session without requiring a manual code entry.

The page presents the request in a clear approval or denial screen. The operator can approve or deny the request with a single action. After acting, the page confirms the outcome and instructs the operator that they can close the browser tab.

Audit Events

All device flow lifecycle events are written to the governance audit trail:

session initiated — records the initiating agent's IP address and session identifier
session approved — records the approving user, tenant scope, and session identifier
session denied — records the denying user and session identifier
token issued — records the user, tenant, and session identifier once the polling agent receives its token

Session identifiers correlate all events for a given device flow lifecycle across initiation, approval, and token issuance.

Session Expiry And Cleanup

Device flow sessions that remain in a Pending state beyond their expiry are automatically transitioned to Expired status by a scheduled background maintenance process. Expired, denied, and approved sessions are purged after the configured retention window.

Browser-Based Runtime Authorization

The Portal also participates in the OAuth 2.0 Authorization Code + PKCE flow used by browser-capable runtime clients.

Functionally, this flow works as follows:

the runtime authorization endpoint validates the OAuth request and redirects the browser into the normal Portal login experience instead of rendering a separate minimal login form
the Portal preserves the OAuth authorization request across the full sign-in journey, including external identity provider redirects, MFA verification, and tenant or context selection when required
the login page shows a dedicated runtime-authorization review state so the operator understands that access is being granted to a client application through the current portal account
the review card presents a compact summary of the requesting application, including the callback host-derived application label and client ID when available
if the operator is already authenticated when the request arrives, the Portal does not complete the handoff automatically; it requires an explicit confirmation click before runtime access is granted
once the operator confirms, the Portal completes the authorization handshake and redirects the browser back to the client callback URI with the issued authorization code

This flow works consistently for accounts using MFA or external identity providers during runtime authorization.

What the operator is approving

The review card lists the specific permissions the client is asking for, and that list is what the platform enforces afterwards — see Runtime Authorization → Consented Scope Enforcement. The grant is always the intersection of what the operator approved and what the client registered for, and it can never exceed what the approving account could do itself.

Client registration lifecycle

AI clients register themselves against the platform automatically the first time they connect; there is no administrator step. Because that surface is open, it is bounded:

a client receives a management credential once, at registration, and uses it to read, update or delete its own registration later. It cannot manage any other client, and the platform answers identically whether a client id is unknown, unaccompanied by a credential, or accompanied by the wrong one — so the endpoint cannot be used to discover which clients exist
a client may only use the grant types it registered for
a client can revoke its own tokens through a standard revocation endpoint
registrations that never complete a sign-in are swept away, so abandoned or automated registration attempts do not accumulate

The Portal's OAuth Clients screen is a read-only view of this registry for platform operators.

How Portal tokens are signed

Portal access tokens are signed with a private key that the Portal alone holds, and validated by everything else against the matching public key, which is published at a standard JWKS endpoint. Nothing that can read the platform's configuration or its secret store can produce a token the Portal will accept.

A second, retiring key can be configured for validation during a rotation, so a key can be replaced without invalidating every session in flight at the instant of the swap.

Deployment requirement (1.2.5). A production deployment must supply a signing key pair. The platform refuses to start in Production without one unless the operator explicitly opts out as a temporary migration measure, and warns whenever it falls back to the older shared-secret scheme. See the platform Configuration Reference for how to generate and rotate the key.

Operational Importance

This area is important because it protects the administrative surface of the platform.

From a functional standpoint, it ensures that:

only valid users can access portal features
higher-risk access can be protected by MFA
users can maintain their own access hygiene
operations teams can respond to suspicious or unwanted sessions
each account's permitted sign-in methods are enforced consistently across both local and external authentication paths

The full platformfunctional reference.