Skip to main content

Identity Governance is available only with Teleport Enterprise. Start your free trial.

Start your free trial
Version: 18.x

Role Access Requests

Report an Issue

Teleport's Just-in-time Access Requests allow users to request access to additional roles in order to elevate their privileges. Requests can be escalated via ChatOps or anywhere else via our flexible Authorization Workflow API.

Prerequisites​

  • A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using 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.

  • Check that you can connect to your Teleport cluster and verify that you can run tctl and tsh commands using your current credentials.

    1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username.

    2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not.

      In an interactive shell: Run the following command. By default, this triggers a multi-factor authentication prompt:

      tsh login --proxy=teleport.example.com --user=[email protected]
      tctl status
      Cluster  teleport.example.com
      Version  18.10.0
      CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

      On non-interactive environments: If you are running tsh and tctl as an AI agent, in a CI/CD environment, or similar, make sure the TELEPORT_IDENTITY_FILE environment variable is assigned to a valid file path with credentials for your cluster. tsh and tctl read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you set up Machine ID to provision one automatically.

      When executing tctl commands with an identity file, you must pass the --auth-server flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, tctl connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to 3025 if you are contacting the Auth Service directly with tctl:

      tctl status --auth-server=teleport.example.com:443

      For tsh commands that read an identity file, you must pass the --proxy flag, which points tsh to the address of the Teleport Proxy Service:

      tsh status --proxy=teleport.example.com

      Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file:

      export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}"

      Add the --auth-server or --proxy flags to all subsequent tctl and tsh commands.

    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

RBAC Setup​

In this example, we will define three roles:

  • contractor: users with this role can request elevated access to the dba role
  • dba: this role grants access to databases
  • approver: users with this role can approve requests for access to the dba role

Contractor Role

Users with this role can request access to the dba role.

kind: role
version: v5
metadata:
  name: contractor
spec:
  allow:
    request:
      roles: ['dba']

DBA Role

This role grants access to databases.

kind: role
version: v5
metadata:
  name: dba
spec:
  allow:
    db_labels:
      '*': '*'
  options:
    # Only allows the contractor to use this role for 1 hour from time of request.
    max_session_ttl: 1h

Approver Role

This role allows users to approve requests for the dba role.

kind: role
version: v5
metadata:
  name: approver
spec:
  allow:
    # `review_requests` permits the listed roles to be approved
    review_requests:
      roles:
      - 'dba'
Requires Teleport Enterprise

Roles containing a review_requests rule can only be used in Teleport Enterprise. In Teleport Community Edition, Access Requests must be approved by an admin running tctl on the Auth Service.

Requesting Access​

To request access to one or more roles, navigate to the Access Requests page. You can find this page by selecting Resources on the side bar, expanding the Access Requests menu, and selecting New Request.

From here, the dropdown will allow you to request access to roles or to specific resources. Select roles in this dropdown and you will be presented with a list of roles you are permitted to request access to.

Click ADD TO REQUEST to include a role in the pending request.

Note: Access Requests must either contain roles or a set of specific resources. You can not mix the two. For more information on how to request access to specific resources, see the Resource Access Requests Guide.

When all desired roles have been added, click PROCEED TO REQUEST, where you can review and submit the request.

Submit Request

While we recommend using the web UI to create Access Requests, users can also request access with the tsh CLI:

Reviewing Access Requests via the Web UI​

Reviewers can see a list of open requests by navigating to Identity Governance > Access Requests > Needs Review in the web UI.

warning

Granting access to a role with the ability to edit other roles could allow a user to permanently upgrade their privileges. When reviewing requests, it's important to carefully consider the role(s) being requested and what permissions will be applied to the user if the request is approved.

Reviewing Access Requests via tsh​

Teleport Enterprise users with appropriate permissions can also approve requests with the tsh command line:

tsh request review --approve <request-id>

Using an approved Access Request​

Once a request has been approved, the requestor can elevate their access for both command-line workflows and web UI workflows.

For command-line use, the requestor should log in using the approved request ID:

log in with an approved access request
tsh login --request-id=bc8ca931-fec9-4b15-9a6f-20c13c5641a9

In the web UI, the requestor can open their request on the Review Requests page and click ASSUME ROLES to gain access to additional roles. Note: role-based Access Requests are additive. The user will have access to their standard role set in addition to the roles granted by the request.

A banner will appear at the top of the page while the approved Access Request is active. When elevated access is no longer necessary, click Switch Back to revert to the original set of roles.

Next Steps​

Automatically request access for SSH​

Once you have configured Role Access Requests, tsh ssh is able to automatically create a Role Access Request for you when access is denied, allowing you to skip the tsh request search and tsh request create steps. If more than one role would grant access to the target node, you will be prompted to select a role to request.

tsh ssh --request-mode role alice@iot
ERROR: 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.
Choose role to request [node-access, node-access-alt]: node-accessEnter request reason: pleaseCreating request...
Waiting for request approval...
Approval received, reason="okay"Getting updated certificates...
iot:~ alice$

Note that in order to make a Role Access Request this way, the role you request access with must have search_as_roles set so you can read the node you want to ssh into.

# requester.yaml
kind: role
version: v5
metadata:
  name: requester
spec:
  allow:
    request:
      roles:
        - node-access
      search_as_roles:
        # does not need to match roles, just needs to be able to access nodes
        # that you want to ssh into
        - access

Integrate 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.

IntegrationTypeSetup Instructions
SlackMessagingSet up Slack
MattermostMessagingSet up Mattermost
Microsoft TeamsMessagingSet up Microsoft Teams
JiraProject BoardSet up Jira
PagerDutyScheduleSet up PagerDuty
EmailMessagingSet up email
DiscordMessagingSet up Discord
OpsgenieIncident ManagementSet up Opsgenie
ServiceNowWorkflowSet up ServiceNow
DatadogIncident ManagementSet up Datadog

Learn how to configure Access Requests​

See the Access Request Configuration guide for a detailed description of all the options you can configure to set up a just-in-time Access Request workflow for your organization.

Set up Access Lists​

Access Lists enable you to assign privileges to groups of users for a fixed period of time. Learn more about Access Lists in the documentation.