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

---
title: Teleport Access Controls Reference
description: Explains the configuration settings that you can include in a Teleport role, which enables you to apply access controls for your infrastructure.
tocDepth: 3
---

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

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

- Nothing is allowed by default.
- Deny rules get evaluated first and take priority.

You can use any of the following to manage Teleport roles and other dynamic
resources:
- Teleport Web UI
- The `tctl` client tool
- Teleport Terraform provider
- Teleport Kubernetes operator
- [Custom API clients](../api/rbac.mdx)

To read more about managing dynamic resources, see the [Dynamic
Resources](../management/dynamic-resources.mdx) guide.

You can view all roles in your cluster on your local workstation by running the
following commands:

```code
# Log in to your cluster with tsh so you can use tctl from your local machine.
$ tsh login --user=myuser --proxy=<Var name="mytenant.teleport.sh" />
$ tctl get roles
```

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

## Example role specification

Here is a full role specification:

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

## Role options

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 sessions after an idle interval | The shortest timeout value wins, i.e. the most restrictive value is selected |
| `disconnect_expired_cert` | Forcefully terminate active 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 | |
| `device_trust_mode` | Enforce authenticated device access for the owner of this role (`required`, `optional`, `off`). Applies only to the resources in the roles' allow field. | |
| `require_session_mfa` | Enforce per-session MFA or PIV-hardware key restrictions on user login sessions (`no`, `yes`, `hardware_key`, `hardware_key_touch`). Applies only to the resources in the roles' allow field. | For per-session MFA, 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_mode` | Allow users to be automatically created on a host |  Logical "AND" i.e. if all roles matching a server specify host user creation (`off`, `drop`, `keep`), it will evaluate to the option specified by all of the roles. If some roles specify both `drop` or `keep` it will evaluate to `keep`|
| `create_db_user_mode` | Allow [database user auto provisioning](../database-access/auto-user-provisioning.mdx). Options: `off` (disable database user auto-provisioning), `keep` (disables the user at session end, removing the roles and locking it), and `best_effort_drop` (try to drop the user at session end, if it doesn't succeed, fallback to disabling it). | Logical "OR" i.e. if any role allows database user auto-provisioning, it's allowed |

## 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. |
| `requester`| Enterprise-only role that allows a user to create Access Requests. |
| `reviewer`| Enterprise-only role that allows review of Access Requests. |

### Role versions

There are currently four supported role versions: `v3`, `v4`, `v5`, `v6` and `v7`. `v4`, `v5` and `v6` roles are
completely backwards-compatible with `v3`, the only difference lies in the
default values which will be applied to the role if they are not
explicitly set. Additionally, roles `v5` or `v6` are required to use [Moderated Sessions](./guides/moderated-sessions.mdx).

Label              | `v3` Default   | `v4`, `v5` and `v6` Default
------------------ | -------------- | ---------------
`node_labels`       | `[{"*": "*"}]` if the role has any logins, else `[]` | `[]`
`app_labels`        | `[{"*": "*"}]` | `[]`
`kubernetes_labels` | `[{"*": "*"}]` | `[]`
`db_labels`         | `[{"*": "*"}]` | `[]`

Role `v6` introduced a new field `kubernetes_resources` that allows
fine-grained control over Kubernetes resources. See [Kubernetes RBAC](../kubernetes-access/manage-access/rbac.mdx) for more details.

Version              |  `kubernetes_resources`
------------------ | --------------
`v3`, `v4` and `v5` Default | `[{"kind":"pod", "name":"*", "namespace":"*", "verbs": ["*"]}]`
`v6` Default |  `[]`
`v7` Default |  `[{"kind":"*", "name":"*", "namespace":"*", "verbs": ["*"]}]`

## RBAC for infrastructure resources

A Teleport role defines which resources (e.g., applications, servers, and
databases) a user can access.
This works by [labeling resources](../management/admin/labels.mdx) and
configuring 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']
```

Teleport handles multiple label entries with logical "AND" operations.
As an example, this entry would match to databases that have the `env: prod`
label *and* a `region` label of either `us-west-1` or `eu-central-1`:

```yaml
    db_labels:
      'env': 'prod'
      'region': ['us-west-1', 'eu-central-1']
```

<Admonition
  type="tip"
  title="Dynamic RBAC"
>
  Resource 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 label matching 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$'
```

### Label expressions

<Admonition type="warning">
Label expressions are available starting in Teleport version `13.1.1`.
All components of your Teleport cluster must be upgraded to version `13.1.1`
or newer before you will be able to use label expressions.
This includes the Auth Service and **all** Teleport agents.
</Admonition>

Teleport roles also support matching resource labels with predicate expressions
when you need to:

- combine logic with OR and AND operators
- perform matching on label keys
- implement negative matches

The following example role would allow access to any nodes labeled `env=staging`
or labeled `team=<team>`, where `<team>` is one of the values of the user's
`teams` trait:

```yaml
kind: role
version: v7
metadata:
  name: example-role
spec:
  allow:
    node_labels_expression: |
      labels["env"] == "staging" ||
      contains(user.spec.traits["teams"], labels["team"])
```

The `<kind>_labels_expression` fields have the same purpose of the
matching `<kind>_labels` fields, but support predicate expressions instead
of label matchers.
They can be used in the following fields of role `spec.allow` and `spec.deny`
conditions:

- `node_labels_expression`
- `app_labels_expression`
- `cluster_labels_expression`
- `kubernetes_labels_expression`
- `db_labels_expression`
- `db_service_labels_expression`
- `windows_desktop_labels_expression`
- `group_labels_expression`

Check out our
[predicate language](../reference/predicate-language.mdx#label-expressions)
guide for a more in depth explanation of the language.

Typically you will only want to use one of `<kind>_labels` or
`<kind>_labels_expression` in a single role, but you are allowed to specify
both.
If you have both in a deny rule, the matching is greedy, if either one matches
access will be denied.
In an allow rule, the matching is not greedy, if both are set they both have to
match for access to be allowed.

## RBAC for dynamic 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`).

A rule for modifying RBAC resources 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 active sessions. You can see all of the
available resources and verbs under the `allow` section in the example role
configuration below.

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
      verbs: [list, create, read, update, delete]
    - resources:
        - kube_service
      verbs: [list, create, read, update, delete]
    - resources:
        - kube_cluster
      verbs: [list, create, read, update, delete]
    - resources:
        - db
      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]
```

### Allowing access to token resources

If you configure a role that allows tokens to be created, users assigned to the
role can create tokens to provision any type of Teleport resource.
For example, you might create a role with the following configuration to enable assigned
users to enroll servers:

```yaml
kind: role
version: v7
metadata:
  name: enroll-servers
spec:
  allow:
    node_labels:
      'env': 'us-lab'
    rules:
      - resources: [token]
        verbs: [list, create, read, update, delete]
  deny: {}
```

With these permissions, users assigned to the role can generate tokens to enroll
a server, application, or database, establish a trust relationship between a root
cluster and a new Teleport Proxy Service, or add a new leaf cluster.

Because the token resource isn't scoped to a specific context, such as a node or
trusted cluster, you should consider any role that provides token permissions to be
an administrative role. In particular, you should avoid configuring `allow` rules
that grant `create` and `update` permissions on `token` resources to prevent
unexpected changes to the configuration or state of your cluster.

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

<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 session access to the user's sessions
    # and sessions they can join by default. This allows seeing any sessions.
    - resources: [session_tracker]
      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: [session_tracker]
      verbs: [list, read, update, delete]
      where: '!contains(session_tracker.participants, user.metadata.name)'
```

## Role templates

In a Teleport role resource, certain fields allow you to use functions and
variables to configure a user's access. The functions and variables available
for a field depend on the access controls that the field configures.

### Template expressions for access to infrastructure resources

When a user attempts to authenticate to an infrastructure resource proxied by
Teleport, such as a database or Kubernetes cluster, Teleport determines from the
user's roles:
- Whether the user is authorized to connect to the resource.
- Which principals the user can assume when they authenticate (for example,
  Linux server logins and Kubernetes groups).

#### Fields

The following role fields control a user's access to infrastructure resources.
All of these are fields within the `allow` and `deny` sections of a Teleport
role resource.

Labels for resources enrolled with Teleport:
- `app_labels`
- `cluster_labels`
- `db_labels`
- `db_service_labels`
- `kubernetes_labels`
- `node_labels`
- `windows_desktop_labels`

Principals a user can assume on infrastructure resources:
- `aws_role_arns`
- `azure_identities`
- `db_names`
- `db_roles`
- `db_users`
- `desktop_groups`
- `gcp_service_accounts`
- `host_groups`
- `host_sudoers`
- `kubernetes_groups`
- `kubernetes_users`
- `logins`
- `windows_desktop_logins`

Teleport principals that a user can impersonate:
- `impersonate.rules`
- `impersonate.users`

#### Functions

You can use the following functions in role fields that govern access to
principals on infrastructure resources:

|Function|Description|
|---|---|
|`{{email.local(variable)}}`|Extracts the local part of an email address.|
|`{{regexp.replace(variable, expression, replacement)}}`|Finds all matches of the expression within the variable and replaces them with the replacement.|

#### Traits

For fields that configure access to infrastructure resources, Teleport
substitutes the following **traits** with data from the authenticating user,
drawing from the local user database as well as the user's external single
sign-on provider.

| Variable | Description |
| - | - |
|`{{internal.aws_role_arns}}`|List of allowed AWS role ARNS for the user.|
|`{{internal.azure_identities}}`| Returns the Azure identities defined in Teleport available to the user. Azure identities can be set for a specific user or defined in a role.|
|`{{internal.db_names}}`|List of all allowed database names for the user.|
|`{{internal.db_users}}`|List of all allowed database users for the user.|
|`{{internal.gcp_service_accounts}}`|List of GCP service accounts for the user.|
|`{{internal.kube_username}}`|Kubernetes usernames available to the user.|
|`{{internal.kubernetes_groups}}`|List of allowed Kubernetes groups for the user.|
|`{{internal.kubernetes_users}}`|List of allowed Kubernetes users for the user.|
|`{{internal.logins}}` | Substituted with a value stored in Teleport's local user database and logins from a root cluster. <br/><br/>For local users, Teleport will substitute this with the "allowed logins" parameter used in the `tctl users add [user] <allowed logins>` command. <br/><br/>If the role is within a leaf cluster in a [trusted cluster](../management/admin/trustedclusters.mdx), Teleport will substitute the logins from the root cluster whether the user is a local user or from an SSO provider. <br/><br/>As an example, if the user has the `ubuntu` login in the root cluster, then `ubuntu` will be substituted in the leaf cluster with this variable. |
|`{{internal.windows_logins}}`|List of allowed Windows logins for the user.|
|`{{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, the variable is expanded to the value of the "xyz" claim. See the next section for more information on referring to the `external` variable in Teleport roles. |

#### Accessing external traits in Teleport roles

When a user authenticates to Teleport through a single sign-on identity provider
(IdP), Teleport populates external variables using traits it receives from the
IdP.

For example, 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"]}}'
```


In role templates, you can refer to these variables using the following two
formats, where `trait` is the name of the trait:

- **Dot syntax:** `{{external.trait}}`
- **Bracket syntax:** `{{external["trait"]}}`

Teleport expands the template variables above with the value of the SAML
attribute or OIDC claim called `trait`.

You can specify an external trait in dot syntax if it begins with a letter and
contains only letters, numbers, and underscores. Otherwise, you must use bracket
syntax to specify a trait.

Common examples of external traits available through an identity provider
include the following:

- `{{external.logins}}`
- `{{external.username}}`
- `{{external.env}}`

Teleport can only expand an `external` variable to a string or a list of
strings. If you are using an OIDC-based SSO solution, ensure that you have
configured your identity provider to include claims with values that have a
supported data type.

Refer to your identity provider's documentation for the complete list of
available claims and attributes.

### Access Request template functions

The following variables and functions allow more fine-grained control over a
user's permissions to submit and review Access Requests.

#### Fields

You can use Access Request template functions in the following fields. You can
include these fields within either `allow` rules or `deny` rules:

- `request.search_as_roles`
- `request.roles`
- `review_requests.preview_as_roles`
- `review_requests.roles`
- `review_requests.where`

#### Functions

Access Requests support the following role template functions:

|Function|Description|
|---|---|
|`{{regexp.match(regexp)}}`|Returns `true` if the regular expression matches a user's role.|
|`{{regexp.not_match(regexp)}}`|Returns `true` if the regular expression does not match a user's role.|

Regular expressions support both glob-style wildcards (the `*` character) and
[Go-style regular expressions](https://pkg.go.dev/regexp). If an expression
begins with the `^` character and ends with the `$` character, Teleport will
evaluate it as a regular expression. Otherwise, it will evaluate it as a
wildcard expression.  Wildcards match a sequence of one or more characters.

#### Variables

Teleport does not perform variable expansion on the values of the fields above.

## Filter fields

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

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

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

## Second Factor - U2F

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