Core Concepts: Administrative Sessions¶

Administrative Sessions provide controlled access for performing sensitive configuration changes in the Keyserver.
They enforce the “four-eyes principle” by requiring two or more administrators to authorize the session before any administrative actions can be executed.

This mechanism prevents unauthorized or unilateral configuration changes and ensures all administrative activity is transparent and auditable.

What Administrative Sessions Protect¶

Administrative Sessions are required for tasks such as:

• Creating or modifying roles
• Creating or modifying subjects
• Creating or revoking signing keys
• Changing key approval requirements for a key

These changes directly impact security boundaries and access control, so they must be protected with additional checks beyond simple authentication.

Why Administrative Sessions Exist¶

The goal is to:

• Prevent a single administrator from making sensitive changes
• Protect against compromised admin accounts
• Ensure a complete approval audit trail for administrative actions
• Reduce the risk of accidental misconfiguration
• Enforce policy even in small teams

Administrative Sessions act as a temporary "privilege window" that enables administrative actions only after proper authorization.

Administrative Session Lifecycle¶

An Administrative Session progresses through the following stages:

1. Creation¶

An administrator opens a new session via the Keyserver UI and provides:

• A session description (e.g., “Adding signing key for Product X”)
• Their own administrative credentials

At this point, the session is inactive until authorization requirements are met. As administrators implicitly authorizes themselves, sessions in test/dev systems will be active immediately as only 1 authorizers are required.

The description is permanently recorded in audit logs and helps approvers understand the purpose of the session. Also note that the Administration Session ID is logged in all audit entries and ties them together is the sessions. This Session ID can be used to search on allowing to see all audit entries for an entire session.

2. Authorization by Other Administrators¶

Other administrators with the appropriate roles are prompted to authorize the session.
Authorization is performed through the UI and requires no passwords or tokens beyond their normal login.

The number of required authorizers is defined during system provisioning.
Common configurations:

• Development phase: 1 authorizer (the administrator itself)
• Production phase: 2 or more authorizers (administrator plus one other)

Administrators implicitly authorizes themselves counting as one authorizer.

Once the configured number of approvals is reached, the session becomes active.

3. Performing Administrative Actions¶

While the session is active, the initiating administrator may perform all allowed administrative operations.

Examples include:

• Add, edit, or delete subjects and associate roles to subjects
• Add or modify roles
• Create, configure, or revoke keys
• Change approver requirements on keys

Only the administrator who owns the session can execute changes, even after another admin authorizes it.

4. Expiry or Closure¶

Administrative Sessions do not remain active indefinitely.
They may close due to:

• Manual closure by the session owner
• Automatic timeout after a configured duration
• Revocation by another authorizer

Once closed:

• No administrative actions can be taken
• A new session must be created to continue work
• All changes remain recorded in the audit log under session ID.

Revoking or Declining a Session¶

Before the session becomes active:

• Administrators may decline authorization
• The session cannot be used until the required approvals are collected
• The initiating administrator may modify or delete the session

After activation:

• The session may still be revoked, preventing further changes
• Completed changes remain in audit logs
• Additional actions require a new session

This ensures robust control over administrative privileges even after creation.

Auditing Administrative Sessions¶

Every session event is recorded:

• Session creation
• Authorization approvals
• Authorization revocations
• Session activation
• All administrative actions performed within the session
• Session closure or expiration

Audit logs include:

• Who authorized the session
• Who performed changes
• What changes were made
• Exact timestamps
• exact JSON payload for REST API call
• This produces a complete, tamper-resistant audit trail.

Key Differences from Operation Approvals¶

The two mechanisms are distinct but complementary.
Administrative Sessions protect configuration.
Operation approvals protect key usage.

Summary¶

• Administrative Sessions enforce multi-party authorization for sensitive configuration tasks.
• An admin creates the session with a description.
• Other admins authorize it until authorization count requirements are met.
• Only the session owner can perform administrative changes.
• Sessions expire automatically or can be closed manually.
• All activity is logged for auditing and compliance associated with session ID.

Administrative Sessions ensure that Keyserver configuration changes remain deliberate, transparent, and securely controlled.