Teleport
Session and Identity Locking
- Edge version
- Version 17.x
- Version 16.x
- Version 15.x
- Older Versions
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
-
A running Teleport cluster version 16.4.10 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.4.10
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
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 initiated from a device matching the device ID will be locked.
tctl lock --device 9cdfc0ad-64b7-4d9c-9342-50e97f418ba0 --message="Compromised device" --ttl=48hCreated a lock with name "5444970a-39a0-4814-968d-e58b4a8fa686".
All connections initiated 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 agent will be locked and the agent will be excluded from the Teleport cluster.
tctl lock --server-id=363256df-f78a-4d99-803c-bae19da9ede4 --message="The server running the Kubernetes Service and Database Service 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 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.yamlrole 'locksmith' has been created
Assign the locksmith
role to your Teleport user by running the appropriate
commands for your authentication provider:
-
Retrieve your local user's roles as a comma-separated list:
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') -
Edit your local user to add the new role:
tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},locksmith" -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Open your
github
authentication connector in a text editor:tctl edit github/github -
Edit the
github
connector, addinglocksmith
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - locksmith
-
Apply your changes by saving closing the file in your editor.
-
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addinglocksmith
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - locksmith
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addinglocksmith
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - locksmith
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
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.
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.