Revoking Access

A Lock blocks a target cluster-wide as soon as Auth propagates it. Locks are independent of certificate TTL: a user whose certificate is still valid is blocked immediately once a matching lock is in force.

Locks do not delete the SSO identity or rotate the cluster CA. For CA rotation after a suspected full compromise, see CA Rotation.

TL;DR

Lock a user:

Terminal

alma create lock --target-user=<name> --message="Incident IR-42"

Set an automatic expiry:

Terminal

alma create lock --target-user=<name> --lock-ttl=4h --message="Pending review"

List active locks:

Terminal

alma get lock

Capture the lock details for the incident record:

Terminal

alma get lock/<name> -o yaml

Remove a lock:

Terminal

alma delete lock/<name>

What locks do and do not do

Locks do:

• Block new certificate issuance, session starts, and API operations for the matched target.
• Take effect as each Proxy and agent receives the lock, typically within seconds over a healthy Auth connection. The locking mode governs access during an Auth disconnection. In strict mode, services deny access after more than five minutes without a successful lock refresh. In bestEffort mode, services continue enforcing the cached lock set.
• Terminate monitored connections when their service receives a matching lock, without waiting for the user to run another command.

Locks do not:

• Delete the user's SSO identity or OIDCConnector mapping.
• Revoke certificates that have already been issued. The lock intercepts them at use time.
• Rotate the cluster CA. Use CA Rotation when certificates may have been exfiltrated and the CA itself must be replaced.

Revoke access granted outside AlmaForge, such as direct target credentials, in the system that grants it.

Lock targets

Each flag scopes the lock to a different target type. A lock matches any session or operation whose principal matches at least one target.

Target	Flag	When to use
User	--target-user=<name>	Block a specific SSO-mapped user by their cluster username. Use this first during an incident.
Role	--role=<name>	Block everyone with a given role. Useful when a role assignment was over-provisioned or a group is compromised.
Login (UNIX)	--target-login=<name>	Block a specific UNIX login name on SSH targets regardless of which user holds it.
Server	--server-id=<uuid>	Block access to a specific server. Use when the node itself is under investigation.
Access request	--access-request=<uuid>	Revoke an approved access request before the elevated session expires.

You can combine --message with any target flag to set a reason string shown to the locked-out user. Keep the message factual and incident-safe because the denial includes the matched target and the message text.

Issue a lock

Lock a user

Terminal

alma create lock --target-user=alice --message="Incident IR-42: investigation in progress"Created a lock with name "7f3d8a2c-...".

Lock a role

Terminal

alma create lock --role=db-admin --message="Role over-provisioned, pending audit"

Lock a server

Terminal

alma create lock --server-id=<node-uuid> --message="Node under investigation"

To find the server UUID:

Terminal

alma get node

Lock TTL

By default a lock has no expiry and must be removed manually.

Use --lock-ttl to set a duration from now:

Terminal

alma create lock --target-user=alice --lock-ttl=8h --message="Pending HR review"

Use --expires to set an absolute RFC3339 time:

Terminal

alma create lock --target-user=alice --expires=2026-07-01T09:00:00Z --message="Pending HR review"

--lock-ttl and --expires are mutually exclusive. When neither is set, the lock remains until you delete it with alma delete lock/<name>.

How locks propagate

Auth holds the authoritative lock set. Proxies and agents subscribe to Auth's event stream through a lock watcher. When you create a lock, Auth notifies all watchers immediately over that stream.

Check the cluster locking mode:

Terminal

alma get authconfig

The default locking mode is bestEffort. Set spec.lockingMode on the cluster AuthConfig resource named cluster to strict when you want stale lock views to fail closed, then apply the updated resource with alma apply -f <authconfig.yaml>.

• Under normal conditions propagation is near-instant.
• If a watcher loses its Auth connection, it retains the last known lock set. The watcher marks itself stale after 5 minutes without a successful refresh. In strict locking mode, a stale watcher denies access. In bestEffort mode, stale watchers allow access using the cached view.
• A connection monitor terminates its connection when it receives a matching lock event. Other access paths check locks when authorizing a new request or connection.

Confirm the lock in audit

Creating a lock emits a LockCreate event in the audit log. Deleting a lock emits a LockDelete event.

Query your audit sink or SIEM for spec.type=LockCreate (code=TLK00I) and spec.type=LockDelete (code=TLK01I). Bound the query to the incident window so that older stale locks do not look like new revocations.

Each LockCreate event records spec.type, spec.code, spec.timestamp, the lock's name in spec.objectRef.name, who made it in spec.actor.name, and what it locks in spec.lockCreate.target. The lock resource records message, expiresAt, createdAt, and createdBy, so preserve both the audit event and alma get lock/<name> -o yaml output in the incident record.

Remove a lock

List locks to find the name:

Terminal

alma get lock

Delete by name:

Terminal

alma delete lock/<name>

Deletion emits a LockDelete event in the audit log.

Cleanup policy

Locks without an expiry remain active until deleted. Review active locks on a regular operations cadence:

Terminal

alma get lock

Track the active lock count in your operations dashboard or incident review report. A non-expiring lock should have an owner, an incident reference, and a cleanup decision.

When to rotate the CA instead

A lock blocks access at use time but does not invalidate issued certificates. If you suspect that a certificate was exfiltrated and could be used outside the cluster (for example, against a target that accepts the cluster CA directly), a lock alone is not sufficient.

Rotate the CA to force all certificate holders to re-authenticate through your IdP. See CA Rotation.

Incident-response runbook

Use this sequence for a suspected account compromise.

1. Lock the user immediately

Terminal

alma create lock --target-user=<name> --message="IR-<number>: account suspected compromised"

2. Check for active access requests

Terminal

alma request ls

Revoke any approved requests held by the user:

Terminal

alma create lock --access-request=<uuid> --message="IR-<number>: revoked pending investigation"

3. Identify and lock any over-provisioned roles

If the incident involves a role with broader access than expected, lock the role before you revise the OIDCConnector claim mapping:

Terminal

alma create lock --role=<role-name> --message="IR-<number>: role locked pending review"

Keep the role lock in force while you remove the IdP group mapping from the OIDCConnector. Verify the stored connector no longer maps that group:

Terminal

alma get oidcconnector/<name> -o yaml

Then test a fresh login through the normal Proxy path. Only delete the role lock after the fresh login no longer receives the role and previously issued credentials carrying it have expired or are blocked by another applicable lock. Removing the mapping does not rewrite existing certificates.

4. Pull recent session recordings

List recordings for the incident window:

Terminal

alma recording ls --last=24h --limit=100

Replay any relevant session:

Terminal

alma recording play <session-id>

The recording list is time-bounded, not user-filtered. Correlate session IDs with SessionStart and SessionEnd audit events for the user in your audit sink.

5. Rotate the CA for full compromise

If certificates may have left the cluster boundary, rotate the CA after the account is locked. See CA Rotation for the step-by-step procedure.

6. Confirm and record

Verify the lock is in place:

Terminal

alma get lock

Verify the audit trail in your audit sink or SIEM for the incident window. Capture both LockCreate and LockDelete events when a temporary lock has already been removed.

Record the lock names, incident reference, creation time, operator, session IDs, and recording locations in your incident log.

References

• Break-Glass Access - emergency CLI access when normal sign-in is unavailable.
• CA Rotation - rotate the cluster CA after a full compromise.
• RBAC - role and OIDCConnector configuration.
• CLI Reference - lock, resource, and recording commands.
• Audit Reference - event catalog and recorded session reference.