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 roles are the primary mechanism for controlling what users can access and what they can do inside a Teleport cluster. Every role is a YAML document that describes two lists of rules — allow and deny — plus a set of behavioral options. Deny rules take priority over allow rules, and nothing is allowed by default.
You can manage roles through the Teleport Web UI, with tctl, the Terraform provider, or the Kubernetes operator.
# View all roles in your cluster
tsh login --proxy=example.teleport.sh --user=myuser
tctl get roles
Full role spec
The following YAML shows every commonly used field in a role resource. Fields marked (optional) can be omitted:
kind: role
version: v8 # v3–v8 supported; v8 is current
metadata:
name: example-role
description: "Example role showing all major fields"
spec:
# allow rules grant access when matched
allow:
# SSH logins the user may assume on Linux servers
logins:
- "{{internal.logins}}"
- ubuntu
- ec2-user
# Kubernetes principals
kubernetes_groups:
- "{{internal.kubernetes_groups}}"
- developers
kubernetes_users:
- "{{internal.kubernetes_users}}"
# Database access
db_names:
- "{{internal.db_names}}"
- "*"
db_users:
- "{{internal.db_users}}"
- alice
db_roles:
- reader
# Resource label selectors (all must match — logical AND across keys)
node_labels:
env: production
team: platform
app_labels:
env: production
kubernetes_labels:
env: "*" # wildcard matches any value
db_labels:
env: production
windows_desktop_labels:
env: production
# Label expression (alternative to label maps, supports OR / AND / NOT)
node_labels_expression: |
labels["env"] == "production" ||
contains(user.spec.traits["teams"], labels["team"])
# Windows logins
windows_desktop_logins:
- Administrator
- "{{internal.windows_logins}}"
# RBAC for Teleport resources (who can manage what via tctl/API)
rules:
- resources: [role, auth_connector, user, token]
verbs: [list, create, read, update, delete]
- resources: [session]
verbs: [list, read]
- resources: [event]
verbs: [list, read]
# Access Requests — which roles a user may request
request:
roles:
- prod-access
search_as_roles:
- prod-access
max_duration: 8h
reason:
mode: required
# Review permissions — which requests this role may review
review_requests:
roles:
- prod-access
preview_as_roles:
- prod-access
# deny rules override allow rules
deny:
node_labels:
env: "lab"
logins:
- root
# options control session behavior
options:
max_session_ttl: 12h
forward_agent: true
ssh_port_forwarding:
local:
enabled: true
remote:
enabled: false
ssh_file_copy: true
client_idle_timeout: 30m
disconnect_expired_cert: false
require_session_mfa: "no" # no | yes | hardware_key | hardware_key_touch
device_trust_mode: "optional" # off | optional | required | required-for-humans
record_session:
default: "best_effort"
create_host_user_mode: "keep" # off | keep | insecure-drop
create_db_user_mode: "off" # off | keep | best_effort_drop
max_connections: 0 # 0 = unlimited
lock: "best_effort" # best_effort | strict
desktop_clipboard: true
desktop_directory_sharing: true
allow and deny blocks
Label selectors
Label selectors restrict which enrolled resources a user can access. Each key-value pair in a map is a logical AND; multiple values for the same key are an OR.
allow:
db_labels:
env: production # AND
region: [us-east-1, eu-west-1] # OR within the key
"*": "*" grants access to all resources of that type. Role versions v3 and below defaulted to this; v4 and higher default to an empty set (no access).
Principal fields
These fields set the principals (logins, groups, database users, etc.) a user can assume when connecting to resources:
| Field | Resource Type |
|---|
logins | SSH login username on Linux servers |
windows_desktop_logins | Windows login username |
kubernetes_groups | Kubernetes groups to impersonate |
kubernetes_users | Kubernetes users to impersonate |
db_names | Database names accessible within a server |
db_users | Database user accounts |
db_roles | Database roles (for auto-provisioning) |
aws_role_arns | AWS IAM roles accessible via App Service |
azure_identities | Azure managed identities |
gcp_service_accounts | GCP service accounts |
RBAC rules for Teleport resources
The rules field controls which Teleport API resources users can manage via tctl, the Web UI, or the API:
allow:
rules:
- resources: [node, app, db, kube_cluster, windows_desktop]
verbs: [list, read]
- resources: [role]
verbs: [list, create, read, update, delete]
- resources: [session]
verbs: [list, read]
where: contains(session.participants, user.metadata.name)
list, create, read, update, delete.
The where clause filters access to individual resources using a predicate expression.
options block reference
| Option | Type | Multi-role behavior | Description |
|---|
max_session_ttl | duration | Shortest wins | Maximum certificate lifetime. |
forward_agent | bool | OR | Allow SSH agent forwarding. |
ssh_port_forwarding | object | AND | Allow TCP port forwarding (local/remote). |
ssh_file_copy | bool | AND | Allow SCP/SFTP file transfers. |
client_idle_timeout | duration | Shortest wins | Disconnect idle sessions. |
disconnect_expired_cert | bool | OR | Disconnect when certificate expires. |
require_session_mfa | string | OR | Per-session MFA requirement. |
device_trust_mode | string | — | Require verified device access. |
max_sessions | int | Lowest wins | Max concurrent sessions per SSH connection. |
max_connections | int | Lowest wins | Max concurrent Teleport sessions per user. |
record_session | object | Strictest wins | Session recording mode. |
create_host_user_mode | string | AND | Auto-create Linux host user. |
create_db_user_mode | string | OR | Auto-provision database user. |
lock | string | strict wins | Locking mode. |
desktop_clipboard | bool | AND | Allow clipboard sharing for RDP sessions. |
desktop_directory_sharing | bool | AND | Allow local directory sharing for RDP. |
pin_source_ip | bool | OR | Pin SSH certs to the source IP. |
Template variables
Role fields support template variables that are expanded at login time using traits from the Teleport user database or an SSO provider.
Internal traits (local users)
| Variable | Expands to |
|---|
{{internal.logins}} | SSH logins configured on the user record. |
{{internal.kubernetes_groups}} | Kubernetes groups configured on the user record. |
{{internal.kubernetes_users}} | Kubernetes users configured on the user record. |
{{internal.db_names}} | Database names configured on the user record. |
{{internal.db_users}} | Database users configured on the user record. |
{{internal.windows_logins}} | Windows logins configured on the user record. |
{{internal.aws_role_arns}} | AWS role ARNs configured on the user record. |
External traits (SSO providers)
SSO providers populate external traits from SAML attributes or OIDC claims:
| Variable | Expands to |
|---|
{{external.groups}} | Value of the groups claim/attribute from the IdP. |
{{external.username}} | Value of the username claim/attribute. |
{{external.email}} | User’s email address from the IdP. |
{{external["http://schemas.example.com/attr"]}} | Bracket notation for attribute URIs. |
Template functions
| Function | Description |
|---|
{{email.local(variable)}} | Extracts the local part of an email (before @). |
{{regexp.replace(variable, pattern, replacement)}} | Regex substitution in a trait value. |
Other variables
| Variable | Description |
|---|
{{user.metadata.name}} | The Teleport username; useful for ownership-based access. |
Example roles
Admin role
Full administrative access to the cluster:
kind: role
version: v8
metadata:
name: admin
spec:
allow:
logins: ["root", "ubuntu", "{{internal.logins}}"]
node_labels:
"*": "*"
db_labels:
"*": "*"
kubernetes_labels:
"*": "*"
kubernetes_groups: ["system:masters"]
app_labels:
"*": "*"
windows_desktop_labels:
"*": "*"
rules:
- resources: ["*"]
verbs: ["*"]
options:
max_session_ttl: 24h
forward_agent: true
Developer role
Production read access with the ability to request elevated privileges:
kind: role
version: v8
metadata:
name: developer
spec:
allow:
logins: ["{{internal.logins}}", "dev"]
node_labels:
env: staging
db_names: ["{{internal.db_names}}"]
db_users: ["{{internal.db_users}}"]
db_labels:
env: staging
kubernetes_labels:
env: staging
kubernetes_groups: ["developers"]
app_labels:
env: staging
request:
roles: [prod-access]
reason:
mode: required
options:
max_session_ttl: 8h
require_session_mfa: "yes"
Read-only auditor role
View sessions and events but no infrastructure access:
kind: role
version: v8
metadata:
name: auditor
spec:
allow:
rules:
- resources: [session, event]
verbs: [list, read]
- resources: [node, app, db, kube_cluster]
verbs: [list, read]
options:
max_session_ttl: 4h
Managing roles with tctl
List all roles
To see a single role in YAML format:tctl get role/developer --format=yaml
Create or update a role from a file
# Create (or update) a role from a YAML file
tctl create -f developer-role.yaml
Edit a role interactively
# Opens the role in $EDITOR
tctl edit role/developer
Deleting a role that is assigned to users will not immediately revoke their active sessions, but they will lose access on their next login or certificate renewal.
