Skip to main content

Scoped RBAC

Report an Issue

Scopes let you divide a Teleport cluster into a hierarchy of isolated administrative boundaries. Use scopes when you want to delegate management of one part of a cluster without granting access to unrelated resources.

How it works​

A scope is a path-like attribute (for example /staging/west or /prod) that Teleport attaches to supported resources, permission grants, and issued credentials. Permissions assigned at a scope apply to resources within that scope and its descendants, but not to parent or sibling scopes. Scopes are an attribute, not an object, so a scope path does not need to be created before resources or permissions are assigned to it.

Cluster administrators create scoped roles, assign those roles to users at a specific scope, and create scoped join tokens for Agents. When a user logs in with a scope, Teleport issues credentials pinned to that scope. Scoped RBAC checks then authorize access only to resources in that scope or one of its descendants. Agents that join with a scoped token register their supported resources at the token's assigned scope.

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.

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.

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.
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 accessible at a hostname with a valid TLS certificate. 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.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • 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@example.com 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@example.com
      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.
  • The Auth Service must also have the TELEPORT_UNSTABLE_AGENT_SCOPE_PIN=yes environment variable set before you use scoped tokens to join Agent roles other than SSH Services (node) and Bots. This includes scoped Kubernetes Services and Application Services.

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, registering dynamic clusters, and assigning scoped Kubernetes access to users.
  • Basic scoped Application access, including joining Application Services at a scope and assigning scoped application 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.
  • Scoped Workload Identity resources for issuing SPIFFE credentials to workloads within a scope.

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
  • tsh scopes ls (lists the scopes at which the user has assigned privileges)
  • 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)
  • tsh apps ls (lists applications available at the current scope)
  • tsh apps login <app> (for applications 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, connect to Kubernetes clusters, and access applications within /examples (replace ubuntu with your desired OS login):

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

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
Scope           Node Name    Address Labels--------------- ------------ ------- -----------/examples/basic 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​

Kubernetes Clusters discovered by the Teleport Discovery Service are not supported by scopes at this time.

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.

Joining a scoped Application Service​

Only statically configured applications served by Application Services support joining with scopes. Dynamic application registration, including those discovered by the Teleport Discovery Service, does 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 an Application Service at the desired scope:

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

Copy the printed invite token to /tmp/scoped-app-token on the Application Service host, then create the following /etc/teleport.yaml:

version: v3
teleport:
  join_params:
    token_name: "/tmp/scoped-app-token"
    method: token
  proxy_server: "teleport.example.com:443"
auth_service:
  enabled: false
proxy_service:
  enabled: false
ssh_service:
  enabled: false
app_service:
  enabled: true
  apps:
  - name: scoped-grafana
    uri: "http://localhost:3000"
    labels:
      env: "staging"
      tier: "mfa"

Start Teleport with this configuration:

sudo teleport start --config=/etc/teleport.yaml

Once the instance has joined, the scoped admin can list it:

tsh apps ls
Application                     Description Type Public Address                        Labels------------------------------- ----------- ---- ------------------------------------- --------------------/examples/basic::scoped-grafana             HTTP lv7pgada3xgarg2rvk7gm4xgmx7nto6j.t... env=staging,tier=mfa

Note that the scope is prefixed, followed by ::, and then the application name. Scoped applications require the user to refer to each application by their scope-qualified name when interacting with tsh.

The public address is also always derived for a scoped application. Users will not be able to define their own public address in order to disallow cross-scope access.

Log in to the application:

tsh apps login /examples/basic::scoped-grafana
Logged into app /examples/basic::scoped-grafana. Example curl command:
curl \  --cert "/Users/teleport-user/.tsh/keys/teleport.example.com/teleport-app/teleport.example.com/@lv7pgada3xgarg2rvk7gm4xgmx7nto6j.crt" \  --key "/Users/teleport-user/.tsh/keys/teleport.example.com/teleport-app/teleport.example.com/@lv7pgada3xgarg2rvk7gm4xgmx7nto6j.key" \  https://lv7pgada3xgarg2rvk7gm4xgmx7nto6j.teleport.example.com

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: /examples/basic::019fb4b9-969d-7f36-b910-84e3e6449756:ZGQ4ZjQ0MTVlNjQ3MmJjZDEzOThhMmU2MzYyNTFjNmYThis token will expire in 480 minutes.
Run this on the new node to join the cluster:
> teleport start \   --roles=node \   --token=/examples/basic::019fb4b9-969d-7f36-b910-84e3e6449756:ZGQ4ZjQ0MTVlNjQ3MmJjZDEzOThhMmU2MzYyNTFjNmY \   --auth-server=proxy.example.com:443

Inspect the token to confirm the immutable labels:

tctl get scoped_token /examples/basic::019fb4b9-969d-7f36-b910-84e3e6449756
kind: scoped_tokenmetadata:  expires: "2026-03-14T04:51:29.109545Z"  name: 019fb4b9-969d-7f36-b910-84e3e6449756scope: /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 /examples/basic::edff1d38-bbcb-4a21-b38d-ac43a2e20f85
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: /examples/basic::019fb4c0-5b15-7c9a-bf91-66f14d8a2b2e:NjNmOTI0YjRmOWI2YTNlMDc1YTU4Y2M4M2Q0ZTgzZWMThis 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 /examples/basic::019fb4c0-5b15-7c9a-bf91-66f14d8a2b2e
kind: scoped_tokenmetadata:  expires: "2026-03-14T05:11:26.341373Z"  name: 019fb4c0-5b15-7c9a-bf91-66f14d8a2b2escope: /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: /examples/basic::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
Scope           Node Name    Address Labels--------------- ------------ ------- -----------/examples/basic 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 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                                                          Assignee      Assigns------------ ----------------------------------------------------------- ------------- --------------------------------------------------materialized /examples/basic::acl-4ezohtYllrk-gbWjn0hj_npCNwhujMurruDLRg user: charlie /examples/basic::example-access -> /examples/basicmaterialized /examples/basic::acl-XMyMVGoNZopPQ9WxuZ5RH6GM5FPHVwLSTFUsBg user: 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, Scoped Tokens, Kubernetes clusters, Access Lists, Access List Members, Bots, and Workload Identities 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::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
        - read
        - create
        - update
        - delete
    - resources:
        - scoped_token
      verbs:
        - list
        - read
        - secrets
        - 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::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::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: /staging::my-scoped-bot
  bound_keypair:
    registration_secret: <secret fetched from "tctl get scoped_token /staging::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.

Scoped SPIFFE​

The standard workload_identity resource supports the scope field. When set, the Workload Identity is considered scoped. Scoped Workload Identities can be created, read, updated, and deleted by scope admins through scoped roles and scoped role assignments, and can be used by scoped Bots to issue SPIFFE credentials to workloads. A scoped Workload Identity cannot be defined in the root scope /. See the Workload Identity resource reference for the available fields.

SPIFFE ID structure​

A scoped Workload Identity must specify a SPIFFE ID that encodes the scope in which it is defined. The path of the SPIFFE ID consists of three sections:

  • The scope section: segments that match the scope in which the Workload Identity is defined.
  • The separator segment: /_/.
  • The administratively-defined section: one or more segments freely chosen by the administrator.

For example, a Workload Identity defined in /staging may specify the SPIFFE ID /staging/_/payments/api. Workloads are then issued SVIDs with the following SPIFFE ID:

spiffe://example.teleport.sh/staging/_/payments/api

The following rules apply to the SPIFFE ID of a scoped Workload Identity:

  • The scope section must exactly match the scope in which the Workload Identity is defined. It cannot be an ancestor or descendant of that scope. This means the scope responsible for a SPIFFE ID can always be determined from the ID alone, and admins of one scope cannot issue SPIFFE IDs that appear to belong to another scope.
  • The scope section must be immediately followed by the separator segment.
  • The administratively-defined section must contain at least one segment, and must not itself contain the separator segment, so that a scoped SPIFFE ID contains exactly one separator.
  • Templating within the SPIFFE ID is supported. These rules are enforced against the rendered SPIFFE ID at issuance time, so template attributes cannot be used to escape the scope.

Granting issuance to a scoped Bot​

Issuance is controlled by the workload_identity section of a scoped role, which selects the Workload Identities that the role permits issuance with by label. Issuance additionally requires the read verb (and, when issuing by label selector, list) for the workload_identity resource in the role's rules.

Configuring tbot in scoped mode​

In scoped mode, tbot supports the workload-identity-x509, workload-identity-jwt, and workload-identity-api services. When selecting a scoped Workload Identity by name, use its scope-qualified name, for example /staging::staging-payments-api.

Scoped SPIFFE example​

The following example builds on the scoped MWI example above, granting the scoped Bot /staging::my-scoped-bot the ability to issue SPIFFE SVIDs. It assumes the scope administrator's role also grants write access to the workload_identity resource.

As the scope administrator, create a scoped Workload Identity:

kind: workload_identity
version: v1
metadata:
  name: staging-payments-api
  labels:
    app: payments
scope: /staging
spec:
  spiffe:
    id: /staging/_/payments/api

Create a scoped role permitting issuance with Workload Identities labeled app: payments, and assign it to the Bot:

kind: scoped_role
version: v1
metadata:
  name: staging-spiffe-issuer
scope: /staging
spec:
  assignable_scopes:
    - /staging
  workload_identity:
    labels:
      - name: app
        values: [payments]
  rules:
    - resources: [workload_identity]
      verbs: [list, read]
---
kind: scoped_role_assignment
version: v1
metadata:
  name: 9c41d3be-72af-4d9e-8e5a-1f3b6c0d47e1
scope: /staging
sub_kind: dynamic
spec:
  bot: /staging::my-scoped-bot
  assignments:
    - role: /staging::staging-spiffe-issuer
      scope: /staging

Add a Workload Identity service to the tbot configuration from the previous example, selecting the Workload Identity by its scope-qualified name:

services:
  - type: workload-identity-api
    listen: unix:///opt/machine-id/workload.sock
    selector:
      name: /staging::staging-payments-api

Workloads connecting to the SPIFFE Workload API socket are issued SVIDs with the following SPIFFE ID:

spiffe://example.teleport.sh/staging/_/payments/api

Kubernetes resource RBAC​

When defining scoped roles, the resources list provided in scoped_role.spec.kube must be defined in order for the role to grant access to a Kubernetes cluster. When the intent is to fully rely on Kubernetes' builtin RBAC rules, a wildcard entry must be defined:

kind: scoped_role
metadata:
  name: kube-access
scope: /examples
spec:
  assignable_scopes:
    - /examples
  kube:
    groups: [cluster-admin]
    labels:
      - name: '*'
        values: ['*']
    resources:
      - kind: '*'
        namespace: '*'
        api_group: '*'
        name: '*'
        verbs: ['*']
version: v1

This is notably opposite to the behavior of unscoped Teleport roles which provide wildcard access by default when kubernetes_resources are left undefined. Scoped roles aim to be explicit and deny by default which is incompatible with the unscoped behavior.

Dynamic Kubernetes cluster registration​

With dynamic Kubernetes cluster registration, you can manage the Kubernetes clusters connected to your Teleport cluster without needing to modify the configuration file of an individual Kubernetes Service instance.

Dynamic Kubernetes cluster registration is useful when you have deployed multiple Kubernetes Service instances or need to regularly reconfigure access to Kubernetes clusters in your infrastructure.

In this guide, you will set up dynamic Kubernetes cluster registration, then create, list, update, and delete Kubernetes clusters via tctl.

How it works​

The Teleport Kubernetes Service proxies traffic from Teleport users to a Kubernetes API server so you can take advantage of passwordless authentication, role-based access controls, audit logging, and other Teleport features in order to manage access to Kubernetes.

In this step, you will install the Teleport Kubernetes Service on a Linux host and configure it to access any Kubernetes cluster you register with your Teleport cluster.

Prerequisites​

  • A running Teleport cluster accessible at a hostname with a valid TLS certificate. 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.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

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

  • A Linux host where you will install the Teleport Kubernetes Service.

    tip

    Our teleport-kube-agent Helm chart does not support dynamic Kubernetes cluster registration.

  • A Kubernetes cluster to join to your Teleport cluster. You must have permissions to create namespaces, secrets, service accounts, cluster roles, and cluster role bindings in the cluster.

  • 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@example.com 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@example.com
      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.

Step 1/3. Set up the Teleport Kubernetes Service​

This step shows you how to install the Teleport Kubernetes Service on a Linux server.

Get a join token​

Establish trust between your Teleport cluster and your new Kubernetes Service instance by creating a scoped join token:

tctl scoped tokens add --type=kube --scope=/examples/kube --assign-scope=/examples/kube --ttl=1h --format=text
/examples/kube::abcd123-insecure-do-not-use-this

Copy the token and keep it somewhere safe so you can use it when running the Teleport Kubernetes Service.

Install the Teleport Kubernetes Service​

Install the Teleport Kubernetes Service on your Linux host:

To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. This script is served by your Teleport cluster's Proxy Service and automatically selects the correct version, edition, and installation mode to match your cluster.

  1. Remove any existing Teleport binaries on your system:

    sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update}

  2. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

  3. Run your cluster's install script:

    curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash

Configure the Teleport Kubernetes Service​

On the host where you will run the Teleport Kubernetes Service, run the following command to create a base configuration for your Teleport instance, assigning example.teleport.sh:443 to the host and port of your Teleport Proxy Service or Teleport Cloud tenant and join-token to the join token we created earlier:

sudo teleport configure \--proxy=example.teleport.sh:443 \--roles=kube \--token=join-token \-o file

Edit your configuration file at /etc/teleport.yaml to include the following:

kubernetes_service:
  enabled: true
  resources:
  - labels:
      "*": "*"

This configuration enables your Kubernetes Service instance to connect to any Kubernetes clusters you register with your Teleport cluster within the same scope. This is because the resources[0].labels field includes the wildcard pattern ("*": "*"), which allows this Kubernetes Service instance to connect to Kubernetes cluster resources with any label key or value. The Kubernetes Service instance's certificate will encode the scope assigned by its join token and be used to ensure only same-scope Kubernetes clusters are visible and registered.

Selectively watching Kubernetes clusters

You can configure a Kubernetes Service instance to watch for a subset of Kubernetes clusters by including specific label keys and values instead of wildcard characters:

resources:
- labels:
    "env": "prod"
    "region": "us-east-2"
- labels:
    "env": "test"
    "region": "us-west-1"

For the Kubernetes Service to register a cluster, any of the items in resources must match the cluster's labels. For an item in resources to match, all of the labels entries within that item must match the cluster's labels.

For example, a cluster with the labels env:prod and region:us-west-1 would not match the configuration above, since it only matches the env:prod label in the first resources item and the region:us-west-1 label in the second resources item.

However, a cluster with env:test and region:us-west-1 would match, since it matches both labels given in the second resources item.

When you create dynamic Kubernetes cluster resources later in this guide, you can assign them labels to ensure that only specific Kubernetes Service instances will watch for them.

Run the Teleport Kubernetes Service​

Start the Teleport Kubernetes Service. The instructions depend on how you installed the Teleport Kubernetes Service and whether your system supports systemd:

Configure the Teleport Kubernetes Service to start automatically when the host boots up by creating a systemd service for it. On the host where you will run the Teleport Kubernetes Service, enable and start Teleport:

sudo systemctl enable teleport
sudo systemctl start teleport

You can check the status of the Teleport Kubernetes Service with systemctl status teleport and view its logs with journalctl -fu teleport.

Step 2/3. Authorize your user​

To enable dynamic Kubernetes cluster registration in Teleport, you will need to authorize your user to access the Kubernetes clusters you want to register with Teleport. We will configure this access in this step, both in Teleport and on your Kubernetes cluster.

Allow access to your Kubernetes cluster​

Ensure that you are in the correct Kubernetes context for the cluster you would like to enable access to.

Retrieve all available contexts:

kubectl config get-contexts

Switch to your context, replacing CONTEXT_NAME with the name of your chosen context:

kubectl config use-context CONTEXT_NAME
Switched to context CONTEXT_NAME

The scoped role you will create in the next section allows your Teleport user access to Kubernetes as the viewers group. Configure the viewers group in your Kubernetes cluster to have the built-in view ClusterRole. When your Teleport user accesses the cluster, the Teleport Kubernetes Service impersonates the viewers group and proxies the requests.

Create a file called viewers-bind.yaml with the following contents:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: viewers-crb
subjects:
- kind: Group
  # Bind the group "viewers", corresponding to the group we assign in the
  # scoped role below.
  name: viewers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  # "view" is a default ClusterRole that grants read-only access to resources.
  # See: https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles
  name: view
  apiGroup: rbac.authorization.k8s.io

Apply the ClusterRoleBinding with kubectl:

kubectl apply -f viewers-bind.yaml

Authorize your user to manage Kubernetes clusters​

Teleport tracks scoped Kubernetes clusters in your infrastructure via dynamic kube_cluster resources. To manage access to Kubernetes clusters with Teleport, your user will need permissions to manage these resources.

Create a scoped role definition called kube-manager.yaml with the following content:

kind: scoped_role
metadata:
  name: kube-manager
scope: /examples
spec:
  assignable_scopes:
    - /examples/kube
  kube:
    groups: [viewers]
    labels:
      - name: '*'
        values: ['*']
    resources:
      - kind: '*'
        namespace: '*'
        api_group: '*'
        name: '*'
        verbs: ['*']
  rules:
    - resources: [kube_cluster]
      verbs:
        - create
        - list
        - read
        - secrets
        - update
        - delete
version: v1

Create the scoped role:

tctl create -f kube-manager.yaml

Assign the role to your user:

tctl create <<EOFkind: scoped_role_assignmentsub_kind: dynamicscope: /examplesspec:  user: user  assignments:    - role: /examples::kube-manager      scope: /examples/kubeversion: v1EOF

Log in to the /examples/kube scope so the scoped role assignment is active for the following tctl commands:

tsh login --user=user --scope=/examples/kube --proxy=example.teleport.sh:443

Step 3/3. Manage dynamic Kubernetes cluster resources​

Now that your Teleport user has permissions to manage scoped Kubernetes cluster resources, we will show you how to create, list, update, and delete them.

Create a kubeconfig​

In this section, you will create a Kubernetes Config resource, or kubeconfig, that your Teleport cluster will use to authenticate to your Kubernetes cluster.

When you signed into Teleport earlier in this guide, tsh may have changed your Kubernetes context to one based on your Teleport cluster, so make sure you update your Kubernetes context to match the cluster you would like to connect to Teleport:

kubectl config get-contexts
Assign CONTEXT_NAME to your chosen context
kubectl config use-context CONTEXT_NAME

On your workstation, download Teleport's get-kubeconfig.sh script, which you will use to generate the kubeconfig:

curl -OL \https://raw.githubusercontent.com/gravitational/teleport/v19.0.0-dev/examples/k8s-auth/get-kubeconfig.sh

The script creates a service account for the Teleport Kubernetes Service that can get Kubernetes pods as well as impersonate users, groups, and other service accounts. The Teleport Kubernetes Service uses this service account to manage access to resources in your Kubernetes cluster. The script also ensures that there is a Kubernetes Secret in your cluster to store service account credentials.

get-kubeconfig.sh creates a namespace called teleport for the resources it deploys, though you can choose a different name by assigning the TELEPORT_NAMESPACE environment variable in the shell where you run the script.

After creating resources, get-kubeconfig.sh writes a new kubeconfig to a file called kubeconfig in the directory where you run the script.

Run the get-kubeconfig.sh script:

bash get-kubeconfig.sh

The script is successful if you see this message:

Done!

Ignore the script's instructions to copy the generated kubeconfig file to the Teleport Proxy Service. In the next section, we will show you how to use the kubeconfig file when creating a dynamic kube_cluster resource.

Create a Kubernetes cluster resource​

Define a scoped kube_cluster resource with the following content in a file called kube_cluster.yaml:

kind: kube_cluster
version: v3
scope: /examples/kube
metadata:
  name: mycluster
spec:
  kubeconfig: |

The spec.kubeconfig field in the snippet above begins a multi-line string. Below, you will include the contents of the kubeconfig file as its value.

Since spec.kubeconfig must be a base64-encoded string, convert the kubeconfig file to base64, then indent it and add it to the kube_cluster.yaml resource definition using the following command:

printf "    %s\n" "$(cat kubeconfig | base64 | tr -d '\n')" >> kube_cluster.yaml

This command also removes any newlines added to the middle of the base64-encoded string before writing it to the kube_cluster resource definition.

Add labels to your kube_cluster

You can add labels to the kube_cluster resource, allowing you to manage access to specific clusters from your Teleport roles or Kubernetes Service instances.

Dynamic, scoped Kubernetes clusters only support static labels, which are key/value pairs. This example defines the env=prod and team=dev labels:

kind: kube_cluster
version: v3
scope: /examples/kube
metadata:
  name: mycluster
  labels:
    env: prod
    team: dev
spec:
  kubeconfig: KUBECONFIG

To create the kube_cluster resource, run the following command:

tctl create kube_cluster.yaml
kubernetes cluster "/examples/kube::mycluster" has been created

Access your new Kubernetes cluster​

Instances of the Teleport Kubernetes Service watch for newly created or updated kube_cluster resources within their assigned scope. When you create the kube_cluster resource, any Kubernetes Service instances you have configured in that scope to track that cluster's labels will register that cluster and enable access to it via Teleport.

As a result, you should now see the cluster you registered above when you run tsh kube ls:

tsh kube ls
 Kube Cluster Name Labels                      Scope          Selected ----------------- --------------------------- -------------- -------- mycluster         teleport.dev/origin=dynamic /examples/kube *

The teleport.dev/origin=dynamic label indicates that the cluster was registered dynamically.

You can also log in to the cluster you just registered:

tsh kube login mycluster
Logged into kubernetes cluster "mycluster". Try 'kubectl version' to test theconnection.

List Kubernetes cluster resources​

You can list kube_cluster resources with the following command:

tctl get kube_clusters

Update a Kubernetes cluster resource​

To update the kube_cluster resource you created earlier, execute the following command to open the resource as it exists on the Auth Service's backend in your text editor:

tctl edit kube_clusters /examples/kube::mycluster

Edit the resource to add a label to your kube_cluster:

  kind: kube_cluster
  scope: /examples/kube
  metadata:
    id: 9999999999999999999
    labels:
      teleport.dev/origin: dynamic
+     env: test
    name: mycluster
  spec:
    aws: {}
    azure: {}
    kubeconfig: KUBECONFIG
  version: v3

Save and close the file in your editor to apply your changes.

You should now see the updated labels:

tsh kube ls
 Kube Cluster Name Labels                               Scope          Selected ----------------- ------------------------------------ -------------- -------- mycluster         env=test teleport.dev/origin=dynamic /examples/kube *
warning

If the updated kube_cluster resource's labels no longer match the ones a Teleport Kubernetes Service instance is configured to watch, the instance will unregister and stop proxying the Kubernetes cluster.

Delete Kubernetes cluster resources​

To delete the kube_cluster resource you created earlier, run the following command:

tctl rm kube_clusters /examples/kube::mycluster
kubernetes cluster "/examples/kube::mycluster" has been deleted

This will unregister the Kubernetes cluster from Teleport:

tsh kube ls
Kube Cluster Name Labels Scope Selected----------------- ------ ----- --------