Scoped RBAC
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.
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
tctlandtshclients.Installing
tctlandtshclients-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:- Mac/Linux
- Windows - Powershell
TELEPORT_DOMAIN=teleport.example.com:443TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"$TELEPORT_DOMAIN = "teleport.example.com:443"$TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version -
Follow the instructions for your platform to install
tctlandtshclients:- Mac
- Windows - Powershell
- Linux
Download the signed macOS .pkg installer for Teleport, which includes the
tctlandtshclients:curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkgIn Finder double-click the
pkgfile to begin installation.dangerUsing 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.
curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zipUnzip the archive and move the `tctl` and `tsh` clients to your %PATH%
NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
All of the Teleport binaries in Linux installations include the
tctlandtshclients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our installation page.curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gztar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gzcd teleportsudo ./installTeleport binaries have been copied to /usr/local/bin
Connecting with TLS routing disabled
This guide's commands assume your Teleport cluster uses TLS routing (
proxy_listener_mode: multiplex), where thetctlandtshclients reach every Teleport service through the Proxy Service's web address on port443. 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:
-
tshcommands (e.g.,tsh login --proxy=...): continue using the Proxy Service web address on port3080(or443if behind a load balancer). Do not change these to port3025. -
Direct
tctlor Auth Service API commands: use port3025for 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
tctlandtshcommands using your current credentials.-
Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.
-
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 statusCluster teleport.example.com
Version 19.0.0-dev
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
On non-interactive environments: If you are running
tshandtctlas an AI agent, in a CI/CD environment, or similar, make sure theTELEPORT_IDENTITY_FILEenvironment variable is assigned to a valid file path with credentials for your cluster.tshandtctlread 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
tctlcommands with an identity file, you must pass the--auth-serverflag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address,tctlconnects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to3025if you are contacting the Auth Service directly withtctl:tctl status --auth-server=teleport.example.com:443For
tshcommands that read an identity file, you must pass the--proxyflag, which pointstshto the address of the Teleport Proxy Service:tsh status --proxy=teleport.example.comEnsure 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-serveror--proxyflags to all subsequenttctlandtshcommands.
tctl statuscommand, you can use your current credentials to run subsequenttctlcommands from your workstation. If you host your own Teleport cluster, you can also runtctlcommands 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=yesenvironment variable set. - The Auth Service must also have the
TELEPORT_UNSTABLE_AGENT_SCOPE_PIN=yesenvironment 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_roleresource for describing scoped permissions. - The
scoped_role_assignmentresource for assigning scoped roles and traits to users and Bots. - The
scoped_tokenresource 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, registering dynamic applications, and assigning scoped application access to users.
- Scoped AWS console apps through registering statically on an Application Service,
or through OIDC and AWS IAM Roles Anywhere integrations, which give scoped
users access to the AWS console through scoped applications.
These integrations are created with
tctlor Terraform, and the AWS setup scripts; the Web UI does not support them yet. - Scoped Access Lists that can be managed by scoped administrators, used to grant scoped roles and traits to groups of users, and synchronized with a SCIM provider.
- 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 logouttsh 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)tsh aws --app <app> ...(for AWS console applications backed by a scoped AWS OIDC integration)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)
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: - '{{internal.kubernetes_groups}}' labels: - name: '*' values: ['*'] resources: - kind: '*' namespace: '*' api_group: '*' name: '*' verbs: ['{{external.kubernetes_verbs}}'] ssh: logins: - '{{internal.logins}}' 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: ['*'] aws: role_arns: - arn:aws:iam::123456789012:role/example-readonly rules: - resources: [scoped_role, scoped_role_assignment, bot, bot_instance, access_list, app_server, integration, app] 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/basic traits: - scope: /examples/basic traits: - key: logins values: [ubuntu] - key: kubernetes_groups values: [cluster-admin] - key: kubernetes_verbs values: ['*']version: 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:
--scopesets 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-scopesets 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 lsScope 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:
--scopesets 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-scopesets 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 lsKube 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
Application Service instances that join with a scoped token can serve both statically
configured applications and dynamic app resources created in the same scope
(see Registering dynamic applications).
Applications discovered by the Teleport Discovery Service do 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 lsApplication 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-grafanaLogged 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
Registering dynamic applications
Application Service instances that joined with a scoped token pick up dynamic applications in their assigned scope,
using the resources label matchers in their configuration, the same way as unscoped Application
Service instances. An Application Service only serves dynamic applications in its own scope.
Add a resources matcher to the Application Service configuration:
app_service:
enabled: true
resources:
- labels:
"*": "*"
Create the application in the scope of the Application Service:
tctl create <<EOFkind: appversion: v3scope: /examples/basicmetadata: name: dynamic-grafana labels: env: stagingspec: uri: http://localhost:3000EOF
The Application Service registers it within a few seconds, with a derived public address:
tsh apps lsApplication Description Type Public Address Labels-------------------------------- ----------- ---- ------------------------------------- -----------/examples/basic::dynamic-grafana HTTP 7ttymu4ogft5frph5gxtgfdqvsnz37tl.t... env=staging
Manage scoped dynamic applications with their scope-qualified name, for example
tctl get app /examples/basic::dynamic-grafanatctl rm app /examples/basic::dynamic-grafana
Scoped applications cannot set a public_addr, required_apps, or dynamic
labels, and cannot be Azure or GCP cloud applications, stdio MCP servers, or
LLM applications. An AWS console application can reference an integration in
the same scope, as described in Scoped AWS access.
Application JWTs
Teleport signs a JWT for every request to an HTTP application and passes it to
the application in the Teleport-Jwt-Assertion header. For a scoped
application, the token's issuer and audience identify the application's scope
and name:
| Claim | Unscoped application | Scoped application |
|---|---|---|
iss | <cluster-name> ex. teleport.example.com) | <cluster-name><scope> ex. teleport.example.com/examples/basic |
aud | The application URI ex. http://localhost:3000) | <scope>/<app-name> ex. /examples/basic/scoped-grafana |
An application that validates the iss and aud claims therefore rejects
tokens minted for an application in another scope, or for another application
in the same scope.
Scoped AWS access
Scoped administrators can register a static AWS application on an Application Service. Applications registered statically here use the ambient credentials on the host machine.
AWS OIDC and AWS IAM Roles Anywhere integrations can be created in a scope. A scoped integration gives scoped users access to the AWS console and AWS CLI through scoped applications, and AWS can tell integrations in different scopes apart, so a role in one scope cannot be assumed with credentials issued for another, given correctly configured AWS settings.
- Only AWS OIDC and AWS IAM Roles Anywhere integrations can be scoped.
- A scoped application refers to its integration by scope-qualified name
(
/examples/basic::aws-oidc), and the integration must be in the same scope as the application. - The Web UI does not support scoped integrations yet. Create them with
tctl(or the Terraform provider) and set up AWS with the scripts and commands below.
To access and manage scoped integrations and their AWS console applications, a scoped
admin's role needs rules for the integration and app_server resources:
rules:
- resources: [integration, app_server]
verbs: [create, list, read, update, delete]
To use them, a scoped user's role lists the AWS roles they may assume:
app:
labels:
- name: '*'
values: ['*']
aws:
role_arns:
- arn:aws:iam::123456789012:role/example-readonly
AWS OIDC
Teleport signs a token for each AWS OIDC request and exchanges it with AWS STS
for credentials, using AssumeRoleWithWebIdentity. AWS trusts the token
because an IAM OIDC identity provider for the token's issuer exists in the AWS
account, and the integration's IAM role trusts that provider.
An unscoped integration uses the cluster's issuer,
https://teleport.example.com, so any role that trusts the cluster's IAM OIDC
provider accepts tokens minted for any unscoped integration. A scoped
integration uses its own issuer:
https://<proxy>/scope/<scope>/<integration-name>
For example, /examples/basic::aws-oidc uses
https://teleport.example.com/scope/examples/basic/aws-oidc. The Proxy Service
serves the OpenID configuration for each scoped integration at
<issuer>/.well-known/openid-configuration, with the cluster's signing keys.
Each scoped integration needs its own IAM OIDC provider, and its role trusts
only that provider, so AWS refuses a token minted for an integration in another
scope. Scoped AWS OIDC integrations do not support issuer_s3_uri.
Step 1/4. Create the IAM OIDC provider and role
Generate the setup script for the integration. Pass the scope URL-encoded in
the scope query parameter:
curl -o awsoidc-idp.sh 'https://teleport.example.com/webapi/scripts/integrations/configure/awsoidc-idp.sh?integrationName=aws-oidc&role=teleport-aws-oidc&scope=%2Fexamples%2Fbasic'
Run it with AWS credentials for the target account in AWS
CloudShell. The script downloads teleport and runs:
teleport integration configure awsoidc-idp \ --cluster=teleport.example.com \ --name=aws-oidc \ --role=teleport-aws-oidc \ --proxy-public-url=https://teleport.example.com/scope/examples/basic/aws-oidc
You can run this command directly instead of the script. It prints the changes and asks for confirmation, then creates:
- an IAM OIDC provider for
https://teleport.example.com/scope/examples/basic/aws-oidc, with the audiencediscover.teleport; - the IAM role
teleport-aws-oidc, whose trust policy allowssts:AssumeRoleWithWebIdentityonly from that provider:
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/teleport.example.com/scope/examples/basic/aws-oidc"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"teleport.example.com/scope/examples/basic/aws-oidc:aud": "discover.teleport"
}
}
}
Users access the AWS console as roles that the integration's role assumes.
Allow teleport-aws-oidc to assume them (sts:AssumeRole), and have each of
those roles trust arn:aws:iam::123456789012:role/teleport-aws-oidc.
Step 2/4. Create the integration
tctl create <<EOFkind: integrationsub_kind: aws-oidcversion: v1scope: /examples/basicmetadata: name: aws-oidcspec: aws_oidc: role_arn: arn:aws:iam::123456789012:role/teleport-aws-oidcEOF
Step 3/4. Register the AWS console application
Register an AWS console application that uses the integration.
tctl create <<EOFkind: app_serverversion: v3scope: /examples/basicmetadata: name: aws-oidcspec: host_id: some-host-id app: kind: app version: v3 scope: /examples/basic metadata: name: aws-oidc spec: uri: https://console.aws.amazon.com cloud: AWS integration: /examples/basic::aws-oidcEOF
The Proxy Service serves AWS console applications backed by an integration, so you do not need to start an Application Service.
Step 4/4. Access AWS
Log in to the scope, then to the application with one of the roles your scoped role allows:
tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.comtsh apps login /examples/basic::aws-oidc --aws-role arn:aws:iam::123456789012:role/example-readonlytsh aws --app /examples/basic::aws-oidc s3 ls
AWS IAM Roles Anywhere
With AWS IAM Roles Anywhere, the Auth Service signs a short-lived X.509
certificate with the cluster's AWS Roles Anywhere certificate authority and
exchanges it with AWS for credentials (CreateSession). A Roles Anywhere trust
anchor in the AWS account holds that certificate authority.
Every certificate the Auth Service signs for an integration carries the integration's identity as a URI subject alternative name (SAN):
| Integration | URI SAN |
|---|---|
Scoped, ex. /examples/basic::aws-ra | urn:teleport:awsra:/examples/basic:aws-ra |
Unscoped, ex. aws-ra | urn:teleport:awsra:aws-ra |
AWS exposes the SAN to IAM as the aws:PrincipalTag/x509SAN/URI condition key.
Every certificate chains to the same trust anchor, so a role that does not check
the SAN can be assumed with a certificate issued for any integration in any
scope. Require the SAN in the trust policy of every role a scoped integration uses to emulate scoping isolation. It is highly recommended that aws admins add the condition on all existing
AWS trust policies set up prior to scoping to ensure that they do not accidentally break scope isolation
on AWS.
Step 1/4. Create the trust anchor, sync profile, and sync role
Generate the setup script:
curl -o awsra-trust-anchor.sh 'https://teleport.example.com/webapi/scripts/integrations/configure/awsra-trust-anchor.sh?integrationName=aws-ra&integrationScope=%2Fexamples%2Fbasic&trustAnchor=teleport-aws-ra&syncProfile=teleport-aws-ra-sync&syncRole=teleport-aws-ra-sync'
Run it with AWS credentials for the target account. The script downloads
teleport and runs teleport integration configure awsra-trust-anchor, which
you can also run directly. Export the certificate authority with
tctl auth export --type=awsra:
teleport integration configure awsra-trust-anchor \ --cluster=teleport.example.com \ --name=aws-ra \ --scope=/examples/basic \ --trust-anchor=teleport-aws-ra \ --sync-profile=teleport-aws-ra-sync \ --sync-role=teleport-aws-ra-sync \ --trust-anchor-cert-b64="$(tctl auth export --type=awsra | base64 | tr -d '\n')"
Step 2/4. Create the target role and profile
Create the role users will assume. Its trust policy requires the trust anchor and the integration's URI SAN:
{
"Effect": "Allow",
"Principal": { "Service": "rolesanywhere.amazonaws.com" },
"Action": ["sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity"],
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:rolesanywhere:us-west-2:123456789012:trust-anchor/<trust-anchor-id>"
},
"StringEquals": {
"aws:PrincipalTag/x509SAN/URI": "urn:teleport:awsra:/examples/basic:aws-ra"
}
}
}
Then create a Roles Anywhere profile that lists the role.
aws rolesanywhere create-profile --name example-readonly --enabled \ --role-arns arn:aws:iam::123456789012:role/example-readonly
Step 3/4. Create the integration
Use the trust anchor and the sync profile and role from step 1.
tctl create <<EOFkind: integrationsub_kind: aws-raversion: v1scope: /examples/basicmetadata: name: aws-raspec: aws_ra: trust_anchor_arn: arn:aws:rolesanywhere:us-west-2:123456789012:trust-anchor/<trust-anchor-id> profile_sync_config: enabled: true profile_arn: arn:aws:rolesanywhere:us-west-2:123456789012:profile/<sync-profile-id> role_arn: arn:aws:iam::123456789012:role/teleport-aws-ra-sync profile_name_filters: ["example-readonly"]EOF
Teleport's profile syncer runs every few minutes. Once it has run, the application will appear in the integration's scope:
tctl get app_server /examples/basic::example-readonly-aws-ra
Step 4/4. Access AWS
Roles Anywhere applications hand credentials to the AWS CLI. Log in to the
scope and the application, then use the AWS profile that tsh configures,
named after the application:
tsh login --user=alice --scope=/examples/basic --proxy=teleport.example.comtsh apps login /examples/basic::example-readonly-aws-ra --aws-role arn:aws:iam::123456789012:role/example-readonlyaws --profile example-readonly-aws-ra s3 ls
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-84e3e6449756kind: 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-ac43a2e20f85kind: 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: v2tsh lsScope 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-66f14d8a2b2ekind: 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.comtsh lsScope Node Name Address Labels--------------- ------------ ------- -----------/examples/basic example-node Tunnel foo=bartsh 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 bobsuccessfully added user bob to access list /examples/basic::example-access-listtctl acl users add /examples/basic::example-access-list charliesuccessfully 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 textSubKind 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:
- An Access List can only grant scoped roles defined in a scope that is equal to or an ancestor of the list's scope.
- 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.
- 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.
- 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.
- A scoped Access List (or an unscoped list that grants any scoped roles or traits) 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:
- It can only grant scoped roles defined in
/examples/basicor/examplesor/. - It can only grant scoped roles at
/examples/basicor/examples/basic/**. - It can only grant scoped traits at
/examples/basicor/examples/basic/**. - It can only have member Access Lists that are unscoped or have scope
/examples/basicor/examplesor/. - It can only have owner Access Lists that are unscoped or have scope
/examples/basicor/examplesor/. - It may not contain any member or owner requirements.
Manage scoped Access Lists with SCIM
SCIM integrations can synchronize membership for scoped Access Lists. To avoid name and title collisions between scopes, configure the SCIM plugin to use scope-qualified names:
tctl edit plugin/scim-generic
In the editor, keep the plugin's existing connector settings and other fields
unchanged. Under spec.Settings.scim, add the following block to set
access_list.name_encoding to scope_qualified:
access_list:
name_encoding: scope_qualified
When scope-qualified encoding is enabled, the SCIM integration exposes both
scoped and unscoped Access Lists of type scim:
- An unscoped Access List keeps its bare SCIM group ID and display name. For
example, an Access List named
engineeringwith titleEngineeringis exposed with IDengineeringand display nameEngineering. - A scoped Access List uses its scope-qualified name as the SCIM group ID and
its scope-qualified title as the display name. For example, an Access List
named
engineeringwith titleEngineeringin/examples/basicis exposed with ID/examples/basic::engineeringand display name/examples/basic::Engineering.
The SCIM provider must use the scope-qualified display name when matching a
scoped group to an Access List. If name_encoding is unset, the integration
retains its legacy behavior and exposes only unscoped Access Lists.
See the SCIM integration guide for general setup instructions.
Infrastructure as Code
Scoped Roles, Scoped Role Assignments, Scoped Tokens, Kubernetes clusters, Integrations, Access Lists, Access List Members, Bots, and Workload Identities can be managed with Teleport's IaC tooling.
The Teleport Terraform provider supports these resources:
teleport_access_listteleport_access_list_memberteleport_botteleport_integrationteleport_kube_clusterteleport_scoped_roleteleport_scoped_role_assignmentteleport_scoped_tokenteleport_workload_identity
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. This assignment also grants
a scoped logins trait that can be used in the /staging::staging-ssh-access
role using {{internal.logins}}:
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
traits:
- scope: /staging
traits:
- key: logins
values: [ubuntu]
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: ['{{internal.kubernetes_groups}}']
labels:
- name: '*'
values: ['*']
resources:
- kind: '*'
api_group: '*'
namespace: '*'
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
tctlandtshclients.Installing
tctlandtshclients-
Determine the version of your Teleport cluster. The
tctlandtshclients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/findand use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:- Mac/Linux
- Windows - Powershell
TELEPORT_DOMAIN=teleport.example.com:443TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"$TELEPORT_DOMAIN = "teleport.example.com:443"$TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version -
Follow the instructions for your platform to install
tctlandtshclients:- Mac
- Windows - Powershell
- Linux
Download the signed macOS .pkg installer for Teleport, which includes the
tctlandtshclients:curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkgIn Finder double-click the
pkgfile to begin installation.dangerUsing 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.
curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zipUnzip the archive and move the `tctl` and `tsh` clients to your %PATH%
NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP.
Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\<username>) instead.
All of the Teleport binaries in Linux installations include the
tctlandtshclients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our installation page.curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gztar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gzcd teleportsudo ./installTeleport binaries have been copied to /usr/local/bin
Connecting with TLS routing disabled
This guide's commands assume your Teleport cluster uses TLS routing (
proxy_listener_mode: multiplex), where thetctlandtshclients reach every Teleport service through the Proxy Service's web address on port443. 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:
-
tshcommands (e.g.,tsh login --proxy=...): continue using the Proxy Service web address on port3080(or443if behind a load balancer). Do not change these to port3025. -
Direct
tctlor Auth Service API commands: use port3025for the Auth Service gRPC listener:tctl status --auth-server=teleport.example.com:3025
-
-
A Linux host where you will install the Teleport Kubernetes Service.
tipOur
teleport-kube-agentHelm 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
tctlandtshcommands using your current credentials.-
Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.
-
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 statusCluster teleport.example.com
Version 19.0.0-dev
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
On non-interactive environments: If you are running
tshandtctlas an AI agent, in a CI/CD environment, or similar, make sure theTELEPORT_IDENTITY_FILEenvironment variable is assigned to a valid file path with credentials for your cluster.tshandtctlread 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
tctlcommands with an identity file, you must pass the--auth-serverflag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address,tctlconnects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to3025if you are contacting the Auth Service directly withtctl:tctl status --auth-server=teleport.example.com:443For
tshcommands that read an identity file, you must pass the--proxyflag, which pointstshto the address of the Teleport Proxy Service:tsh status --proxy=teleport.example.comEnsure 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-serveror--proxyflags to all subsequenttctlandtshcommands.
If you can connect to the cluster and run the
tctl statuscommand, you can use your current credentials to run subsequenttctlcommands from your workstation. If you host your own Teleport cluster, you can also runtctlcommands 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.
-
Remove any existing Teleport binaries on your system:
sudo rm -f /usr/local/bin/{tsh,teleport,tctl,tbot,fdpass-teleport,teleport-update} -
Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).
-
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:
- Package Manager
- TAR Archive
- No 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 teleportsudo 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.
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, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport:
sudo teleport install systemd -o /etc/systemd/system/teleport.servicesudo systemctl enable teleportsudo 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.
On the host where you will run the Teleport Kubernetes Service, start Teleport:
sudo teleport start --config=/etc/teleport.yaml
Teleport runs in the foreground and outputs logs for the services it is running.
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_NAMESwitched 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-contextsAssign 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.yamlkubernetes 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 lsKube 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 myclusterLogged 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 lsKube Cluster Name Labels Scope Selected ----------------- ------------------------------------ -------------- -------- mycluster env=test teleport.dev/origin=dynamic /examples/kube *
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::myclusterkubernetes cluster "/examples/kube::mycluster" has been deleted
This will unregister the Kubernetes cluster from Teleport:
tsh kube lsKube Cluster Name Labels Scope Selected----------------- ------ ----- --------
Scoped traits
Scoped traits can be assigned alongside scoped roles using scoped role assignments or Access Lists. They are similarly assigned at a designated scope and interact with scoped roles through the same template system supported by unscoped roles.
Templated roles
Templates in scoped roles use the same {{internal.<key>}} and
{{external.<key>}} syntax as unscoped roles. They behave identically to their
unscoped counterparts with two exceptions:
- The
externalnamespace can not be used withinternalkeys (e.g.logins,kubernetes_groups) - Trait values can not be accessed using any namespaces other than
internalandexternal. This differs from unscoped roles that implicitly treat unrecognized namespaces asexternalunder the hood. The special{{user.metadata.name}}template can still be be used to interpolate the username for the logged in user.
The following example defines a scoped role with templated values for
spec.ssh.logins, spec.kube.groups, and spec.kube.resources:
kind: scoped_role
version: v1
scope: /examples
metadata:
name: templated-user
spec:
assignable_scopes:
- /examples
- /examples/basic
ssh:
logins: ['{{internal.logins}}']
labels:
- name: '*'
values: ['*']
kube:
groups: ['{{internal.kubernetes_groups}}']
labels:
- name: '*'
values: ['*']
resources:
- kind: '*'
api_group: '*'
namespace: '*'
name: '*'
verbs: ['{{external.kubernetes_verbs}}']
Assigning scoped traits
Scoped traits can be assigned using scoped role assignments:
kind: scoped_role_assignment
sub_kind: dynamic
version: v1
scope: /examples
spec:
user: alice
assignments:
- role: /examples::templated-user
scope: /examples/basic
traits:
- scope: /examples/basic
traits:
- key: logins
values: [ubuntu]
- key: kubernetes_groups
values: [cluster-admin]
- key: kubernetes_verbs
values: ['*']
This assignment grants logins=ubuntu, kubernetes_groups=cluster-admin, and
kubernetes_verbs=* at the /examples/basic scope. Traits follow scope
isolation rules in that they can only apply to roles being evaluated at or
below their assigned scope. This means that a trait assigned at
/examples/basic will not be visible when evaluating a role assigned at
/examples or /examples/other.
Scoped role and trait assignments each have a Scope of Origin and a Scope of
Effect. The Scope of Origin is where the roles or traits are assigned from and
is determined by the scoped_role_assignment.scope field. This dictates the
authority of the assignment relative to others. The Scope of Effect is where
roles or traits are effective at and is determined by the scope field of each
assignments or traits entry;
scoped_role_assignment.spec.assignments[].scope and scoped_role_assignment.spec.traits[].scope.
Scoped traits are aggregated hierarchically based on their Scope of Origin and Scope of Effect. For example, the same set of traits can be achieved even if some of them are assigned at a higher Scope of Effect:
kind: scoped_role_assignment
sub_kind: dynamic
version: v1
scope: /examples
spec:
user: alice
assignments:
- role: /examples::templated-user
scope: /examples/basic
traits:
- scope: /examples
traits:
- key: logins
values: [ubuntu]
- scope: /examples/basic
traits:
- key: kubernetes_groups
values: [cluster-admin]
- key: kubernetes_verbs
values: ['*']
When evaluating the assigned templated-user role at /examples/basic, the
trait map used still includes logins, kubernetes_groups, and
kubernetes_verbs. Trait values are also additive, so if we were to assign the
following:
traits:
- scope: /examples
traits:
- key: logins
values: [ubuntu]
- scope: /examples/basic
traits:
- key: kubernetes_groups
values: [cluster-admin]
- key: kubernetes_verbs
values: ['*']
- key: logins
values: [root]
Then the resulting logins trait would contain [root, ubuntu]. Notice that
the trait value assigned at a more specific Scope of Effect appears earlier in
the value list. This is enforced behavior that ensures trait value order is
always deterministic. In the rare case that value order matters during an
access decision, the most specifically scoped trait value "wins". However, this
ordering only applies within a Scope of Origin. Trait values assigned from
a higher authority Scope of Origin will always appear before those assigned in
lower authority scopes. For example:
kind: scoped_role_assignment
sub_kind: dynamic
version: v1
scope: /examples
spec:
user: alice
traits:
- scope: /examples
traits:
- key: logins
values: [ubuntu]
- scope: /examples/basic
traits:
- key: kubernetes_groups
values: [cluster-admin]
- key: kubernetes_verbs
values: ['*']
---
kind: scoped_role_assignment
sub_kind: dynamic
version: v1
scope: /examples/basic
spec:
user: alice
assignments:
- role: /examples::templated-user
scope: /examples/basic
traits:
- scope: /examples/basic
traits:
- key: logins
values: [root]
When evaluating the templated-user role assigned at /examples/basic, all
three traits are still present and logins still contains both ubuntu and
root. However, their ordering is now [ubuntu, root]. Despite root
appearing in a more specific Scope of Effect (e.g. /examples/basic), the
ubuntu value appears in the scoped_role_assignment originating from
/examples. Which is a higher authority scope than the /examples/basic scope
assigned to the second scoped_role_assignment.
Access Lists
Scoped traits can be assigned from scoped Access Lists:
kind: access_list
version: v1
scope: /examples
metadata:
name: access-list-with-traits
spec:
title: "Access List with traits"
owners:
- name: bob
membership_kind: MEMBERSHIP_KIND_USER
grants:
scoped_roles:
- scope: /examples/basic
role: /examples::templated-user
scoped_traits:
- scope: /examples/basic
traits:
kubernetes_groups: [cluster-admin]
kubernetes_verbs: ['*']
logins: [ubuntu]
audit:
recurrence:
frequency: 6months
This Access List will materialize into the equivalent scoped_role_assignment
for all members of the list:
kind: scoped_role_assignment
sub_kind: materialized
version: v1
scope: /examples
spec:
user: alice
assignments:
- role: /examples::templated-user
scope: /examples/basic
traits:
- scope: /examples/basic
traits:
- key: logins
values: [ubuntu]
- key: kubernetes_groups
values: [cluster-admin]
- key: kubernetes_verbs
values: ['*']
Note that the Access List's scope is the Scope of Origin for the resulting assignment. Because Access Lists are materialized into scoped role assignments, all of the same rules for aggregating and applying scoped traits apply.
Unscoped traits
Unscoped traits are also supported by scoped roles. They can still be defined on Teleport Users, within an IdP, or the result of a Login Rule. Unscoped traits are treated as the "root" of the trait map when evaluating a scoped role. Scoped traits can append to keys defined by unscoped traits, but the unscoped trait values will always appear first. This is consistent with trait values from higher authority Scopes of Origin being preferred over lower scope traits. Critically, unscoped traits will always be applied to every scoped role evaluation. If a certain trait should only be used within a specific set of scopes, that trait should never be assigned as an unscoped trait.