Account Management

The Account Management portal gives users a policy-aware place to maintain their authentication and recovery methods. Keeping these journeys inside ProAuth prevents relying applications from implementing credential rules, recovery checks, or WebAuthn ceremonies inconsistently.

The portal supports UserStore login passkeys, primary recovery methods, verified security contacts, password lifecycle, passkey MFA, identity proof, password changes, and tenant application sessions. Availability and permitted actions are determined by the effective server policy; the browser does not calculate readiness itself.

Administrators planning UserStore login-passkey policy should start with UserStore passkeys. Operational recovery and incident-response guidance is in Passkey security operations. The broader lifecycle is described in UserStore enterprise hardening.

Overview

ProAuth provides a dedicated pipeline at /account/security that authenticates users via a full OpenID Connect flow (Authorization Code + PKCE) before granting access to the management interface. This ensures a proper authenticated session regardless of how the user navigates to the portal.

The portal automatically adapts to the user's identity provider type:

• UserStore users see policy-allowed login-passkey, recovery, password, and MFA-passkey functions.
• Federated IDP users such as Google or Microsoft Entra ID users see MFA-passkey management when configured. Their primary credentials remain managed by the federated provider.

Accessing the Portal

Users can access the Account Management portal via:

https://<proauth-domain>/account/security?tenantid=<tenant-id>&idpinstanceid=<idp-instance-id>

Both tenantid and idpinstanceid query parameters are required. They identify the tenant and identity provider context for the user's session.

After a successful account management sign-in, ProAuth stores the tenant and identity provider context in a protected, HTTPS-only browser cookie scoped to /account/security. This cookie is used only as a routing hint for future re-authentication when a user returns to a bookmarked account management section such as /account/security/passkeys. It does not authorize access by itself; after sign-in, ProAuth still validates the authenticated user's tenant claim and federated identity before rendering account data.

If a request has neither the required query parameters nor a valid remembered context cookie, ProAuth shows a friendly recovery page instead of starting an ambiguous sign-in flow. Users should open account management from the application where they signed in, or sign in to the application again and use its account management link.

Access Methods

1. Login page link: The UserStore login page can include an "Account Management" link that opens the portal in a new browser tab.

2. ID token claim: ProAuth includes a pa_account_management_url claim in ID tokens and the UserInfo endpoint response. Client applications can use this claim to provide a direct link to the portal.

{
  "pa_account_management_url": "https://login.example.com/account/security?tenantid=...&idpinstanceid=..."
}

Login Page Link Visibility

The UserStore IDP instance option AccountManagementLinkVisibility controls whether the login page shows the Account Management link:

Value	Behavior
auto	Shows the link when passkeys are enabled. This is the default and preserves the previous passkey-driven behavior.
enabled	Always shows the link.
disabled	Hides the link.

Authentication Flow

When a user accesses the portal, ProAuth initiates an OIDC authentication flow against itself:

INFO

The Account Management pipeline uses a dedicated system client application ("ProAuth Account Management") that is auto-provisioned during startup. This client uses PKCE and does not require a client secret.

Login passkey management

This area is available only to UserStore users. Login passkeys are primary authenticators stored in the UserStore database. User-verification behavior, accepted authenticator classes, attestation, and other requirements come from the UserStore IDP's effective policy.

Features

• View credentials — See the display name, creation and last-use dates, sync/backup state, maturation, compliance, and availability reported by the server.
• Register a passkey — Add a security key, platform authenticator such as Windows Hello, Touch ID, or Face ID, or a synced passkey when policy permits it.
• Rename a passkey — Give a credential a recognizable name without changing its cryptographic identity.
• Replace a passkey — Register and, where required, mature a replacement before deleting the old credential.
• Delete a passkey — Remove a selected credential after policy-compliant reauthentication. The final usable credential cannot be deleted through self-service.
• Review readiness — See the exact server-provided reasons that block enrollment completion or password removal.
• Manage recovery — Verify security contacts and rotate primary recovery codes independently from MFA recovery codes.
• Manage password lifecycle — Request or cancel password removal when the UserStore policy permits it.
• Complete restricted recovery — Bind a replacement passkey after satisfying an allowed recovery or initial-enrollment route.

WARNING

Deleting a passkey is irreversible. ProAuth always blocks self-service deletion of the final usable passkey and guides the user through replacement. An administrator can still revoke the final credential when compromise is confirmed; the user then enters restricted recovery.

Recovery readiness

Readiness is more than the number of credentials. The portal displays blocking reasons from the v2 UserStore API, which can include credential maturation, compliance, diversity, verified-contact count, recovery-route availability, authentication age, binding lineage, or notification readiness.

Do not interpret a registered but held, revoked, non-compliant, or immature credential as a usable recovery method.

Security contacts

Security contacts are separate from ordinary profile fields. A contact contributes to readiness only after verification and while it remains non-revoked. Changing or removing a contact can immediately change password-removal readiness.

Verification secrets are never returned by administration read APIs. Where a UserStore migration backfills a confirmed email address, ProAuth records migration provenance; an unconfirmed email address is not treated as verified.

Primary recovery codes

Primary recovery codes recover UserStore primary authentication. They are not MFA recovery codes. A rotated set is displayed once, returned with no-store response semantics, and stored by ProAuth only as hashes. Rotating a set invalidates all previous unused codes.

Users should store recovery codes separately from the device or cloud account that stores their passkeys.

Password removal

When the policy is UserRemovable, the portal permits the user to request removal only after readiness succeeds and the current authentication evidence satisfies the binding policy. RemoveWhenReady schedules the same transition under policy control. During a configured grace period the user can see the pending state and cancel where permitted.

At commit, ProAuth evaluates readiness again. A successful commit permanently clears the password hash, password-reset material, and password-expiry state. Removing a passkey later does not restore the old password.

Restricted enrollment and recovery

A user with EnrollmentRequired or RecoveryRequired can satisfy one named route allowed by policy. Successful proof creates a short-lived restricted session. This session cannot complete normal OIDC sign-in; it can only bind a new policy-compliant primary passkey. Completion invalidates pre-recovery sessions, renewable grants, and one-time recovery artifacts.

Storage

Login passkeys, security contacts, recovery artifacts, and authentication state are stored in the UserStore database associated with the user. Secrets such as recovery codes and TAPs are never stored in recoverable plaintext.

MFA passkey management

This area is available to UserStore and federated users associated with a Passkey MFA instance. These credentials provide a second factor and are governed separately from UserStore login passkeys.

Association Requirements

MFA passkey management is only available when the user is associated with at least one active Passkey two-factor instance through any of these relationships:

• Direct user assignment
• Client application assignment
• Tenant assignment
• IDP instance assignment

Features

Users can view, register, rename, and delete MFA passkeys. Login-passkey password-removal readiness, primary recovery contacts, and primary recovery codes do not apply to MFA credentials.

First Passkey Setup

The first MFA passkey can be registered during the MFA challenge flow. Subsequent passkeys should be managed through the Account Management portal.

Storage

MFA passkeys are stored in the ProAuth database (not the User Store database), in the ProAuthUserMfaFactor entity. This allows MFA passkeys to work with both User Store and federated identity providers.

Change password

This function is available only to UserStore users whose password policy permits a password and whose current password state is Active. Users provide their current password, and the replacement is validated against the IDP's password policy.

When password status is Absent, a passkey operation cannot recreate it. If PasskeyPasswordRecreationPolicy permits recreation, the user must complete the corresponding strong-authentication or recovery workflow first. Under Prohibited, the change-password function remains unavailable.

Profile and verified security contacts

The Profile page shows the identity proven by the current session, active and retired identity history, pending identity-replacement operations, and the user's verified security contacts.

For a UserStore user, the portal can add and verify an email contact, replace an existing verified contact, and remove a contact when recovery policy remains satisfied. Replacing a contact requires separate codes from the original and candidate addresses plus current policy-compliant authentication. The operation advances security state and revokes dependent sessions; changing a visible profile value is not a shortcut around this process.

See Verified security contacts for purposes, provenance, APIs, and operator guidance.

Identity replacement proof

When an administrator starts a provider-identity replacement, the Profile page presents separate Prove identity actions for the current and staged replacement identities. These are proof-only authentication ceremonies: they are bound to the exact replacement operation and cannot create an ordinary application session.

Both identities and any configured independent approvals must be complete before an operator can execute the replacement. The outward ProAuth subject remains stable and the former identity becomes retired history.

See Identity and session security.

Active application sessions

The Sessions page lists active stored token families for the authenticated tenant, grouped by client application. It shows issuance and expiry information, whether renewable state exists, and the token types without exposing token values.

Users can:

• sign out of one application, which writes a client-scoped reauthentication cutoff and revokes matching token state;
• sign out of all applications in the current tenant, which writes a tenant-scoped cutoff and revokes matching state.

An older SSO session cannot silently recreate access after the cutoff. Fresh policy-compliant authentication is required. “All applications” is tenant-scoped; it does not affect unrelated tenants associated with the same central user.

MFA settings

The MFA settings page summarizes enrolled factors and recovery posture. Passkey MFA remains managed through the passkey page. Verified primary-recovery contacts and login-passkey recovery are shown separately so a lower-assurance recovery route cannot silently replace a stronger factor.

View Customization

The Account Management portal uses customizable Liquid templates. All text labels use the ProAuth label system under the /accountmgmt content-path root, with account-management keys such as accountmgmt-* and account-change-password-*. Administrators can customize text and provide translations through the Management API.

The portal uses a dedicated _AccountLayout.liquid master template with a sidebar navigation, separate from the standard login _Layout.liquid.

Administration API

Administrators can manage user passkeys through the UserStore Administration API:

GET    /api/userstore/v2/{userstoreId}/administration/passkeycredential/user/{userId}
DELETE /api/userstore/v2/{userstoreId}/administration/passkeycredential/user/{userId}/{passkeyId}
GET    /api/userstore/v2/{userstoreId}/administration/passkey-security/users/{userId}
GET    /api/userstore/v2/{userstoreId}/administration/passkey-security/operations
POST   /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/temporary-access-pass-requests

INFO

Administrators can list and remove passkeys but cannot register new ones. Passkey registration requires the WebAuthn ceremony to execute on the user's device and browser.

AdminApp provides a UserStore-scoped Passkey security tab on each user for credential investigation, permanent compromise revocation, readiness, TAP administration, recovery state, and correlated history. System administrators also have a Security Operations workspace for maker-checker, recovery, TAP and history queues, with separate Migrations, Identity Operations, and global FIDO metadata trust destinations. These surfaces use only v2 APIs and render server decisions rather than duplicating passkey policy in the browser.

See Passkey security operations for the operator procedures and safety rules behind these endpoints.