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 or 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
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.7.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
See Installation for details.
-
A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.7, which you can download by visiting the customer portal.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
-
A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.8. To download these tools, visit the Downloads page.tctl versionTeleport v9.3.8 go1.17
tsh versionTeleport v9.3.8 go1.17
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 9.3.7
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 9.3.8
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
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:
tctl lock [email protected] --message="Suspicious activity." --ttl=10hCreated 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=10hCreated 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=10hCreated 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=10hCreated 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=10hCreated 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=24hCreated 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: v5
metadata:
name: locksmith
spec:
allow:
rules:
- resources: [lock]
verbs: [list, create, read, update, delete]
tctl create -f locksmith.yamlrole 'locksmith' has been created
And assign this role to a user. The user must log in again 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.
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-e820ab7f9d2block "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 datebest_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:
Create a YAML file called 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.yamlcluster auth preference has been updated
Edit /etc/teleport.yaml
on 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: 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.