# Requesting Access to Roles and Resources 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 guide explains to you how to use `tsh` 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. ## 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= ``` Substitute `--kind` with the kind of Teleport resource you would like to request access to. This can be one of the following: - `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_ADDRESS/TYPE/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 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` 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-0 nginx-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 ``` 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= --kube-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 ```