Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gravitational/teleport/llms.txt

Use this file to discover all available pages before exploring further.

Teleport’s Just-in-Time (JIT) Access Requests let you implement the principle of least privilege at every layer. Users operate day-to-day with a minimal role set, and when they need elevated access — to a production database, a privileged Kubernetes namespace, or an admin role — they submit a time-bound request that one or more approvers must review. Access Requests support two patterns:
  • Role Requests: A user requests one or more Teleport roles (e.g., dba, k8s-admin).
  • Resource Requests: A user requests access to a specific infrastructure resource (a particular server, database, or Kubernetes cluster).

​
How Access Requests work

1

Define requestable roles

A Teleport administrator creates the roles a user can request and the role that permits approval. Users are assigned a base role that explicitly names the roles they are allowed to request.
2

User submits a request

The user runs tsh request create or uses the Teleport Web UI to submit a request, optionally providing a reason and specifying a maximum duration for elevated access.
3

Approvers are notified

Reviewers receive a notification — via the Web UI, Slack, PagerDuty, or another plugin — and examine the request. Approvers can inspect which resources the requested role would grant access to before approving.
4

Request is approved or denied

An approver runs tctl requests approve or clicks Approve in the Web UI. Teleport can require multiple approvals before granting access.
5

User assumes elevated access

The user re-issues their login with the approved request ID to obtain short-lived certificates that include the elevated roles. Roles are additive — the user keeps their base roles and gains the requested ones.
6

Elevated access expires automatically

At expiry, the elevated role is revoked. The user’s certificates no longer include the requested roles, and they return to their baseline permissions without any manual action from an administrator.

​
RBAC setup

The following example defines three roles: contractor, dba, and approver.

​
The requesting role

Users assigned contractor can request the dba role: 
kind: role
version: v5
metadata:
  name: contractor
spec:
  allow:
    request:
      roles:
        - dba
      # Optional: require the user to provide a reason
      reason:
        mode: required

​
The target role

The dba role grants broad database access but enforces a short session TTL: 
kind: role
version: v5
metadata:
  name: dba
spec:
  allow:
    db_labels:
      '*': '*'
    db_names:
      - '*'
    db_users:
      - '*'
  options:
    # Elevated access expires 4 hours after the request is approved
    max_session_ttl: 4h

​
The approver role

Users with the approver role can review requests for the dba role: 
kind: role
version: v5
metadata:
  name: approver
spec:
  allow:
    review_requests:
      roles:
        - dba
Apply all three roles: 
$ tctl create contractor.yaml
$ tctl create dba.yaml
$ tctl create approver.yaml
Assign roles to users: 
$ tctl users update alice --set-roles=contractor,access
$ tctl users update bob --set-roles=approver,access

​
Submitting a request

Users can create requests from the CLI: 
# Request a single role with a reason
$ tsh request create --roles=dba --reason='deploying hotfix to prod DB'

# Request multiple roles with a max duration
$ tsh request create --roles=dba,k8s-admin \
    --reason='incident response' \
    --max-duration=2h
Or request access to a specific resource: 
$ tsh request search --kind=db --search=prod-postgres
$ tsh request create --resources=db/prod-postgres \
    --reason='investigating slow query'
Teleport prints a request ID you can share with approvers: 
Creating request to role(s) [dba]...
Request ID: bc8ca931-fec9-4b15-9a6f-20c13c5641a9
Reason:     deploying hotfix to prod DB
Waiting for request approval...

​
Approving and denying requests

Approvers can act from the CLI or the Teleport Web UI (Identity Governance → Access Requests → Needs Review). 
# List pending requests
$ tctl requests ls

# Approve a request with an optional reason
$ tctl requests approve bc8ca931-fec9-4b15-9a6f-20c13c5641a9 \
    --reason='confirmed with on-call, looks good'

# Deny a request
$ tctl requests deny bc8ca931-fec9-4b15-9a6f-20c13c5641a9 \
    --reason='not on-call rotation, please page the DBA'

​
Using an approved request

Once approved, the requesting user re-logs in with the request ID to obtain elevated certificates: 
$ tsh login --request-id=bc8ca931-fec9-4b15-9a6f-20c13c5641a9
# > Roles: access, dba
# > Valid until: 2024-01-15 18:00:00 UTC [valid for 4h0m0s]
In the Web UI, navigate to Access Requests → Review Requests, open the approved request, and click Assume Roles. A banner at the top of the UI indicates that elevated access is active. Click Switch Back to revert to your baseline roles before expiry.

​
Auto-expiry of elevated access

Elevated access expires automatically based on the lowest value of:
  • request.max_duration set in the requesting role
  • The --max-duration flag passed at request creation time
  • The options.max_session_ttl of the requested role
  • The remaining TTL in the user’s current Teleport session
No administrator action is needed to revoke access — when the certificates expire, the elevated roles are gone.
Teleport does not allow users to approve their own requests. This is enforced by the Auth Service regardless of role configuration.

​
Access Request plugins

Teleport provides notification and approval plugins so reviewers can act from the tools they already use:

Slack

Receive request notifications and approve/deny from Slack.

PagerDuty

Route access requests to on-call engineers automatically.

Jira

Create Jira issues for each request and approve from the ticket.

Opsgenie

Notify and approve requests via Opsgenie alerts.

Microsoft Teams

Receive and approve requests in Teams channels.

ServiceNow

Integrate request approvals into ServiceNow workflows.
Plugins connect to the Teleport Auth Service using machine certificates and listen for new Access Request events. See the plugin documentation for setup instructions for each provider.

​
Review thresholds

You can require multiple approvals before a request is granted — for example, two out of three members of the dba-approvers group must approve: 
kind: role
version: v7
metadata:
  name: contractor
spec:
  allow:
    request:
      roles:
        - dba
      thresholds:
        - approve: 2
          deny: 1

​
Next steps

RBAC

Learn how allow/deny rules and role templates work.

SSO

Map IdP group membership to requestable Teleport roles.

MFA

Require MFA at login and per session for elevated roles.

Device Trust

Enforce that only registered devices can access sensitive resources.

Build docs developers (and LLMs) love

Get started for freeTalk to us