Skip to main content
Version: 19.x (unreleased)

Scoped RBAC

Report an Issue

Scopes are a hierarchical organization system for Teleport resources and permissions. A scope is a path-like attribute (for example /staging/west or /prod) attached to resources and permission grants. Permissions assigned at a scope apply to resources within that scope and all of its descendant scopes, but cannot reach across to orthogonal scopes or up to ancestor scopes.

For example, a cluster administrator can assign a scoped admin role to Alice at /staging/west. Alice can then manage scoped roles, scoped tokens, and SSH Services in /staging/west and descendant scopes such as /staging/west/team-a, but she cannot affect /staging/east, /prod, or unscoped cluster resources.

This page describes the concepts behind scopes, and provides instructions for basic usage and specific scenarios.

Use cases​

Scopes are designed to enable:

  • Hierarchical isolation. Permissions granted within a scope cannot affect resources or permissions in parent or sibling scopes.
  • Delegated administration. Cluster administrators can grant powerful administrative capabilities to "scope admins" without those admins being able to affect anything outside their scope.
  • Reduced blast radius. Users can pin a login session to a specific scope, limiting the privileges of the resulting credentials to that scope and its descendants.
  • Mixed permissiveness. Different access controls (such as session recording, port forwarding, or idle timeouts) can apply to the same user in different scopes.

Scopes are an attribute, not an object. A scope path does not need to be created before resources or permissions are assigned to it.

Scopes complement labels, but they solve a different problem. Labels describe individual resources and are used by roles to choose matching resources. Scopes define the administrative boundary and the scope of issued credentials. Label selectors can further restrict which resources a scoped role can access, but they cannot grant access outside the role assignment's scope.

Active development

Scopes are an actively developed feature of Teleport. Not every Teleport feature is supported within a scope yet, and breaking changes may still be introduced. Scoped resources and credentials created with one Teleport version may not work with another.

When operating in a scoped session, commands and APIs that have not yet been updated to understand scopes will commonly fail with a scoped identities not supported error. This is expected for features outside the currently supported set listed below.

Prerequisites​

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  19.0.0-dev
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
  • All Teleport instances (Auth Service, Proxy Service, and Agents) must be running the same Teleport version, and must have the TELEPORT_UNSTABLE_SCOPES=yes environment variable set.

Currently supported features​

The current implementation provides the following functionality. Treat this as the exhaustive list of scoped features; features that are not listed here should be assumed unsupported in scoped mode.

  • The scoped_role resource for describing scoped permissions.
  • The scoped_role_assignment resource for assigning scoped roles to users and Bots.
  • The scoped_token resource for joining Agents at a specific scope.
  • Scope pinning, allowing a user to log in at a scope and create a session whose privileges are limited to the target scope.
  • Basic scoped SSH access, including joining SSH Services at a scope and assigning scoped SSH access to users.
  • Basic scoped Kubernetes access, including joining Kubernetes services at a scope and assigning scoped Kubernetes access to users.
  • Scoped Access Lists that can be managed by scoped administrators and used to grant scoped roles to groups of users.
  • Scoped Bots for Machine and Workload Identity (MWI), supporting both identity output and SSH access.

Basic usage​

Scoped and unscoped operations are mutually exclusive. When logged in without a scope, scoped roles do not grant any privileges. When logged in to a scope, only features that have been explicitly updated for scopes are expected to work. The following commands are officially supported in scoped mode:

  • tsh login --scope=<scope> ...
  • tsh logout (required to exit a scoped session)
  • tsh ls (lists SSH instances available at the current scope)
  • tsh ssh <login>@<host> (for SSH instances available at the current scope)
  • tsh kube ls (lists Kubernetes clusters available at the current scope)
  • tsh kube login <cluster> (for Kubernetes clusters available at the current scope)
  • tctl get|create|edit|rm <resource> (for scoped resources)
  • tctl scoped tokens add|rm|ls ... (for managing scoped tokens)
  • tctl scopes status (overview of scoped privilege usage in the cluster)
note

The admin action MFA prompt does not currently apply to scoped resources. Scoped commands that do not prompt for MFA today may begin to do so in future releases.

Setting up a scoped admin​

A new Teleport cluster has no scoped roles defined. The default editor role includes the ability to create and assign scoped roles, so an unscoped administrator can bootstrap the first scoped admin.

While logged in as a user with the editor role, create a scoped admin role that can manage scoped permissions, SSH into instances, and connect to Kubernetes clusters within /examples (replace ubuntu with your desired OS login):

tctl create <<EOFkind: scoped_rolemetadata:  name: example-adminscope: /examplesspec:  assignable_scopes:    - /examples  kube:    labels:      - name: '*'        values: ['*']    groups: [cluster-admin]  ssh:    logins: [ubuntu]    labels:      - name: '*'        values: ['*']    permit_x11_forwarding: true    forward_agent: true    file_copy: true    port_forwarding:      local:        enabled: true      remote:        enabled: true  rules:    - resources: [scoped_role, scoped_role_assignment, bot, bot_instance, access_list]      verbs: [create, list, readnosecrets, update, delete]    - resources: [scoped_token]      verbs: [create, list, read, update, delete]version: v1EOF

Note that the kube configuration block does not yet support configuring kubernetes_resources.

Next, create a scoped role assignment to grant example-admin to the user who will become the scoped admin (replace alice with your user):

tctl create <<EOFkind: scoped_role_assignmentsub_kind: dynamicscope: /examplesspec:  user: alice  assignments:    - role: /examples::example-admin      scope: /examples/basicversion: v1EOF

Although the example-admin role is defined at /examples, it is assigned to alice only at the more specific scope /examples/basic. Using scope hierarchy this way ensures alice cannot reach across to other scopes under /examples and provides a guardrail against alice accidentally editing her own admin role and locking herself out.

Joining a scoped SSH Service​

Log the scoped admin into the desired scope:

tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.com

Create a scoped token that can be used to join an SSH Service at the desired scope:

tctl scoped tokens add --scope=/examples/basic --assign-scope=/examples/basic --ttl=8h --type=node

A scoped token has two distinct scopes:

  • --scope sets the scope that the token resource itself lives in. This is the administrative scope of the token, and determines who can manage it. A scoped admin can only create tokens within their own scope or a descendant scope.
  • --assign-scope sets the scope that will be assigned to any resource (such as an SSH Service) that joins the cluster using this token. The assigned scope must be equal to or a descendant of the token's --scope.

In this example, both values are /examples/basic because the scoped admin is creating a token within their scope and using it to provision an SSH Service instance in the same scope. To provision an SSH Service into a more specific scope, use a more specific --assign-scope. For example, with --scope=/examples/basic --assign-scope=/examples/basic/west, the token is owned at /examples/basic but the joined SSH Service will live at /examples/basic/west.

Follow the printed instructions to join an SSH Service using the generated token. Once the instance has joined, the scoped admin can list it:

tsh ls
Node Name    Address Labels------------ ------- -----------example-node Tunnel  foo=bar

Finally, SSH into the SSH Service instance using the scoped admin user:

tsh ssh ubuntu@example-node

Joining a scoped Kubernetes Service​

Only static Kubernetes clusters support joining with scopes. Dynamic cluster registration, including those discovered by the Teleport Discovery Service, dot not yet support scopes.

Log the scoped admin into the desired scope:

tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.com

Create a scoped token that can be used to join a Kubernetes Service at the desired scope:

tctl scoped tokens add --scope=/examples/basic --assign-scope=/examples/basic --ttl=8h --type=kube

A scoped token has two distinct scopes:

  • --scope sets the scope that the token resource itself lives in. This is the administrative scope of the token, and determines who can manage it. A scoped admin can only create tokens within their own scope or a descendant scope.
  • --assign-scope sets the scope that will be assigned to any resource (such as a Kubernetes Service) that joins the cluster using this token. The assigned scope must be equal to or a descendant of the token's --scope.

In this example, both values are /examples/basic because the scoped admin is creating a token within their scope and using it to provision a Kubernetes Service instance in the same scope. To provision a Kubernetes Service into a more specific scope, use a more specific --assign-scope. For example, with --scope=/examples/basic --assign-scope=/examples/basic/west, the token is owned at /examples/basic but the joined Kubernetes Service will live at /examples/basic/west.

Follow the printed instructions to join a Kubernetes cluster using helm and the generated token. Once the instance has joined, the scoped admin can list it:

tsh kube ls
Kube Cluster Name Labels Scope         Selected----------------- ------ ------------- --------example-cluster          /example/west

Login to the Kubernetes cluster using the scoped admin user:

tsh kube login example-cluster

This generates the kubeconfig necessary to access the cluster using scoped credentials. You can either use kubectl directly by specifying the correct context or use the tsh kubectl sub-command to interact with the selected cluster.

Adding immutable labels via a token​

A scoped token can carry a set of immutable labels that are automatically applied to any SSH instance that joins with the token, and which cannot be overridden by the joining instance.

tctl scoped tokens add --scope=/examples/basic --assign-scope=/examples/basic --ttl=8h --type=node --ssh-labels=foo=bar,baz=qux

The invite token: 019ce8f7-f0d5-784d-af3f-075aa79c19cbThis token will expire in 480 minutes.
Run this on the new node to join the cluster:
> teleport start \   --roles=node \   --token=019ce8f7-f0d5-784d-af3f-075aa79c19cb~YzZlYzdlYTg1YTZjZTEwZjVjYjAxMTc3Mjc2NTk3NGY \   --auth-server=proxy.example.com:443

Inspect the token to confirm the immutable labels:

tctl get scoped_token/019ce8f7-f0d5-784d-af3f-075aa79c19cb
kind: scoped_tokenmetadata:  expires: "2026-03-14T04:51:29.109545Z"  name: 019ce8f7-f0d5-784d-af3f-075aa79c19cbscope: /examples/basicspec:  assigned_scope: /examples/basic  immutable_labels:    ssh:      baz: qux      foo: bar  join_method: token  roles:  - Node  usage_mode: unlimitedstatus: {}version: v1

Once the SSH Service instance joins, the immutable labels are merged with any labels set on the instance itself and cannot be overridden:

tctl get node/example
kind: nodemetadata:  labels:    env: test    fruit: pear  name: edff1d38-bbcb-4a21-b38d-ac43a2e20f85scope: /examples/basicspec:  hostname: example  immutable_labels:    baz: qux    foo: bar  use_tunnel: true  version: 18.7.1version: v2
tsh ls
Scope           Node Name Address Labels-------------------------------------------------------------------------/examples/basic example   Tunnel  baz=qux,foo=bar,fruit=pear,env=test

Single-use tokens​

Scoped tokens can be restricted so that they may only be used to join a single instance. Set --mode=single_use when creating the token:

tctl scoped tokens add --scope=/examples/basic --assign-scope=/examples/basic --ttl=8h --type=node --mode=single_use

The invite token: 019ce90a-3585-75b1-b992-263758a9b843This token will expire in 480 minutes.

Use the token as normal to join an instance. After joining completes, the token's status reflects that it has been consumed:

tctl get scoped_token/019ce90a-3585-75b1-b992-263758a9b843
kind: scoped_tokenmetadata:  expires: "2026-03-14T05:11:26.341373Z"  name: 019ce90a-3585-75b1-b992-263758a9b843scope: /examples/basicspec:  assigned_scope: /examples/basic  join_method: token  roles:  - Node  usage_mode: single_usestatus:  secret: {}  usage:    single_use:      reusable_until: "2026-03-13T21:44:05.695268Z"      used_at: "2026-03-13T21:14:05.695268Z"      used_by_fingerprint: +I0OyNhoiP5BSvA8kIE+QLYOZYHQ7ngDh0/MgTRXncc=version: v1

Subsequent join attempts using the token fail:

ERROR REPORT:
Original Error: *interceptors.RemoteError scoped token usage exhausted

Adding scoped users as a scoped admin​

Log the scoped admin into the desired scope:

tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.com

Create a scoped role that grants SSH access to SSH Services at the scope (replace ubuntu with your desired OS login):

tctl create <<EOFkind: scoped_rolemetadata:  name: example-userscope: /examples/basicspec:  assignable_scopes:  - /examples/basic  ssh:    logins: [ubuntu]    labels:      - name: '*'        values: ['*']    permit_x11_forwarding: true    forward_agent: true    file_copy: true    port_forwarding:      local:        enabled: true      remote:        enabled: trueversion: v1EOF

Assign the role to the intended user (replace bob with your user):

tctl create <<EOFkind: scoped_role_assignmentsub_kind: dynamicscope: /examples/basicspec:  user: bob  assignments:    - role: example-user      scope: /examples/basicversion: v1EOF

Bob can now log in to the scope and SSH into SSH Services within it:

tsh login --user=bob --scope=/examples/basic --proxy=teleport.example.com
tsh ls
Node Name    Address Labels------------ ------- -----------example-node Tunnel  foo=bar
tsh ssh ubuntu@example-node

Granting scoped roles with Access Lists​

Access Lists can grant scoped roles to groups of users without requiring an individual scoped role assignment per user.

Log the scoped admin into the desired scope:

tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.com

Create a scoped role that can grant SSH access in /examples/basic:

tctl create -f <<EOFkind: scoped_rolemetadata:  name: example-accessscope: /examples/basicspec:  assignable_scopes:    - /examples/basic  ssh:    logins: [ubuntu]    labels:      - name: '*'        values: ['*']    permit_x11_forwarding: true    forward_agent: true    file_copy: true    port_forwarding:      local:        enabled: true      remote:        enabled: trueversion: v1EOF

Create an Access List that grants this scoped role to its members:

tctl create <<EOFversion: v1kind: access_listmetadata:  name: example-access-listscope: /examples/basicspec:  title: "Example scoped Access List"  description: "Grants scoped access to SSH Services in /examples/basic"  owners:    - name: alice      membership_kind: MEMBERSHIP_KIND_USER  grants:    scoped_roles:      - role: /examples/basic::example-access        scope: /examples/basicEOF

Add members to the Access List:

tctl acl users add /examples/basic::example-access-list bob
successfully added user bob to access list /examples/basic::example-access-list
tctl acl users add /examples/basic::example-access-list charlie
successfully added user charlie to access list /examples/basic::example-access-list

Access Lists that grant scoped roles always result in a "materialized" scoped role assignment for each of their members and owners. A "materialized" scoped role assignment is an one that is automatically created and kept up to date for each user that is granted a scoped role by an Access List. Each materialized scoped role assignment assigns all of the scoped roles granted by the Access List to the user. Confirm a scoped role assignment has been materialized for each member:

tctl get scoped_role_assignments --format text
SubKind      ID                                                          User    Assigns                        ------------ ----------------------------------------------------------- ------- --------------------------------------------------materialized /examples/basic::acl-4ezohtYllrk-gbWjn0hj_npCNwhujMurruDLRg charlie /examples/basic::example-access -> /examples/basicmaterialized /examples/basic::acl-XMyMVGoNZopPQ9WxuZ5RH6GM5FPHVwLSTFUsBg bob     /examples/basic::example-access -> /examples/basic

Access Lists and members can also be managed via the Web UI under Identity Governance > Access Lists. Currently, only unscoped Access Lists can be created or managed in the web UI, but unscoped Access Lists can still grant scoped roles as long as the role is defined in the root scope /.

Nested Access Lists are fully supported, meaning Access Lists can have members that are other Access Lists, and members of the child list receive all scoped role grants from the parent list. Scoped roles can also be granted to Access List owners using the owner_grants field. See the Access Lists reference for details.

Scoped Access List rules​

To maintain hierarchical scoped privilege isolation, the following rules apply to scoped Access Lists:

  1. An Access List can only grant scoped roles defined in a scope that is equal to or an ancestor of the list's scope.
  2. A scoped role grant can only grant the scoped role at a scope that is equal to or a descendent of the list's scope.
  3. An Access List can only be added as a member of another Access List if the member list's scope is equal to or an ancestor of the parent list's scope.
  4. An Access List can only be added as an owner of another Access List if the owner list's scope is equal to or an ancestor of the owned list's scope.
  5. A scoped Access List (or an unscoped list that grants any scoped roles) may not contain member requirements or owner requirements.

Any attempt to create an Access List violating these rules will be rejected by the Auth Service with an error message.

For an example Access List with scope /examples/basic:

  1. It can only grant scoped roles defined in /examples/basic or /examples or /.
  2. It can only grant scoped roles at /examples/basic or /examples/basic/**.
  3. It can only have member Access Lists that are unscoped or have scope /examples/basic or /examples or /.
  4. It can only have owner Access Lists that are unscoped or have scope /examples/basic or /examples or /.
  5. It may not contain any member or owner requirements.

Infrastructure as Code​

Scoped roles, scoped role assignments, and scoped tokens can be managed with Teleport's IaC tooling.

The Teleport Terraform provider supports these resources:

The Kubernetes Operator supports these custom resources:

When using the Kubernetes Operator, the Helm values used to install the operator must set TELEPORT_UNSTABLE_SCOPES=yes in the operator's environment:

extraEnv:
  - name: TELEPORT_UNSTABLE_SCOPES
    value: "yes"

Scoped Machine and Workload Identity​

The standard bot resource supports the scope field. When set, the Bot is considered a scoped Bot. Scoped Bots can be created, read, updated, and deleted by scope admins through scoped roles and scoped role assignments.

The relationship between a scoped Bot and its associated resources is constrained as follows:

  • Scoped Bots produce identities pinned to the scope they exist in. They can only access resources within that scope or descendant scopes, not in ancestor or orthogonal scopes.
  • Scoped Bots may only be granted privileges within their own scope or descendant scopes.
  • Unscoped roles cannot be assigned to a scoped Bot.
  • A scoped Bot must authenticate using a scoped token. Scoped Bots cannot use unscoped join tokens.
  • The scoped token used by a scoped Bot must exist in the same scope as the Bot or in an ancestor scope.

To authenticate as a scoped Bot, tbot must be running in scoped mode, controlled by either the scoped: true configuration value or the --scoped CLI flag.

Scoped MWI example​

The following example shows the scoped resources required to run a Bot in scoped mode. It assumes you already have an unscoped administrator who can bootstrap the first scoped admin, and a scoped role named staging-ssh-access that grants the Bot its intended SSH privileges.

Grant a scope administrator the ability to manage scoped Bots and scoped tokens:

kind: scoped_role
version: v1
metadata:
  name: staging-scope-mwi-admin
scope: /staging
spec:
  assignable_scopes:
    - /staging
  rules:
    - resources:
        - scoped_role
        - scoped_role_assignment
        - bot
        - bot_instance
      verbs:
        - list
        - readnosecrets
        - create
        - update
        - delete
    - resources:
        - scoped_token
      verbs:
        - list
        - read
        - readnosecrets
        - create
        - update
        - delete
---
kind: scoped_role_assignment
version: v1
metadata:
  name: 8a3f1c2d-9e47-4b6a-a1d0-5c8e7f3b2a92
scope: /staging
sub_kind: dynamic
spec:
  user: my-scope-admin
  assignments:
    - role: staging-scope-mwi-admin
      scope: /staging

The scope administrator can now create a scoped Bot. Beyond a name and a scope, no further configuration is required:

kind: bot
version: v1
metadata:
  name: my-scoped-bot
scope: /staging
spec: {}

Grant the Bot privileges through a scoped role assignment, identifying the Bot by its scope-qualified name in spec.bot:

kind: scoped_role_assignment
version: v1
metadata:
  name: 6b72b4dc-655e-4b3b-bae3-515378a296ae
scope: /staging
sub_kind: dynamic
spec:
  bot: /staging::my-scoped-bot
  assignments:
    - role: staging-ssh-access
      scope: /staging

Create a scoped token that the Bot will use to authenticate. The example below uses the bound_keypair join method, but other join methods are also supported:

kind: scoped_token
version: v1
metadata:
  name: my-scoped-bot
scope: /staging
spec:
  roles: [Bot]
  join_method: bound_keypair
  usage_mode: bot
  bot: /staging::my-scoped-bot
  bound_keypair: {}

Configure tbot to run in scoped mode by setting scoped: true in the configuration file (or by passing --scoped on the command line):

version: v2
proxy_server: example.teleport.sh:443
onboarding:
  join_method: bound_keypair
  token: my-scoped-bot
  bound_keypair:
    registration_secret: <secret fetched from "tctl get scoped_token/my-scoped-bot --with-secrets">
scoped: true
storage:
  type: directory
  path: /var/lib/teleport/bot
services:
  - type: identity
    destination:
      type: directory
      path: /opt/machine-id

Once tbot is running, the credentials it produces can be used to access resources within the scope using tsh or tctl with the identity file, or with ssh using the OpenSSH configuration files generated by tbot.