Resource Access Requests are currently in Preview.
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. Open-source Teleport 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, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 11.3.1, which you can download by visiting the customer portal.tctl versionTeleport v11.3.1 go1.19
tsh versionTeleport v11.3.1 go1.19
-
A Teleport Cloud account, which includes a running Auth Service and Proxy Service. If you do not have a Teleport Cloud account, visit the sign up page to begin your free trial.
-
The
tctl
admin tool andtsh
client tool version >= 11.2.1. To download these tools, visit the Downloads page.tctl versionTeleport v11.2.1 go1.19
tsh versionTeleport v11.2.1 go1.19
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 11.3.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 11.2.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
All teleport
instances in the cluster must be running Teleport v10.0.0
or
greater in order for Resource Access Requests to be properly enforced.
Older versions of teleport
will only do RBAC checks based on roles and will
not respect resource restrictions.
It is not recommended to enable Resource Access Requests by setting any
search_as_roles
until all teleport
instances in your cluster have been
upgraded to version 10.
Step 1/8. Create the requester role
This role allows the requester to search for resources accessible by the
access
role (all resources by default) and request access to them.
# requester.yaml
kind: role
version: v5
metadata:
name: requester
spec:
allow:
request:
search_as_roles:
- access
tctl create requester.yaml
Step 2/8. Create the reviewer role
This role allows the reviewer to approve all requests for the access
role.
# reviewer.yaml
kind: role
version: v5
metadata:
name: reviewer
spec:
allow:
review_requests:
roles:
- access
preview_as_roles:
- access
tctl create reviewer.yaml
Step 3/8. Grant the roles to users
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.
tctl users add alice --roles requester --logins alicetctl users add bob --roles reviewer
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
.
Step 4/8. 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-af66a6675738
bbb56211-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
.
Advanced filters and queries are supported, see our
filtering reference.
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 5/8. 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-a1d091a4ddab
Username: alice
Roles: access
Resources: ["/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 6/8. 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 request
tsh request show f406f5d8-3c2a-428f-8547-a1d091a4ddabRequest ID: f406f5d8-3c2a-428f-8547-a1d091a4ddab
Username: alice
Roles: access
Resources: ["/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
tsh 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 7/8. 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-a1d091a4ddab
Username: alice
Roles: access
Resources: ["/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=test
tsh ssh [email protected]iot:~ alice$
Step 8/8. 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
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 [email protected]ERROR: access denied to alice connecting to iot on cluster teleport.example.com
You do not currently have access to [email protected], attempting to request access.
Enter request reason: please
Creating request...
Request ID: ab43fc70-e893-471b-872e-ae65eb24fd76
Username: alice
Roles: access
Resources: ["/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
Create a role which can only access SSH nodes labeled env:staging
.
# staging-access.yaml
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
tctl create staging-access.yaml
Update the requester
and reviewer
roles to reference staging-access
instead of the default access
role.
# requester.yaml
kind: role
version: v5
metadata:
name: requester
spec:
allow:
request:
search_as_roles:
- staging-access
# Requires 2 approvals for the request.
thresholds:
- approve: 2
deny: 1
# reviewer.yaml
kind: role
version: v5
metadata:
name: reviewer
spec:
allow:
review_requests:
roles:
- staging-access
preview_as_roles:
- staging-access
tctl create -f requester.yamltctl create -f reviewer.yaml
The requester
will now only be able to search for or request access to
resources accessible by the staging-access
role.
Allow reviewers to see the hostnames of SSH Nodes
It is possible for a reviewer to view Resource Access Requests for SSH Nodes to which that reviewer does not have access. In this case, the reviewer will not be able to view the hostname of the requested node and they will only see the node's UUID.
To give the reviewer permission to view the Node hostname, use the
allow.review_requests.preview_as_roles
field in the reviewer's role, e.g.:
kind: role
spec:
allow:
review_requests:
preview_as_roles: [access]
This can often be set to the same value as allow.review_requests.roles
.
When any of the preview_as_roles
set for the reviewer would allow access to
the requested node, the hostname will be displayed in the Review Request page of
the Teleport Web UI.
Integrating with an external tool
With Teleport's Access Request plugins, users can request, approve, and deny access without leaving 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 |
Using TTLs with Access Requests
tsh request create
supports flags to control TTLs for the request and
elevated access. See the CLI
Reference for more
details.