teleport/docs/pages/access-controls/reference.mdx

---
title: Access Controls Reference Documentation
description: Access Controls reference documentation for role options and properties.
h1: Teleport Access Controls Reference
---

This guide shows you how to use Teleport roles to manage role-based access
controls (RBAC) in your Teleport cluster.

## Roles

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".

```yaml
allow:
  - 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](../reference/resources.mdx).
To see the list of roles in a Teleport cluster, an administrator can execute:

<ScopedBlock scope={["oss", "enterprise"]}>

```code
# Log in to your cluster with tsh so you can use tctl from your local machine.
# You can also run tctl on your Auth Service host without running "tsh login"
# first.
$ tsh login --user=myuser --proxy=teleport.example.com
$ tctl get roles
```

</ScopedBlock>
<ScopedBlock scope={["cloud"]}>

```code
# Log in to your cluster with tsh so you can use tctl.
$ tsh login --user=myuser --proxy=mytenant.teleport.sh
$ tctl get roles
```

</ScopedBlock>

(!docs/pages/includes/backup-warning.mdx!)

Here is a full role specification:

(!docs/pages/includes/role-spec.mdx!)

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

| Variable | Description |
| - | - |
| `{{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. |
| `{{external.xyz}}` | Substituted with a value from an external [SSO provider](https://en.wikipedia.org/wiki/Single_sign-on). 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="http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname">
        <AttributeValue>firstname.lastname</AttributeValue>
</Attribute>
```

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

```
logins:
   - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'
```

### Role options

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

| Option | Description | Multi-role behavior |
| - | - | - |
| `max_session_ttl` | Max. time to live (TTL) of a user's SSH certificates | The shortest TTL wins |
| `forward_agent` | Allow SSH agent forwarding | Logical "OR" i.e. if any role allows agent forwarding, it's allowed |
| `port_forwarding` | Allow TCP port forwarding | Logical "OR" i.e. if any role allows port forwarding, it's allowed |
| `ssh_file_copy` | Allow SCP/SFTP | Logical "AND" i.e. if all roles allows file copying, it's allowed |
| `client_idle_timeout` | Forcefully terminate active SSH sessions after an idle interval | The shortest timeout value wins, i.e. the most restrictive value is selected |
| `disconnect_expired_cert` | Forcefully terminate active SSH sessions when a client certificate expires | Logical "OR" i.e. evaluates to "yes" if at least one role requires session termination |
| `max_sessions` | Total number of session channels which can be established across a single SSH connection via Teleport | |
| `enhanced_recording` | Indicates which events should be recorded by the BFP-based session recorder | |
| `permit_x11_forwarding` | Allow users to enable X11 forwarding with OpenSSH clients and servers | |
| `require_session_mfa` | Require additional MFA tap before initiating a session | Logical "OR" i.e. evaluates to "yes" if at least one role requires session MFA |
| `lock` | Locking mode (`strict` or `best_effort`) | `strict` wins in case of conflict |
| `request_access` | Enterprise-only Access Request strategy (`optional`, `always` or `reason`) | |
| `request_prompt` | Prompt for the Access Request "reason" field | |
| `max_connections` | Enterprise-only limit on how many concurrent sessions can be started via Teleport | |
| `max_kubernetes_connections` | Defines the maximum number of concurrent Kubernetes sessions per user | |
| `record_session` |Defines the [Session recording mode](../reference/audit.mdx#modes).|The strictest value takes precedence.|
| `desktop_clipboard` | Allow clipboard sharing for desktop sessions | Logical "AND" i.e. evaluates to "yes" if all roles enable clipboard sharing |
| `pin_source_ip` | Enable source IP pinning for SSH certificates | Logical "OR" i.e. evaluates to "yes" if at least one role requires session termination |
| `cert_extensions` | Specifies extensions to be included in SSH certificates | |
| `create_host_user` | Allow users to be automatically created on a host |  Logical "AND" i.e. evaluates to "yes" if all roles matching a Node enable host user creation |

## Preset roles

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

| Role | Description |
| --- | --- |
| `editor` | Allows editing of cluster configuration settings. |
| `auditor`| Allows reading cluster events, audit logs, and playing back session records. |
| `access`| Allows access to cluster resources. |

<Details title="Version Warning: Before 8.0" opened={false}>
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.
</Details>

### Role versions

There are currently three supported role versions: `v3`, `v4` and `v5`. `v4` and `v5` 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. Additionally, `v5` is required to use [Moderated Sessions](./guides/moderated-sessions.mdx).

Label              | `v3` Default   | `v4` and `v5` 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](../management/admin/labels.mdx) 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`.

### Example

The role below allows access to all nodes labeled "env=stage" except those that
also have "workload=database" or "workload=backup".

Access to any other nodes will be denied.

```yaml
kind: role
version: v5
metadata:
  name: example-role
spec:
  allow:
    node_labels:
      'env': 'stage'

  deny:
    node_labels:
      # Multiple labels are interpreted as an "or" operation. In this case,
      # Teleport will deny access to any node labeled as 'workload=database' or
      # 'workload=backup'
      'workload': ['database', 'backup']
```

<Admonition
  type="tip"
  title="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).
</Admonition>

### Extended Node labels syntax

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

```yaml
kind: role
version: v5
metadata:
  name: example-role
spec:
  allow:
    node_labels:
      # 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`).

Below is an example `allow` section that illustrates commonly used `rules`.
Each rule includes a list of Teleport resources and the CRUD
operations that a user is allowed to execute on them:

```yaml
allow:
  rules:
    # CRUD options for managing Teleport Server Access Nodes
    - resources:
        - node
      verbs: [list, create, read, update, delete]
    - resources:
        - app_server
      verbs: [list, create, read, update, delete]
    - resources:
        - kube_service
      verbs: [list, create, read, update, delete]
    - resources:
        - db_server
      verbs: [list, create, read, update, delete]
    - resources:
        - windows_desktop
      verbs: [list, create, read, update, delete]
    - resources:
        - role
      verbs: [list, create, read, update, delete]
    # Auth connectors are also known as 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]
    - resources:
        - trusted_cluster
      verbs: [list, create, read, update, delete]
    # Events: Determines whether a user can view the audit log
    # and session recordings.
    - resources:
        - event
      verbs: [list, read]
    - resources:
        - user
      verbs: [list, create, read, update, delete]
    - resources:
        - token
      verbs: [list, create, read, update, delete]

```

## RBAC for sessions

It is possible to further limit access to
[shared sessions](../connect-your-client/tsh.mdx#sharing-sessions) and
[session recordings](../architecture/nodes.mdx#ssh-session-recording).
The examples below illustrate how to restrict session access only for the user
who created the session.

<Details title="Version Warning: Before 8.1" opened={false}>
Teleport versions prior to 8.1 don't support the roles shown below.
You may create these roles after upgrading, but in the event of a cluster
downgrade they will become invalid.
</Details>

<Admonition
  type="warning"
  title="Preset Auditor Role"
>
In order for these roles to take effect, you must ensure your user doesn't also
have a more permissive role, like the preset `auditor` role, which allows access
to all events, sessions, and session recordings.
</Admonition>

Role for restricted access to session recordings:

```yaml
version: v5
kind: role
metadata:
  name: only-own-sessions
spec:
  allow:
    rules:
    # Users can only view session recordings for sessions in which they
    # participated.
    - resources: [session]
      verbs: [list, read]
      where: contains(session.participants, user.metadata.name)
```

Role for restricted access to active sessions:

```yaml
version: v5
kind: role
metadata:
  name: only-own-ssh-sessions
spec:
  allow:
    rules:
    # Teleport allows shared session access by default, so for our restrictions
    # to work we first allow access to ssh_sessions...
    - resources: [ssh_session]
      verbs: ['*']
  deny:
    rules:
    # ... 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, user.metadata.name)'
```

## Second Factor - U2F

Refer to the [Second Factor - WebAuthn](./guides/webauthn.mdx#u2f) guide if you
have a cluster using the legacy U2F support.

## Filter fields

Here is an explanation of the fields used in the `where` and `filter` conditions within this guide.

| Field                      | Description                                         |
|----------------------------|-----------------------------------------------------|
| `user.roles`               | The list of roles assigned to a user              |
| `session.participants`     | The list of participants from a session recording |
| `ssh_session.participants` | The list of participants from an SSH session       |
| `user.metadata.name`       | The user's name                                     |

Check out our [predicate language](../reference/predicate-language.mdx#scoping-allowdeny-rules-in-role-resources)
guide for a more in depth explanation of the language.