Teleport

Session and Identity Locking

Locking support was introduced in Teleport v7.1. To fully enforce the locks at all components, you should update all teleport binaries in your deployment.

System administrators can disable a compromised user, node 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, 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
an MFA device by the device's UUID
an OS/UNIX login
a Teleport node by the node's UUID (effectively unregistering it from the cluster)
a Windows desktop by the desktop's name
an access request by UUID

Prerequisites

Installed Teleport >= 8.0.7 or Teleport Cloud
Tctl admin tool >= 8.0.7

Verify that your Teleport client is connected:

$ tctl status

# Cluster  tele.example.com
# Version  8.0.7
# CA pin   sha256:sha-hash-here

To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:

$ tsh login --proxy=myinstance.teleport.sh
$ tctl status

Step 1/2. Create a lock

To create a new lock, one can run the tctl lock command:

tctl lock [email protected] --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.

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 initated with per-session MFA matching the device ID will be locked.

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 node will be locked.

tctl lock --node=363256df-f78a-4d99-803c-bae19da9ede4 --message="The node 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.

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.

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 error when creating a role:

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

Create a role locksmith:

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

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

And assign this role to a user. Re-login for this role to take effect.

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:"[email protected]" is in force: Suspicious activity.

Note

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

tctl lock [email protected] --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: [email protected]
  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 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 default locking mode via API or CLI using resource cluster_auth_preference or static configuration file:

Create a YAML file cap.yaml or get the existing file using tctl get cap

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

Create a resource:

tctl create -f cap.yaml
cluster auth preference has been updated

Edit the teleport.yaml of the Auth server:

auth_service:
    authentication:
        locking_mode: best_effort

Restart the auth server for the change to take effect.

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

kind: role
version: v4
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.

Have a suggestion or can’t find something?

IMPROVE THE DOCS