Skip to content

Administrative client access

The Admin API accepts tokens whose only audience is urn:openidentitystack:admin-api, with the ois.admin scope. Generic api, missing audiences, business audiences, and combined administrative/business audiences are rejected. Business access requires a separate token.

Entitlement and ceilings

Each administrative client needs an explicit grant to the reserved Admin resource, with separate delegated and machine permission ceilings. An ordinary client's scopes, role names, or resource mappings do not establish this entitlement. The reserved resource identity, scope, and openidentitystack permission namespace cannot be reassigned through ordinary resource configuration.

Delegated permissions are the intersection of the user's current permissions, the client's delegated ceiling, the Admin resource, and the issued token's permissions. Client credentials use only the approved machine ceiling. A machine identity does not inherit a user's roles. Both use canonical permission claims; alternate permissions, scope, scp, and role claims do not convey administrative authority.

Authorization reads the current resource projection for the request's authority revision. While that revision is unchanged, later requests in the same process reuse the projection for the same client, subject, and token permission ceiling. Current client approval, active status, subject authority, and ceiling continue to constrain previously issued tokens. Reducing a ceiling cannot be undone by refreshing a token. A refresh cannot gain permissions absent from its original token.

The request captures the shared authority revision before reading those permissions. Mutating use cases reuse that revision, so revoking a role, client, or ceiling after authorization and before persistence causes the authority fence to reject the stale mutation. Reload and review the operation after the resulting conflict.

Machine audit actors use client: followed by the complete client ID, including IDs already beginning with that prefix. This keeps a client named system or a human UUID distinct from background work and human users. Human actors retain their user UUID; unauthenticated background work retains system. Explicit administrative audit writes and automatic authority-change records use the same representation. Authorization and registry ownership continue to use their original principal identifiers.

Encoded audit actor identifiers longer than 128 characters use sha256: followed by the lowercase SHA-256 digest of the complete encoded UTF-8 identifier. Investigators can hash client: plus a known client ID to correlate its actions. The same representation is used in persisted audit entries and general audit logs. Literal actor identifiers beginning with sha256: are also hashed so they cannot impersonate a digest representation.

Authority withdrawal and operation

The first Admin API request started after a withdrawal commits uses current authority, including direct roles, group memberships and role mappings, active roles, explicit wildcard grants, local user status, client status, administrative entitlement, and the appropriate delegated or machine ceiling. The same bearer token loses the withdrawn permission without waiting for expiry or refreshing Management Web. /api/me returns the same evaluated permissions used to authorize that request. Read-only requests already in progress may complete using the authority evaluated for that request; mutations must also pass the captured authority revision fence before persistence.

The shared authority revision is the cache generation. It advances in the same transaction as a role, group, grant, credential, user-status, client, or administrative-resource change, so the next request evaluates that change immediately on every serving instance. The cache is process-local, keeps only the current revision, and has no time-to-live. Each request still reads the revision from the authoritative database and re-reads the administrative resource before reusing a decision. Asynchronously replicated permission reads are not supported. Deploy all instances before relying on next-request withdrawal. If the revision row or the administrative resource cannot be read, the request fails with a server error and does not use a cached decision or token claims. Restore database availability before retrying. Do not disable these checks to work around an outage.

Persisted changes to existing role permissions/status, role assignments, group memberships and role mappings, user status, and client status/scopes create AdministrativeAuthorityChanged audit records in the same database transaction. Deleting these authority-bearing entities is also recorded. Records contain the acting subject (or system for a non-HTTP operation), entity identifiers, operation, and an allowlist of changed field names. They contain no profile values, credentials, tokens, or arbitrary claim values. Entitlement and resource-ceiling workflows retain their transaction-bound resource audit records; protected human approval keeps its separate intent/outcome audit.

A rejected save or transaction rollback commits neither the authority change nor its authority audit. An audit write failure therefore fails the authority update. Check committed state after an ambiguous response before retrying; successful retries create a record for the committed operation. Changes made outside the application's persistence boundary require the operator to provide an equivalent transaction-bound audit. These guarantees apply to the Admin API; independently validating business resources retain the token-lifetime limitations described in the resource migration guidance.

Operator workflow

Open the application's Administrative access tab. Enter separate delegated and machine ceilings using one platform permission per line. Use concrete permissions for routine integrations; * includes current and future platform permissions. Clear both ceilings to withdraw administrative access.

Initial approval and expansion require an existing explicit all-permissions holder, actual human authentication within five minutes, acknowledgement, and durable audit. Stale authentication starts a fresh sign-in and requires the operator to repeat the operation. Cancellation does not submit an approved retry. Reductions preserve existing endpoint permissions and do not require a new approval.

OAuth settings, new credentials, and re-enabling an entitled client use the same human approval boundary because these operations could transfer the client's access. Ordinary application edits cannot create an entitlement. Metadata changes, disabling, credential revocation, and entitlement reduction remain available under their existing permissions.

The API exposes GET and PUT /api/admin/applications/{id}/administrative-access. The response contains approved, delegatedPermissions, applicationPermissions, and nullable revision. PUT supplies both ceilings and expectedRevision; use null for a new entitlement. A stale revision returns 409. Approval failures return the 403 Problem Details codes described in unrestricted administrative approval.

Management Web preparation

The migrator prepares only the fixed management-web-client registration, with ois.admin, authorization code plus PKCE, and independently reviewed redirect URIs configured under OpenIddict:Clients:ManagementWeb. Preparation alone does not approve it.

For controlled initial deployment, explicitly set Seed:AdministrativeAccess:BootstrapManagementWeb=true for one migrator run. This flag is off by default. It grants the known Management Web registration a delegated * ceiling and no machine permissions. The bootstrap validates the existing public-client identity, PKCE, allowed grant types, absence of credentials, and exact configured redirect/post-logout URI sets. It refuses mismatches and disabled registrations. Remove the flag after successful bootstrap.

An existing grant is never expanded or restored by bootstrap reruns, including an empty grant retained after withdrawal. The bootstrap does not approve ordinary registrations or provide a runtime recovery endpoint. Other integrations must receive explicit human approval.

Every preparation run validates the existing registration against the complete reviewed configuration before protocol projection, even with bootstrap disabled or an existing grant. Redirects, logout redirects, scopes, grant types, public SPA profile, PKCE, consent policy, active status, and absence of credentials must match. Mismatches fail without changing the client or grant; reconcile them through the approved administrative workflow, including an intentionally removed ois.admin scope, before rerunning preparation. New registrations are persisted before projection; existing registrations are never silently repaired.

Before enabling the boundary, preserve and test an independently accessible emergency human administrator and review the Management Web deployment configuration. Apply resource persistence migrations, prepare registrations, perform the controlled bootstrap if required, approve other integrations, as described in ADR 0005. Obtain administrative tokens with the dedicated audience and approved ceilings. There is no generic-api compatibility mode. Downgrading reopens the old administrative boundary.

Browser verification

The following screenshots show the approval workflow exercised by the real-browser test against an isolated PostgreSQL database. Cancelling approval leaves the client unapproved; acknowledgement enables the requested scoped grant.

Administrative approval requires explicit acknowledgement

Approved machine ceiling with no delegated authority