Resource Access Requests
With Teleport Resource Access Requests, users can request access to specific resources without needing to know anything about the roles or RBAC controls used under the hood. The Access Request API makes it easy to dynamically approve or deny these requests.
Just-in-time Access Requests are a feature of Teleport Enterprise. Teleport Community Edition users can get a preview of how Access Requests work by requesting a role via the Teleport CLI. Full Access Request functionality, including Resource Access Requests and an intuitive and searchable UI are available in Teleport Enterprise.
Prerequisites
-
A running Teleport cluster version 18.0.0 or above. If you do not have one, read Get Started with Teleport or set up a demo environment.
-
The
tctl
andtsh
clients.Installing
tctl
andtsh
clients- Mac
- Windows - Powershell
- Linux
Download the signed macOS .pkg installer for Teleport, which includes the
tctl
andtsh
clients:curl -O https://cdn.teleport.dev/teleport-18.0.0.pkgIn Finder double-click the
pkg
file 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-v18.0.0-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
tctl
andtsh
clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our installation page.curl -O https://cdn.teleport.dev/teleport-v18.0.0-linux-amd64-bin.tar.gztar -xzf teleport-v18.0.0-linux-amd64-bin.tar.gzcd teleportsudo ./installTeleport binaries have been copied to /usr/local/bin
The
tctl
andtsh
clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at/v1/webapi/ping
and use a JSON query tool to obtain your cluster version:curl https://example.teleport.sh/v1/webapi/ping | jq -r '.server_version'18.0.0
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email@example.com to your Teleport username:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=email@example.comtctl statusCluster teleport.example.com
Version 18.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/6. Grant roles to users
The built-in requester
and reviewer
roles have permissions to, respectively,
open and review Access Requests. Grant the requester
and reviewer
roles to
existing users, or create new users to test this feature. Make sure the
requester has a valid login
so that they can view and access SSH nodes.
For the rest of the guide we will assume that the requester
role has been
granted to a user named alice
and the reviewer
role has been granted to a
user named bob
.
-
Assign the
requester
role to a user namedalice
:Assign the
requester
role toalice
by running the appropriate commands for your authentication provider:- Local User
- GitHub
- SAML
- OIDC
-
Retrieve your local user's roles as a comma-separated list:
ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') -
Edit your local user to add the new role:
tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},requester" -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Open your
github
authentication connector in a text editor:tctl edit github/github -
Edit the
github
connector, addingrequester
to theteams_to_roles
section.The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.
Here is an example:
teams_to_roles: - organization: octocats team: admins roles: - access + - requester
-
Apply your changes by saving closing the file in your editor.
-
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
saml
configuration resource:tctl get --with-secrets saml/mysaml > saml.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to thesaml.yaml
file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. -
Edit
saml.yaml
, addingrequester
to theattributes_to_roles
section.The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - requester
-
Apply your changes:
tctl create -f saml.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Retrieve your
oidc
configuration resource:tctl get oidc/myoidc --with-secrets > oidc.yamlNote that the
--with-secrets
flag adds the value ofspec.signing_key_pair.private_key
to theoidc.yaml
file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. -
Edit
oidc.yaml
, addingrequester
to theclaims_to_roles
section.The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.
Here is an example:
claims_to_roles: - name: "groups" value: "my-group" roles: - access + - requester
-
Apply your changes:
tctl create -f oidc.yaml -
Sign out of the Teleport cluster and sign in again to assume the new role.
-
Repeat these steps to assign the
reviewer
role to a user namedbob
.
Consider defining custom roles to limit the scope of a requester or reviewer's permissions. Read the Access Request Configuration guide for available options.
Step 2/6. Search for resources
First, log in as alice
.
tsh login --proxy teleport.example.com --user alice
Notice that tsh ls
returns an empty list, because alice
does not have access to any resources by default.
tsh lsNode Name Address Labels--------- ------- ------
Then try searching for all available ssh nodes.
tsh request search --kind nodeName Hostname Labels Resource ID------------------------------------ ----------- ------------ ------------------------------------------------------b1168402-9340-421a-a344-af66a6675738 iot test=test /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738bbb56211-7b54-4f9e-bee9-b68ea156be5f node test=test /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f
To request access to these resources, run> tsh request create --resource /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738 --resource /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \ --reason <request reason>
You can search for resources of kind node
, kube_cluster
, db
, app
, and
windows_desktop
. Teleport also supports searching and requesting access to
resources within Kubernetes clusters with kind kube_resource
.
Advanced filters and queries are supported. See our filtering reference for more information.
Try narrowing your search to a specific resource you want to access.
tsh request search --kind node --search iotName Hostname Labels Resource ID------------------------------------ ----------- ------------ ------------------------------------------------------b1168402-9340-421a-a344-af66a6675738 iot test=test /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738
To request access to these resources, run> tsh request create --resource /teleport.example.com/node/b1168402-9340-421a-a344-af66a6675738 \ --reason <request reason>
Step 3/6. Request access to a resource
Copy the command output by tsh request search
in the previous step, optionally filling in a request reason.
tsh request create --resource /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \ --reason "responding to incident 123"Creating request...Request ID: f406f5d8-3c2a-428f-8547-a1d091a4ddabUsername: aliceRoles: accessResources: ["/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f"]Reason: "responding to incident 123"Reviewers: [none] (suggested)Status: PENDING
hint: use 'tsh login --request-id=<request-id>' to login with an approved request
Waiting for request approval...
The command will automatically wait until the request is approved.
Step 4/6. Approve the Access Request
First, log in as bob
.
tsh login --proxy teleport.example.com --user bob
Then list, review, and approve the Access Request.
tsh request lsID User Roles Resources Created At (UTC) Status------------------------------------ ----- ------ --------------------------- ------------------- -------f406f5d8-3c2a-428f-8547-a1d091a4ddab alice access ["/teleport.example.... [+] 23 Jun 22 18:25 UTC PENDING
[+] Requested resources truncated, use `tsh request show <request-id>` to view the full list
hint: use 'tsh request show <request-id>' for additional details use 'tsh login --request-id=<request-id>' to login with an approved requesttsh request show f406f5d8-3c2a-428f-8547-a1d091a4ddabRequest ID: f406f5d8-3c2a-428f-8547-a1d091a4ddabUsername: aliceRoles: accessResources: ["/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f"]Reason: "responding to incident 123"Reviewers: [none] (suggested)Status: PENDING
hint: use 'tsh login --request-id=<request-id>' to login with an approved requesttsh request review --approve f406f5d8-3c2a-428f-8547-a1d091a4ddabSuccessfully submitted review. Request state: APPROVED
Check out our Access Request Integrations to notify the right people about new Access Requests.
Step 5/6. Access the requested resource
alice
's tsh request create
command should resolve now that the request has been approved.
tsh request create --resource /teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f \ --reason "responding to incident 123"Creating request...Request ID: f406f5d8-3c2a-428f-8547-a1d091a4ddabUsername: aliceRoles: accessResources: ["/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f"]Reason: "responding to incident 123"Reviewers: [none] (suggested)Status: PENDING
hint: use 'tsh login --request-id=<request-id>' to login with an approved request
Waiting for request approval...
Approval received, getting updated certificates...
> Profile URL: https://teleport.example.com Logged in as: alice Active requests: f406f5d8-3c2a-428f-8547-a1d091a4ddab Cluster: teleport.example.com Roles: access, requester Logins: alice Kubernetes: disabled Allowed Resources: ["/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f"] Valid until: 2022-06-23 22:46:22 -0700 PDT [valid for 11h16m0s] Extensions: permit-agent-forwarding, permit-port-forwarding, permit-pty
alice
can now view and access the node.
tsh lsNode Name Address Labels--------- --------- ---------iot [::]:3022 test=testtsh ssh alice@iotiot:~ alice$
Step 6/6. Resume regular access
While logged in with a Resource Access Request, users will be blocked from access to any other resources.
This is necessary because their certificate now contains an elevated role,
so it is restricted to only allow access to the resources they were specifically approved for.
Use the tsh request drop
command to "drop" the request and resume regular access.
tsh request drop
When you drop an Access Request, Teleport issues a new user certificate. The new certificate retains the expiration of the previous certificate. Once your session expires and you reauthenticate to Teleport, you receive a user certificate with your user's originally configured time to live.
Next Steps
Automatically request access for SSH
Once you have configured Resource Access Requests,
tsh ssh
is able to automatically create a Resource Access Request for you when access is denied,
allowing you to skip the tsh request search
and tsh request create
steps.
tsh ssh alice@iotERROR: access denied to alice connecting to iot on cluster teleport.example.com
You do not currently have access to alice@iot, attempting to request access.
Enter request reason: pleaseCreating request...Request ID: ab43fc70-e893-471b-872e-ae65eb24fd76Username: aliceRoles: accessResources: ["/teleport.example.com/node/bbb56211-7b54-4f9e-bee9-b68ea156be5f"]Reason: "please"Reviewers: [none] (suggested)Status: PENDING
hint: use 'tsh login --request-id=<request-id>' to login with an approved request
Waiting for request approval...
Approval received, reason="okay"Getting updated certificates...
iot:~ alice$
Restrict the resources a user can request access to
In this guide, we showed you how to enable a user to search for resources to
request access to. To do so, we assigned the user a Teleport role with the
search_as_roles
field set to the preset access
role.
You can impose further restrictions on the resources a user is allowed to
search by assigning search_as_roles
to a more limited role. Below, we will
show you which permissions you must set to restrict a user's ability to search
for different resources.
To restrict access to a particular resource using a role similar to the ones
below, edit one of the user's roles so the search_as_roles
field includes the
role you have created.
For full details on how to use Teleport roles to configure RBAC, see the Access Controls Reference.
node
You can restrict access to searching node
resources by assigning values to the
node_labels
field in the spec.allow
or spec.deny
fields. The following
role allows access to SSH Service instances with the env:staging
label.
kind: role
version: v5
metadata:
name: staging-access
spec:
allow:
node_labels:
env: staging
logins:
- '{{internal.logins}}'
options:
# Only allows the requester to use this role for 1 hour from time of request.
max_session_ttl: 1h
kube_cluster
You can restrict access to searching kube_cluster
resources by assigning
values to the kubernetes_labels
field in the spec.allow
or spec.deny
fields.
The following role allows access to Kubernetes clusters with the env:staging
label:
kind: role
metadata:
name: kube-access
version: v8
spec:
allow:
kubernetes_labels:
env: staging
kubernetes_resources:
- kind: '*'
namespace: '*'
name: '*'
api_group: '*'
deny: {}
Kubernetes resources
You can restrict access to Kubernetes resources by assigning values to the
kubernetes_resources
field in the spec.allow
or spec.deny
fields.
The following role allows access to Kubernetes pods with the name nginx
in any
namespace, and all pods in the dev
namespace:
kind: role
metadata:
name: kube-access
version: v8
spec:
allow:
kubernetes_labels:
'*': '*'
kubernetes_resources:
- kind: pods
namespace: '*'
name: 'nginx*'
api_group: ''
- kind: pods
namespace: dev
name: '*'
api_group: ''
kubernetes_groups:
- viewers
deny: {}
Restrict Access Requests to specific Kubernetes resource kinds
The request.kubernetes_resources
field allows you to restrict what kinds of Kubernetes
resources a user can request access to. Configuring this field to any value will disallow
requesting access to the entire Kubernetes cluster.
If the request.kubernetes_resources
field is not configured, then a user can request access
to any Kubernetes resources, including the entire Kubernetes cluster.
The following role allows users to request access to Kubernetes namespaces.
Requests for Kubernetes resources other than pods
will not be allowed.
kind: role
metadata:
name: requester-kube-access
version: v8
spec:
allow:
request:
search_as_roles:
- kube-access
kubernetes_resources:
- kind: pods
api_group: ''
The following role allows users to request access only to Kubernetes deployments and/or pods.
kind: role
metadata:
name: requester-kube-access
version: v8
spec:
allow:
request:
search_as_roles:
- kube-access
kubernetes_resources:
- kind: deployments
api_group: apps
- kind: pods
api_group: ''
The following role allows users to request access to any specific Kubernetes resources.
kind: role
metadata:
name: requester-kube-access
version: v8
spec:
allow:
request:
search_as_roles:
- kube-access
kubernetes_resources:
- kind: '*'
api_group: '*'
The request.kubernetes_resources
field only restricts what
kind
/ api_group
of Kubernetes resource requests are allowed.
To control Kubernetes access to these resources see
Kubernetes Resources
section for more details.
db
You can restrict access to searching db
resources by assigning values to the
db_labels
field in the spec.allow
or spec.deny
fields.
The following role allows access to databases with the env:dev
or
env:staging
labels:
kind: role
version: v5
metadata:
name: developer
spec:
allow:
db_labels:
env: ["dev", "staging"]
# Database account names this role can connect as.
db_users: ["viewer", "editor"]
db_names: ["*"]
app
You can restrict access to searching app
resources by assigning values to the
app_labels
field in the spec.allow
or spec.deny
fields.
The following role allows access to all applications except for those in
env:prod
:
kind: role
version: v5
metadata:
name: dev
spec:
allow:
app_labels:
"*": "*"
deny:
app_labels:
env: "prod"
windows_desktop
You can restrict access to searching windows_desktop
resources by assigning
values to the windows_desktop_labels
field in the spec.allow
or spec.deny
fields.
The following role allows access to all Windows desktops with the
env:dev
or env:staging
labels.
kind: role
version: v4
metadata:
name: developer
spec:
allow:
windows_desktop_labels:
env: ["dev", "staging"]
windows_desktop_logins: ["{{internal.windows_logins}}"]
Request access to Kubernetes resources
Teleport users can request access to a Kubernetes resources 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.
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.
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-]+$'
Using cluster-scoped resource requests requires the role under search_as_roles
to have the correct
permissions for the cluster-scoped resource. This is an example of the required permissions to
request access only to the namespace prod
(does not include any resources within it):
kind: role
version: v8
spec:
allow:
kubernetes_resources:
- kind: namespaces
api_group: ''
name: prod
verbs:
- '*'
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_clusterName Hostname Labels Resource ID----- -------- ------ ----------------------------------------local /teleport.example.com/kube_cluster/local
Integrating with an external tool
With Teleport's Access Request plugins, users can manage Access Requests from within your organization's existing messaging and project management solutions.
Integration | Type | Setup Instructions |
---|---|---|
Slack | Messaging | Set up Slack |
Mattermost | Messaging | Set up Mattermost |
Microsoft Teams | Messaging | Set up Microsoft Teams |
Jira | Project Board | Set up Jira |
PagerDuty | Schedule | Set up PagerDuty |
Messaging | Set up email | |
Discord | Messaging | Set up Discord |
OpsGenie | Incident Management | Set up OpsGenie |
ServiceNow | Workflow | Set up ServiceNow |
Datadog | Incident Management | Set up Datadog |
Next Steps
- Learn more about Access Lists