locking.mdx

title	description
Session and Identity Locking	How to lock compromised users or agents

System administrators can disable a compromised user or Teleport Agent—or prevent access during cluster maintenance—by placing a lock on a session, user or host identity.

Teleport will reject new API requests and terminate active connections to SSH, application, database, desktop, and Kubernetes sessions matching the lock's target.

A lock can target the following objects or attributes:

• a Teleport user by the user's name
• a Teleport RBAC role by the role's name
• a Teleport trusted device by the device ID
• an MFA device by the device's UUID
• an OS/UNIX login
• a Teleport Agent by the Agent's server UUID (effectively unregistering it from the cluster)
• a Windows desktop by the desktop's name
• an Access Request by UUID

Prerequisites

(!docs/pages/includes/edition-prereqs-tabs.mdx!)

• (!docs/pages/includes/tctl.mdx!)

Step 1/2. Create a lock

You can create a new lock with the tctl lock command. Specify the lock target with one of the following options:

```code $ tctl lock --user=foo@example.com --message="Suspicious activity." --ttl=10h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ``` All users with assigned roles matching the target role will be locked. ```code $ tctl lock --role=contractor --message="All contractor access is disabled for 10h." --ttl=10h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ``` All connections initiated from a device matching the device ID will be locked. ```code $ tctl lock --device 9cdfc0ad-64b7-4d9c-9342-50e97f418ba0 --message="Compromised device" --ttl=48h Created a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686". ``` All connections initiated with per-session MFA matching the device ID will be locked. ```code $ tctl lock --mfa-device=d6c06a18-e147-4232-9dfe-6f83a28d5850 --message="All contractor access is disabled for 10h." --ttl=10h # Created a lock with name "d6c06a18-e147-4232-9dfe-6f83a28d5850". ``` All connections to the specified agent will be locked and the agent will be excluded from the Teleport cluster. ```code $ tctl lock --server-id=363256df-f78a-4d99-803c-bae19da9ede4 --message="The server running the Kubernetes Service and Database Service is under investigation." --ttl=10h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ``` All connections to the specified Windows Desktop will be locked. ```code $ tctl lock --windows-desktop=WIN-FMPFM5UF1SS-teleport-example-com --ttl=10h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ``` All connections using elevated privileges from the matching Access Request will be locked. ```code $ tctl lock --access-request=261e80c5-357b-4c43-9b67-40a6bc4c6e4d --ttl=24h # Created a lock with name "dc7cee9d-fe5e-4534-a90d-db770f0234a1". ```

If your user is missing a lock permission, you will get an error when creating a lock:

ERROR: access denied to perform action "create" on "lock"

Define a role locksmith:

kind: role
version: v5
metadata:
  name: locksmith
spec:
  allow:
    rules:
      - resources: [lock]
        verbs: [list, create, read, update, delete]

Create the role:

$ tctl create -f locksmith.yaml
# role 'locksmith' has been created

(!docs/pages/includes/create-role-using-web.mdx!)

(!docs/pages/includes/add-role-to-user.mdx role="locksmith"!)

With a lock in force, all established connections involving the lock's target get terminated while any new requests are rejected.

Errors returned and warnings logged in this situation feature a message of the form:

lock targeting User:"foo@example.com" is in force: Suspicious activity.

You can tweak the message returned to a user with `--message` parameter:

$ tctl lock --user=foo@example.com --message="Please come back tomorrow." --ttl=24h

Note that without specifying `--ttl` or `--expires`, the created lock remains in force until explicitly removed with `tctl rm`. Refer to `tctl lock --help` for the list of all supported parameters.

Under the hood, tctl lock creates a resource:

kind: lock
version: v2
metadata:
  name: dc7cee9d-fe5e-4534-a90d-db770f0234a1
spec:
  target:
    user: foo@example.com
  message: "Suspicious activity."
  expires: "2021-08-14T22:27:00Z"  # RFC3339 format

The kind: lock resources can also be created and updated using tctl create as per usual. See the Admin Guide for more details.

Step 2/2. List and delete active locks

Use tctl get command to list all active locks:

$ tctl get locks

Delete a lock resource:

$ tctl rm locks/24679348-baff-4987-a2cd-e820ab7f9d2b
lock "24679348-baff-4987-a2cd-e820ab7f9d2b" has been deleted

Deleting a lock will allow new sessions or host connections.

Next steps: Locking modes

If a Teleport Node or Proxy Service cannot properly synchronize its local lock view with the backend, there is a decision to be made about whether to rely on the last known locks. This decision strategy is encoded as one of the two modes:

• strict mode causes all interactions to be terminated when the locks are not guaranteed to be up to date
• best_effort mode keeps relying on the most recent locks

The cluster-wide mode defaults to best_effort. You can set up the default locking mode via API or CLI using a cluster_auth_preference resource or static configuration file.

If your Auth Service configuration (/etc/teleport.yaml by default) contains an auth_service.authentication section, edit the Teleport configuration file to contain the following:

auth_service:
    authentication:
        locking_mode: best_effort

Restart or redeploy the Auth Service for the change to take effect.

If not, edit your cluster authentication preference resource:

$ tctl edit cap

Adjust the file in your editor to include the following:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  locking_mode: best_effort
version: v2

Save and close your editor to apply your changes.

The cluster-wide mode defaults to best_effort. You can set up the default locking mode via API or CLI using a cluster_auth_preference resource:

$ tctl edit cap

Adjust the file in your editor to include the following:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  locking_mode: best_effort
version: v2

Save and close your editor to apply your changes.

It is also possible to configure the locking mode for a particular role:

kind: role
version: v5
metadata:
    name: example-role-with-strict-locking
spec:
    options:
       lock: strict

When none of the roles involved in an interaction specify the mode or when there is no user involved, the mode is taken from the cluster-wide setting.

With multiple potentially conflicting locking modes (the cluster-wide default and the individual per-role settings) a single occurrence of strict suffices for the local lock view to become evaluated strictly.