Fork me on GitHub

Teleport Access Controls Reference


This document describes Teleport Roles, Role Options, and Role-Based Access Control (RBAC) for Teleport Access Controls.


A Teleport role works by having two lists of rules: allow rules and deny rules. When declaring access rules, keep in mind the following:

  • Everything is denied by default.
  • Deny rules get evaluated first and take priority.

A rule consists of two parts: the resources and verbs. Here's an example of an allow rule describing a list verb applied to the SSH sessions resource. It means "allow users of this role to see a list of active SSH sessions".

  - resources: [session]
    verbs: [list]

If this rule was declared in the deny section of a role definition, it would prohibit users from getting a list of trusted clusters and sessions. You can see all of the available resources and verbs under the allow section in the example role configuration below.

To manage cluster roles, a Teleport administrator can use the Web UI or the command line using tctl resource commands. To see the list of roles in a Teleport cluster, an administrator can execute:

tctl get roles

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

A role definition looks like this:

kind: role
version: v4
  name: example
  # SSH options used for user sessions with default values:
    # max_session_ttl defines the TTL (time to live) of SSH certificates
    # issued to the users with this role.
    max_session_ttl: 8h
    # forward_agent controls whether SSH agent forwarding is allowed
    forward_agent: true
    # port_forwarding controls whether TCP port forwarding is allowed
    port_forwarding: true
    # client_idle_timeout determines if SSH sessions to cluster nodes are forcefully
    # terminated after no activity from a client (idle client). it overrides the
    # global cluster setting. examples: "30m", "1h" or "1h30m"
    client_idle_timeout: never
    # Determines if the clients will be forcefully disconnected when their
    # certificates expire in the middle of an active SSH session.
    # It overrides the global cluster setting.
    disconnect_expired_cert: no
    # Optional: max_connections Per-user limit of concurrent sessions within a
    # cluster.
    max_connections: 2
    # Optional: max_sessions total number of session channels that can be established
    # across a single connection. 10 will match OpenSSH default behavior.
    max_sessions: 10
    # permit_x11_forwarding allows users to use X11 forwarding with openssh clients and servers through the proxy
    permit_x11_forwarding: true

  # The allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. By default, nothing is allowed.
    # The logins array defines the OS/UNIX logins a user is allowed to use.
    # a few special variables are supported here (see below)
    logins: [root, '{{internal.logins}}']
    # Windows logins a user is allowed to use for desktop sessions.
    windows_desktop_logins: [Administrator, '{{internal.logins}}']
    # If kubernetes integration is enabled, this setting configures which 
    # kubernetes groups the users of this role will be assigned to.
    # Note that you can refer to a SAML/OIDC trait via the "external" property bag.
    # This allows you to specify Kubernetes group membership in an identity manager:
    kubernetes_groups: ["system:masters", "{{external.trait_name}}"]]

    # List of node labels a user will be allowed to connect to:
      # A user can only connect to a node marked with 'test' label:
      'environment': 'test'
      # The wildcard ('*') means "any node"
      '*': '*'
      # Labels can be specified as a list:
      'environment': ['test', 'staging']
      # Regular expressions are also supported, for example, the equivalent
      # of the list example above can be expressed as:
      'environment': '^test|staging$'

      # A user can only access prod enviroments
      'env': 'prod'
      # User can access any region in us-west, e.g us-west-1, us-west-2
      'region': 'us-west-*'
      'cluster_name': '^us.*\.example\.com$'

    # Defines roles that this user can request.
    # Needed for teleport's access request workflow
      - dba

    # List of allow-rules. See below for more information.
    - resources: [role]
      verbs: [list, create, read, update, delete]
    - resources: [auth_connector]
      verbs: [list, create, read, update, delete]
    - resources: [session]
      verbs: [list, read]
    - resources: [trusted_cluster]
      verbs: [list, create, read, update, delete]
    - resources: [event]
      verbs: [list, read]
    - resources: [user]
      verbs: [list,create,read,update,delete]
    - resources: [token]
      verbs: [list,create,read,update,delete]

  # The deny section uses the identical format as the 'allow' section.
  # The deny rules always override allow rules.
  deny: {}

The following variables can be used with logins and windows_desktop_logins fields:

{{internal.logins}}Substituted with "allowed logins" parameter used in tctl users add [user] <allowed logins> command. This applies only to users stored in Teleport's own local database.
{{}}Substituted with a value from an external SSO provider. If using SAML, this will be expanded with "xyz" assertion value. For OIDC, this will be expanded a value of "xyz" claim.

Both variables above are there to deliver the same benefit: they allow Teleport administrators to define allowed OS logins via the user database, be it the local DB, or an identity manager behind a SAML or OIDC endpoint.

An example of a SAML assertion

Assuming you have the following SAML assertion attribute in your response:

<Attribute Name="">

... you can use the following format in your role:

   - '{{external[""]}}'

Role options

As shown above, a role can define certain restrictions on SSH sessions initiated by users. The table below documents the behavior of each option if multiple roles are assigned to a user.

OptionDescriptionMulti-role behavior
max_session_ttlMax. time to live (TTL) of a user's SSH certificatesThe shortest TTL wins
forward_agentAllow SSH agent forwardingLogical "OR" i.e. if any role allows agent forwarding, it's allowed
port_forwardingAllow TCP port forwardingLogical "OR" i.e. if any role allows port forwarding, it's allowed
client_idle_timeoutForcefully terminate active SSH sessions after an idle intervalThe shortest timeout value wins, i.e. the most restrictive value is selected
disconnect_expired_certForcefully terminate active SSH sessions when a client certificate expiresLogical "OR" i.e. evaluates to "yes" if at least one role requires session termination
max_connectionsLimit on how many active SSH sessions can be started via Teleport
max_sessionsTotal number of session channels which can be established across a single SSH connection via Teleport

Preset roles

Teleport provides several pre-defined roles out-of-the-box:

editorAllows editing of cluster configuration settings.
auditorAllows reading cluster events, audit logs, and playing back session records.
accessAllows access to cluster resources.

Teleport versions prior to 8.0 also included a default admin role. This role has been deprecated in favor of smaller, more fine-grained roles like the presets mentioned above.

Users installing a brand new Teleport cluster on version 8.0 or later will not see this admin role. Users who upgrade to Teleport 8 from an earlier version will continue to see the admin role, but are encouraged to migrate to roles that are more appropriately scoped.

Role versions

There are currently two supported role versions: v3 and v4. v4 roles are completely backwards-compatible with v3, the only difference lies in the default allow labels which will be applied to the role if they are not explicitly set.

Labelv3 Defaultv4 Default
node_labels[{"*": "*"}] if the role has any logins, else [][]
app_labels[{"*": "*"}][]
kubernetes_labels[{"*": "*"}][]
database_labels[{"*": "*"}][]

RBAC for hosts

A Teleport role can also define which hosts (nodes) a user can have access to. This works by labeling nodes and listing allow/deny labels in a role definition.

Consider the following use case:

The infrastructure is split into staging/production environments using labels like environment=production and environment=staging. You can create roles that only have access to one environment. Let's say you create an intern role with the allow rule for label environment=staging.


The role below allows access to all nodes labeled "env=stage" except those that also have "workload=database" (these will always be denied).

Access to any other nodes will be denied:

kind: role
version: v4
  name: example-role
      'env': 'stage'

      # multiple labels are interpreted as an "or" operation.  in this case
      # Teleport will deny access to any node labeled as 'database' or 'backup'
      'workload': ['database', 'backup']
Dynamic RBAC

Node labels can be dynamic, i.e. determined at runtime by an output of an executable. In this case, you can implement "permissions follow workload" policies (eg., any server where PostgreSQL is running becomes automatically accessible only by the members of the "DBA" group and nobody else).

Extended Node labels syntax

Below are a few examples for more complex filtering using various regexes.

kind: role
version: v4
  name: example-role
      # literal strings:
      'environment': 'test'
      # the wildcard ('*') means "any node"
      '*': '*'
      # a list of alternative options:
      'environment': ['test', 'staging']
      # regular expressions are also supported, for example the equivalent
      # of the list example above can be expressed as:
      'environment': '^test|staging$'

Teleport resources

RBAC lets teams limit what resources are available to Teleport users. This can be helpful if, for example, you don't want regular users editing SSO (auth_connector) or creating and editing new roles (role).

List of all rule options defined below.

    # Role: CRUD options for managing Teleport Roles
    - resources:
      - role
      verbs: [list, create, read, update, delete]
    # Auth Connectors: CRUD options for managing SSO connectors
    - resources:
      - auth_connector
      verbs:  [list, create, read, update, delete]
    # Session: Provides access to Session Recordings.
    # e.g If session read is false, users can't play the recordings
    # It is possible to restrict "list" but to allow "read" (in this case a user will
    # be able to replay a session using `tsh play` if they know the session ID)
    - resources:
      - session
      verbs:  [list,read]
    # Trusted Clusters:  CRUD options for managing Trusted Clusters
    - resources:
      - trusted_cluster
      verbs: [list, create, read, update, delete]
    # Events: Can view the audit log and session recordings.
    - resources:
      - event
      verbs:  [list, read]
    # User: CRUD options for managing Teleport local users
    - resources: [user]
      verbs: [list,create,read,update,delete]
    # Tokens: CRUD options for managing tokens
    # Enterprise customer can enable app and node wizard enabling this resource
    - resources: [token]
      verbs: [list,create,read,update,delete]

RBAC for sessions

It is possible to further limit access to shared sessions and session recordings. The examples below illustrate how to restrict session access only for the user who created the session.

Teleport versions prior to 8.1 don't support the roles exemplified below. You may to create such roles after an upgrade, but in the event of a cluster downgrade they will become invalid.

Role for restricted access to session recordings:

version: v4
kind: role
  name: only-own-sessions
    # Users can only view session recordings for sessions in which they
    # participated.
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants,

Role for restricted access to active sessions:

version: v4
kind: role
  name: only-own-ssh-sessions
    # Teleport allows shared session access by default, so for our restrictions
    # to work we first allow access to ssh_sessions...
    - resources: [ssh_session]
      verbs: ['*']
    # ... and then limit that access via a deny rule.
    # Deny rules take precedence over allow rules, so the resulting role allows
    # users to create SSH sessions but to only view their own sessions.
    - resources: [ssh_session]
      verbs: [list, read, update, delete]
      where: '!contains(ssh_session.participants,'

Second Factor - U2F

Refer to the Second Factor - U2F guide if you have a cluster using the legacy U2F support.

Have a suggestion or can’t find something?