Skip to content

Administrative Sessions

An administrative session is a time-limited, multi-party authorization that must be active before any configuration change can be made in the Keyserver. A session is required to create or modify roles, subjects, and signing keys.


Why administrative sessions exist

A single compromised or careless admin account should not be able to change access control on its own. Administrative sessions require the configured number of authorizers before any change takes effect.

Sessions:

  • Become active only when the required number of authorizers have authorized them
  • Tie every change made under them to the session ID in the audit log
  • Expire automatically, limiting the window of elevated privilege
  • Require every change to be made under a described session

Production authorizer count

The number of authorizers a session requires is defined in the deployment configuration. A deployment that requires at least two distinct authorizers provides four-eyes control; a deployment that requires one does not. While a session is open, the Admin page shows the count as "Authorizers ( N of required M):".

Trial deployments

Trial deployments require one authorizer, so a trial session is active as soon as it is created.


Session lifecycle

stateDiagram-v2
    [*] --> Created : Admin creates session<br/>with description

    Created --> Active : Required authorizers<br/>have authorized<br/>(self counts as 1)

    Active --> Created : An authorizer revokes,<br/>count falls below<br/>the required number

    Active --> Closed : Session owner revokes<br/>or timeout expires

    Created --> Abandoned : Admin cancels<br/>before activation

    Closed --> [*]
    Abandoned --> [*]

Diagram: Admin creates session with description; Required authorizers have authorized (self counts as 1); An authorizer revokes, count falls below the required number; Session owner revokes or timeout expires; Admin cancels before activation

1. Creation

To start an administrative session, click the Admin tab, enter a description of the changes you intend to make (for example, "Adding FW key for Product X release"), and click Create. The session stays inactive, with no administrative actions possible, until the required number of authorizers have authorized it. You count as one, so where one authorizer is required, as on the trial environment, the session is active at once.

The description is recorded in the audit log. Authorizers and auditors use it to understand why the session was opened.

2. Authorization

Other administrators whose role carries the authorizer Nature can see the pending session and authorize it. The session owner counts as one authorizer.

Once the required number of authorizers is reached, the session becomes active.

3. Making changes

While the session is active, the owning administrator can:

  • Create, edit, or delete subjects
  • Create, edit, or delete roles and their permissions
  • Create, edit, or revoke signing keys
  • Change the Required Approvers count on keys

Only the session owner can make changes, even after another admin has authorized the session.

Signing keys cannot be deleted, only revoked. Revoking a key sets its status to FAILED, keeps its record for audit, and removes every role permission that referenced it. A ROOT key cannot be revoked while it still has CA or FW keys beneath it that are not revoked.

4. Closure

Sessions close when:

  • The owner revokes the session (recommended when finished)
  • The configured validity window expires

Once a session is closed, no further changes are possible. A new session must be created.

If another authorizer revokes their authorization and the count falls below the required number, the session stays open but reverts to pending. Changes are refused until another authorizer authorizes it. The session owner cannot revoke their own authorization; to end the session, the owner revokes the session itself.


Audit trail

Every action taken under an administrative session is recorded in the audit log with the session ID in the adminsessionid field. Filter by it to see every change made in one session. See Monitor and Filter the Audit Log and Audit Coverage Reference.

Events recorded:

Event What is logged
Session creation Creator, description, timestamp
Authorization Each authorizer's identity and timestamp
Administrative action Full request body, the field modified, timestamp
Session closure How and when the session ended

Comparison with operation approvals

Both administrative sessions and operation approvals use multi-party authorization, but they protect different things:

Administrative Session Operation Approval
Protects System configuration (keys, roles, subjects) Key usage (signing, certificate issuance)
Requested by Administrator Operation creator (CI/CD pipeline)
Authorized by Other administrators Human approvers
Scope All changes within the session One specific operation
Duration Minutes, closed manually or by timeout Set by validms on the operation
Audit field adminsessionid operationid