Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport’s role-based access control (RBAC) system lets you define exactly which users can reach which infrastructure resources — SSH nodes, Kubernetes clusters, databases, applications, and desktops — and under what conditions. Every access decision is evaluated against a set of Teleport roles assigned to the authenticated user.

​
How Teleport roles work

A Teleport role is a YAML resource with two rule lists: allow and deny. Teleport evaluates rules using the following logic:
  • Nothing is allowed by default.
  • deny rules are evaluated first and always take priority over allow rules.
  • Multiple roles are merged; the most restrictive option typically wins for options like timeouts, while logical OR applies for capabilities like port forwarding.
Deny rules take precedence over allow rules in all cases. If a user holds two roles where one allows access to a node and another denies it, access will be denied. Use deny rules deliberately and avoid placing them on roles granted through Access Lists.

​
Example role YAML

The following role grants a developer access to staging servers, a Kubernetes cluster, and a PostgreSQL database. It uses template variables to automatically populate logins and Kubernetes groups from the user’s stored traits. 
kind: role
version: v7
metadata:
  name: developer
spec:
  options:
    max_session_ttl: 8h
    forward_agent: true
  allow:
    # SSH node access — only nodes labeled env=staging
    node_labels:
      env: staging
    logins:
      - '{{internal.logins}}'
      - ubuntu

    # Kubernetes access
    kubernetes_labels:
      env: staging
    kubernetes_groups:
      - '{{internal.kubernetes_groups}}'
      - developers
    kubernetes_users:
      - '{{internal.kubernetes_users}}'

    # Database access
    db_labels:
      env: staging
    db_names:
      - '{{internal.db_names}}'
      - app_db
    db_users:
      - '{{internal.db_users}}'
      - readonly

  deny: {}

​
Creating and assigning roles

Use tctl to apply a role resource and assign it to a user: 
# Create or update the role from a file
$ tctl create -f developer.yaml

# Assign the role to a user
$ tctl users update alice --set-roles=developer,access

# Verify the user's roles
$ tctl get users/alice
You can also view all roles in your cluster: 
$ tsh login --proxy=example.teleport.sh --user=myuser
$ tctl get roles

​
Attribute-based access control with labels

Teleport extends RBAC with label-based ABAC — you match resources by their labels rather than by name. This makes policies dynamic: a newly enrolled server automatically receives access (or is automatically denied) based on the labels it carries. 
allow:
  node_labels:
    # Literal match
    environment: production
    # Wildcard: any region value
    region: '*'
    # List of alternatives (OR logic within a key)
    tier: ['web', 'api']
    # Regular expression
    team: '^platform|infra$'
Multiple label keys within the same block are combined with AND logic. For example, a node must match both environment=production AND the specified region to be accessible.

​
Label expressions

For more complex logic — OR across keys, negative matches, or trait-based comparisons — use node_labels_expression (and the equivalent for other resource types): 
kind: role
version: v7
metadata:
  name: team-access
spec:
  allow:
    node_labels_expression: |
      labels["env"] == "staging" ||
      contains(user.spec.traits["teams"], labels["team"])
The same pattern applies to app_labels_expression, db_labels_expression, kubernetes_labels_expression, and others.

​
Role traits and template variables

Teleport substitutes template variables at authentication time, drawing values from the user’s internal traits (stored in Teleport’s local user database) or external traits from your SSO provider.

​
Internal traits

VariableDescription
{{internal.logins}}SSH logins allowed for the user
{{internal.kubernetes_groups}}Kubernetes groups for the user
{{internal.kubernetes_users}}Kubernetes usernames for the user
{{internal.db_names}}Allowed database names
{{internal.db_users}}Allowed database users

​
External traits (SSO)

When a user authenticates through an SSO provider, Teleport populates the external namespace from the IdP’s claims or attributes: 
logins:
  - '{{external.username}}'
db_users:
  - '{{external.db_user}}'
# For SAML attributes with URL-format names, use bracket syntax:
logins:
  - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'
You can also use helper functions in template expressions: 
logins:
  # Extract the local part of an email address (e.g. alice@example.com → alice)
  - '{{email.local(external.email)}}'

​
Setting traits on local users

For local (non-SSO) users, set traits directly on the user resource: 
kind: user
version: v2
metadata:
  name: alice
spec:
  roles:
    - developer
  traits:
    logins:
      - alice
      - ubuntu
    kubernetes_groups:
      - developers
    db_names:
      - app_db

​
Role options reference

Key options that control session behavior when multiple roles are assigned:
OptionDescriptionMulti-role behavior
max_session_ttlMaximum certificate TTLShortest wins
forward_agentSSH agent forwardingOR (any role allows → allowed)
client_idle_timeoutIdle session terminationShortest timeout wins
require_session_mfaPer-session MFAOR (any role requires → required)
device_trust_modeTrusted device enforcementSee Device Trust
record_sessionSession recording modeMost strict wins

​
Preset roles

Teleport ships with several built-in roles:

access

Default role for human users. Grants access to resources based on the user’s traits.

editor

Allows editing cluster configuration and most dynamic resources.

auditor

Read-only access to audit logs and session recordings.

reviewer

Can review and approve Access Requests submitted by other users.

​
Next steps

SSO Integration

Map identity provider groups to Teleport roles automatically.

Access Requests

Let users request temporary elevated roles with approval workflows.

MFA

Require multi-factor authentication for login and per-session access.

Device Trust

Restrict access to only registered, managed devices.

Build docs developers (and LLMs) love

Get started for freeTalk to us