Skip to content

Latest commit

 

History

History
251 lines (183 loc) · 8.99 KB

0009-locking.md

File metadata and controls

251 lines (183 loc) · 8.99 KB
authors state
Andrej Tokarčík ([email protected])
draft

RFD 9 - Locking

What

This RFD provides a locking mechanism to restrict access to a Teleport environment. When such a lock is in force, all interactions matching the lock's conditions are either terminated or prevented.

Why

Security teams require greater control over interactions (sessions, connections, generation of certificates) in order to be able to:

  • lock out the team during maintenance windows,
  • terminate and disable further access for users, even if in possession of a valid Teleport certificate,
  • achieve FedRAMP/NIST compliance.

Details

Lock resource

A new resource named Lock with the following specification is introduced:

message LockSpecV2 {
    // Target describes the set of interactions that the lock applies to.
    LockTarget Target;

    // Message is the message displayed to locked-out users.
    string Message;

    // Expires if set specifies TTL for the lock.
    google.protobuf.Timestamp Expires;
}

// LockTarget lists the attributes of interactions to be disabled.
// The attributes are interpreted/matched qua simple names,
// with no support for wildcards or regular expressions.
message LockTarget {
    // User specifies the name of a Teleport user.
    string User;

    // Role specifies the name of an RBAC role known to the root cluster.
    // In remote clusters, this constraint is evaluated with both original
    // and mapped roles.
    string Role;

    // Login specifies the name of a local UNIX user.
    string Login;

    // Node specifies the name or UUID of a node.
    // A matching node is also prevented from heartbeating to the auth server.
    string Node;

    // MFADevice specifies the ID of an MFA device recorded in a user certificate.
    string MFADevice;
}

In most cases LockTarget should list just a single attribute. (It would be preferable to define it as a oneof, however setting a custom jsontag for oneof is not supported by gogoproto.)

Note that Lock is not a singleton resource: when there are multiple Locks stored (and in force), it suffices for an interaction to be matched by any one of the locks to be terminated/disabled.

Relation to User.Status

There already exists a field of User resource that is used to capture a user lock in connection with failed Web UI login attempts.

This Status field and its LoginStatus definition are superseded by Lock. All of its use cases should be converted to Lock.

The Lock approach allows to specify locks for entities that are only yet to exist or exist merely transiently (such as SSO user objects). It could also help with alleviating the load associated with caching User resources.

tctl support

Lock resources can be managed using tctl [get|create|rm]. In this way, it is possible to update or remove a lock after it has been created.

There will be a special tctl lock helper provided, to facilitate creation of new Locks, see Scenarios below.

Propagation within a Teleport cluster

Instead of relying on the main cache system for lock propagation, every cluster component (Teleport process) will be initialized with its own local lock-specific watcher. Such a LockWatcher will be used to report connection/staleness issues to the caller while attempting to reestablishing a connection to the auth server in the background (similar to as already performed by services.ProxyWatcher).

It will be parametrized by a duration that defines the maximum failure period after which the data are to be considered stale. If this tolerance interval is exceeded while performing such reloads, the fallback mode described below is employed until a healthy connection is reestablished.

LockWatcher will keep a single connection to the auth server for the purpose of monitoring the Lock resources. It will in turn allow derived watchers ("lock watcher subscriptions") which can be configured by a list of LockTargets.

Fallback mode

If LockWatcher returns an error indicating stale data, there is a decision to be made about whether to rely on the last known locks. There will be two levels on which to determine this decision.

  1. If a lockable transaction involves a user and the user's certificate has an extension named teleport-lock-fallback, the transaction is locked out based on the extension's value which comes from the user's RBAC role:
spec:
   options:
       # In strict mode, if the locks are not up to date, all matching interactions will be terminated.
       # In best_effort mode, the most recent view of the locks will remain to be used.
       lock: [strict|best_effort]
  1. A LockFallback field is added to the ClusterAuthPreference resource. The new field configures the cluster-wide fallback mode that applies when a more specific hint is not available. It defaults to best_effort to retain backward compatibility with HA deployments.

Disable generating new certificates

No new user or host certificates matching a lock target should be generated while the lock is in force. An audit event should be emitted upon such an attempt.

A new lock check will be added to the generateUserCert and GenerateHostCert functions in lib/auth/auth.go.

Disable initiating new connections

Even if a locked-out user is already in a posinteraction of a valid Teleport certificate, they should be prevented from initiating a new session. This is covered by adding a check to auth.Authorize.

This restriction touches all the access proxies/servers supported by Teleport: SSH, k8s, app and DB. A lock in force will also block initiating sessions with the proxy web UI and sending requests to the Auth API (both gRPC and HTTP/JSON).

Terminate existing connections

Terminating an established session/connection due to a (freshly created) lock is similar to terminating an existing session due to certificate expiry. The support for the latter is covered by srv.Monitor. To add support for locks, srv.Monitor will be passed in a reference to LockWatcher associated with the Teleport instance.

The developed logic should work with every protocol that features "live sessions" in the proper sense and that makes use of srv.Monitor: SSH, k8s and DB.

Replication to leaf clusters

Lock resources are replicated from the root cluster to leaf clusters in a similar manner to how CAs are shared between trusted clusters (the periodicUpdateCertAuthorities routine), i.e. by periodically invoking a leaf cluster's API to replace the locks associated with the root cluster with the most recent set of locks active at the root cluster.

Lock resources received from the root cluster should be stored under a separate backend key namespace:

/locks/<clusterName>/<lockName>

Scenarios

Creating a permanent lock

$ tctl lock [email protected] --message="Suspicious activity."
Created a lock with ID "dc7cee9d-fe5e-4534-a90d-db770f0234a1".

This locks out [email protected] without automatic expiration. The lock can be lifted by tctl rm lock/dc7cee9d-fe5e-4534-a90d-db770f0234a1.

The above locking command would be equivalent to

tctl create <<EOF
kind: lock
metadata:
  name: dc7cee9d-fe5e-4534-a90d-db770f0234a1
spec:
  message: "Suspicious activity."
  target:
    user: [email protected]
version: v2
EOF

The showed YAML would also correspond to the output of tctl get lock/dc7cee9d-fe5e-4534-a90d-db770f0234a1.

Creating a lock with expiry

$ tctl lock --role=developers --message="Cluster maintenance." --expires-in=10h
Created a lock with ID "dc7cee9d-fe5e-4534-a90d-db770f0234a1".

This locks out users with the role developers for the next 10 hours.

Assuming the time at which the command is issued on 2021-06-14 at 12:27 UTC, the above locking command would be equivalent to both

tctl create <<EOF
kind: lock
metadata:
  name: dc7cee9d-fe5e-4534-a90d-db770f0234a1
spec:
  target:
    role: developers
  message: "Cluster maintenance."
  expires: "2021-06-14T22:27:00Z"   # RFC3339
version: v2
EOF

and

tctl lock --role=developers --message="Cluster maintenance." --expires="2021-06-14T22:27:00Z"

Generation of new user certificates prevented

Attempts to generate a new user certificate (tsh login, tctl auth sign) while a lock targeting role developers is in force will result in the following error:

ERROR: lock targeting Role:"developers" is in force (Cluster maintenance.)

SSH session with an already issued certificate prohibited

$ tsh ssh graviton-node
ERROR: ssh: rejected: administratively prohibited (lock targeting User:"andrej" is in force: Malicious behaviour.)

Live SSH session terminated

An informational message is printed before the connection is terminated:

Lock targeting Role:"developers" is in force: Cluster maintenance.
the connection was closed on the remote side on  15 Jun 21 10:43 CEST

Locking out a node

$ tctl lock --node=node-uuid

Locking out an MFA device ID

$ tctl lock --mfa-device=device-uuid