Requesting Access to Roles and Resources

Report an Issue

Is this page helpful?

How can we improve this page?

View as Markdown

If you cannot access a Teleport role or resource with your current Teleport permissions, you can create an Access Request to obtain elevated permissions for a limited time.

This page describes how to create Teleport Access Requests.

tip

In Teleport Enterprise accounts with Identity Governance enabled, it is possible to create Access Requests in the Teleport Web UI and Teleport Connect.

Access Requests can also be created in the Teleport Web UI and Teleport Connect. In the Teleport Web UI, navigate from the left sidebar to Identity Governance > Access Requests > New Request. In Teleport Connect, either open a new tab with cluster resources by clicking on the new tab button or click the Access Requests button in the top right.

Requesting access to roles

You can request access to one or more Teleport roles using the tsh request create command and the --roles flag, e.g.:

tsh request create --roles "dev,analyst"

The command above creates an Access Request for the dev and analyst roles.

For role requests in the Web UI, see Requesting Access.

Requesting access to Teleport cluster resources

In addition to Teleport roles, you can request access to individual Teleport resources, including resources within a Teleport-protected Kubernetes cluster.

To request access to a Teleport-protected infrastructure resource, you can search for possible resources, retrieve the ID of a resource to request access to, then create an Access Request for that resource ID.

tip

In the Teleport Web UI, you can view the resources you can request access to by navigating to Resources in the sidebar.

1. Search for a resource to request access to:

   tsh request search --kind=node

   Set node to one of the following resource kinds:

   • node
   • kube_cluster
   • kube_resource
   • db
   • app
   • windows_desktop

2. Determine the ID of the resource to request access to. Resource IDs have the following format:

   /CLUSTER_NAME/KIND/RESOURCE_NAME
   

   For example, assume that you have found the following Teleport-protected server to request access to:

   tsh request search --kind=node
   Name                                 Hostname Labels Resource ID------------------------------------ -------- ------ ----------------------------------------------00000000-0000-0000-0000-000000000000 myhost          /teleport.example.com/node/00000000-0000-00...

   While the resource ID on the right is clipped, you can use the format above to infer that it is the following:

   /teleport.example.com/node/00000000-0000-0000-0000-000000000000
   

3. Request access to the resource by running the following command, inputting the resource ID you found in the previous step:

   tsh request create --resource RESOURCE_ID

Requesting access with Resource Constraints

When creating a Resource Access Request, you can select specific SSH logins or AWS roles for each supported resource. The Teleport Web UI and tsh show these separately, as granted or requestable for each resource. When using the approved request, Teleport enforces both role permissions and your selections for the resource you're accessing.

Availability

Support for Resource Constraints requires Teleport v18.7.6 or later for AWS Console applications, and Teleport v19.0.0 or later for SSH nodes. These minimums apply to all Auth Service and Proxy Service instances and any Teleport agents providing access to the requested resource.

For request creation, the Teleport Web UI requires the same minimums. Alternatively, tsh and tctl clients v19.0.0 or later support either resource type. Teleport Connect can use approved requests with Resource Constraints, but does not support creating them.

Listing SSH logins and AWS roles

Run tsh request show-principals with a resource ID from your search results. This example lists SSH logins for a build server:

tsh request show-principals /teleport.example.com/node/27f0e510-7119-4ac3-ae50-4b8300ff405f
Resource:  /teleport.example.com/node/27f0e510-7119-4ac3-ae50-4b8300ff405fName:      27f0e510-7119-4ac3-ae50-4b8300ff405fHostname:  buildLabels:    env=production
Logins:  deploy  granted  admin  requestable  root   requestable
hint: tsh request create --resource '/teleport.example.com/node/27f0e510-7119-4ac3-ae50-4b8300ff405f?logins=admin,root' --reason "..."

For AWS Console applications, the command similarly lists each role's Amazon Resource Name (ARN).

Creating an Access Request

Append ?logins= and the desired logins to the resource ID. For example, to request admin on the build server:

tsh request create \    --resource '/teleport.example.com/node/27f0e510-7119-4ac3-ae50-4b8300ff405f?logins=admin' \    --reason "update deploy configuration"

For an AWS Console application, append ?role_arns= and the desired role ARN:

tsh request create \    --resource '/teleport.example.com/app/aws-console?role_arns=arn:aws:iam::123456789012:role/ReadOnly' \    --reason "investigating incident 123"

tsh request create waits for approval and activates the approved request automatically.

Quote the resource ID to preserve special characters, and separate multiple values with commas. Within values, escape commas, ampersands, and backslashes with a leading \.

Creating Access Requests from a file

Use --resource-file to read resources and optional Resource Constraints from a JSON file. In this example, a user requests the admin login on the build server with a file named request.json:

{
  "resources": [
    {
      "id": {
        "cluster": "teleport.example.com",
        "kind": "node",
        "name": "27f0e510-7119-4ac3-ae50-4b8300ff405f"
      },
      "constraints": {
        "version": "v1",
        "ssh": { "logins": ["admin"] }
      }
    }
  ]
}

The corresponding command is:

tsh request create --resource-file=request.json \    --reason "update deploy configuration"

For AWS Console applications, id.kind is app and id.name is the application name. Use a constraints.aws_console object with a role_arns array instead of constraints.ssh.

Omit constraints to request a resource without Resource Constraints. You can combine --resource-file with --resource to include additional resources.

The same request can be created from standard input with --resource-file=-:

tsh request create --resource-file=- \    --reason "update deploy configuration" < request.json

With --nowait --format=json, tsh request create prints the request as JSON without waiting for approval:

tsh request create --resource-file=request.json --nowait --format=json \    --reason "update deploy configuration"

After approval, the requester uses request-id from the command output to activate the request:

tsh login --request-id=request-id

Requesting access to Kubernetes resources

As with Teleport cluster resources, users can request access to a Kubernetes resource by running the following command, where resource-id is the ID of the resource:

tsh request create resource-id

Namespace-scoped resources

For Kubernetes namespaced resources, the resource-id is in the following format:

/TELEPORT_CLUSTER/kube:ns:NAMESPACED_PLURAL_KIND[.API_GROUP]/KUBE_CLUSTER/NAMESPACE/RESOURCE_NAME

The API_GROUP part is only required for resources that are part of the core Kubernetes group.

tip

You can run this command to list the namespaced Kubernetes resources, including their API groups:

kubectl api-resources --namespaced=true -o name --sort-by=name

For example, to request access to a pod called nginx-1 in the dev namespace, run the following command:

tsh request create --resource /teleport.example.com/kube:ns:pods/mycluster/dev/nginx-1

And to request access to a deployment called website in the prod namespace, run the following command:

tsh request create --resource /teleport.example.com/kube:ns:deployments.apps/mycluster/prod/website

For the NAMESPACED_PLURAL_KIND value you can use * to match all. For the API_GROUP, NAMESPACE and RESOURCE_NAME values, you can match ranges of characters by supplying a wildcard (*) or regular expression. Regular expressions must begin with ^ and end with $.

For example, to create a request to access all pods in all namespaces that match the regular expression /^nginx-[a-z0-9-]+$/, run the following command:

tsh request create --resource '/teleport.example.com/kube:ns:pods/mycluster/*/^nginx-[a-z0-9-]+$'

Cluster-scoped resources

For Kubernetes cluster-scoped resources, the resource-id is in the following format:

/TELEPORT_CLUSTER/kube:cw:CLUSTER_WIDE_PLURAL_KIND[.API_GROUP]/KUBE_CLUSTER/RESOURCE_NAME

The API_GROUP part is only required for resources that are part of the core kubernetes group.

tip

You can run this command to list the cluster-wide Kubernetes resources, including their API groups:

kubectl api-resources --namespaced=false -o name --sort-by=name

For example, to request access to a namespace called prod, run the following command:

tsh request create --resource /teleport.example.com/kube:cw:namespaces/mycluster/prod

Note that this will only grant access to the namespace resource itself, not to any namespaced resources within it.

For the CLUSTER_WIDE_PLURAL_KIND value you can use * to match all. For the API_GROUP and RESOURCE_NAME value, you can match ranges of characters by supplying a wildcard (*) or regular expression. Regular expressions must begin with ^ and end with $.

For example, to create a request to access all namespaces prefixed with dev that match the regular expression /^dev-[a-z0-9-]+$/, run the following command:

tsh request create --resource '/teleport.example.com/kube:cw:namespaces/mycluster/^dev-[a-z0-9-]+$'

Wildcard requests

You can request access to a namespace and all resources within it, as well as to all cluster-wide resources. To do so, you can use wildcards in the resource ID.

For cluster-wide resources, the kind format as described above is kube:cw:CLUSTER_WIDE_PLURAL_KIND[.API_GROUP]. To request access to all cluster-wide resources you can request access to kube:cw:*.*. Where the first * represents the kind, and the second * represents the api group.

For namespaced resources, the kind format is kube:ns:NAMESPACED_PLURAL_KIND[.API_GROUP]. To request access to all namespaced resources within a specific namespace, you can request access to kube:ns:*.*, where the first * represents the kind, and the second * represents the api group.

For example, to request access to the prod namespace (cluster-wide) all resources within it (i.e., namespaced), you can run the following command:

tsh request create \  --resource /teleport.example.com/kube:cw:namespaces/mycluster/prod \  --resource '/teleport.example.com/kube:ns:*.*/mycluster/prod/*'

Similarly, to request access to everything within a cluster, you can use the following command:

tsh request create \  --resource '/teleport.example.com/kube:cw:*.*/mycluster/*' \  --resource '/teleport.example.com/kube:ns:*.*/mycluster/*/*'

which is equivalent to:

tsh request create \  --resource /teleport.example.com/kube_cluster/mycluster

Search for Kubernetes resources

If a user has no access to a Kubernetes cluster, they can search the list of resources in the cluster by running the following command, replacing kube-cluster with the name of the Kubernetes cluster and namespace with the name of a Kubernetes namespace:

tsh request search \    --kind=kube_resource --kube-kind=pods --kube-api-group='' \    --kube-cluster=kube-cluster \    [--kube-namespace=namespace|--all-kube-namespaces]
Name               Namespace Labels    Resource ID-----------------  --------- --------- ----------------------------------------------------------nginx-deployment-0 default   app=nginx /teleport.example.com/kube:ns:pods/local/default/nginx-deployment-0nginx-deployment-1 default   app=nginx /teleport.example.com/kube:ns:pods/local/default/nginx-deployment-1
To request access to these resources, run> tsh request create \    --resource /teleport.example.com/kube:ns:pods/local/default/nginx-deployment-0 \    --resource /teleport.example.com/kube:ns:pods/local/default/nginx-deployment-1 \    --reason <request reason>

The list returned includes the name of the resource, the namespace it is in if applicable, its labels, and the resource ID. Resources included in the list are those that match the kubernetes_resources field in the user's search_as_roles. The user can then:

• Request access to the resources by running the command provided by the tsh request search command.
• Edit the command to request access to a subset of the resources.
• Use a custom request with wildcards or regular expressions.

tsh request search --kind=kube_resource --kube-kind=<kind> --kube-api-group=<api_group> works even if the user has no permissions to interact with the desired Kubernetes cluster, but the user's search_as_roles values must allow access to the cluster. If the user is unsure of the name of the cluster, they can run the following command to search it:

tsh request search --kind=kube_cluster
Name  Hostname Labels Resource ID----- -------- ------ ----------------------------------------local                 /teleport.example.com/kube_cluster/local