Fork me on GitHub

Teleport

Teleport Role Access Requests

Improve

With Teleport, users can request additional roles via a third-party communication service. 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 and tsh client tool version >= 10.3.1, which you can download by visiting the customer portal.

    tctl version

    Teleport v10.3.1 go1.18

    tsh version

    Teleport v10.3.1 go1.18

  • 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 and tsh client tool version >= 10.2.2. To download these tools, visit the Downloads page.

    tctl version

    Teleport v10.2.2 go1.18

    tsh version

    Teleport v10.2.2 go1.18

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 10.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 status

Cluster myinstance.teleport.sh

Version 10.2.2

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Role Access Requests Setup

Contractor Role This role allows the contractor to request the role DBA.

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

DBA Role This role can be requested by the contractor.

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

Admin Role This role allows the admin to approve the contractor's request.

kind: role
version: v5
metadata:
  name: admin
spec:
  allow:
    # `review_requests` permits the listed roles to be approved
    review_requests:
      roles:
      - 'dba'
    rules:
    # `access_request` is part of Access Workflows introduced in 4.2
    # `access_request` should only be given to Teleport Admins.
    # For a full list of allow-rules, see
    # https://goteleport.com/docs/access-controls/reference/
    - resources:
      - access_request
      verbs:
      - list
      - read
      - update
      - delete
  deny:
    # ...
  options:
    # ...
tsh login teleport-cluster --request-roles=dba

Seeking request approval... (id: bc8ca931-fec9-4b15-9a6f-20c13c5641a9)

Note

Users can finish the request without waiting for approval with the --request-nowait flag. Once the request is approved, the user can see it with tsh request ls and login with it using tsh login --request-id.

As a Teleport Administrator:

tctl request ls

Token Requestor Metadata Created At (UTC) Status

------------------------------------ --------- -------------- ------------------- -------

bc8ca931-fec9-4b15-9a6f-20c13c5641a9 alice roles=dba 07 Nov 19 19:38 UTC PENDING

tctl request approve bc8ca931-fec9-4b15-9a6f-20c13c5641a9

Assuming access, tsh will automatically manage a certificate re-issued with the newly requested roles applied. In this case contractor will now have have the permission of the dba.

Warning

Granting a role with administrative abilities could allow a user to permanently upgrade their privileges (e.g. if contractor was granted admin for some reason). We recommend only escalating to the next role of least privilege vs jumping directly to "Super Admin" role.

The deny.request block can help mitigate the risk of doing this by accident. See Example Below.

# Example role that explicitly denies a contractor from requesting the admin
# role.
kind: role
version: v5
metadata:
name: contractor
spec:
options:
    # ...
allow:
    # ...
deny:
    request:
    roles: ['admin']

Adding a Reason to Access Requests

When requesting a new role users can add provide a reason along with their request tsh login --request-roles="db" --request-reason="Need access to db".

By requiring a reason along with an Access Request, you can provide users with a default unprivileged state where they must always go through the Access Requests API in order to gain meaningful privilege.

Teams can leverage claims (traits) provided by external identity providers both when determining which roles a user is allowed to request, and if a specific request should be approved/denied.

Example Setup

Unprivileged User
In this example we have an employee who isn't able to access any systems. When they log in, they'll always need to provide a reason for access.

kind: role
metadata:
  name: employee
spec:
  allow:
    request:
      # the `roles` list can now be a mixture of literals and wildcard matchers
      roles: ['common', 'dev-*']
      # the `claims_to_roles` mapping works the same as it does in
      # the OIDC connector, with the added benefit that the roles being mapped to
      # can also be matchers. the below mapping says that users with
      # the claims `groups: admins` can request any role in the system.
      claims_to_roles:
        - claim: groups
          value: admins
          roles: ['*']
      # Teleport can attach annotations to pending Access Requests. these
      # annotations may be literals, or be variable interpolation expressions,
      # effectively creating a means for propagating selected claims from an
      # external identity provider to the plugin system.
      annotations:
        foo: ['bar']
        groups: ['{{external.groups}}']
  options:
    # the `request_access` field can be set to 'always' or 'reason' to tell
    # tsh or the web UI to always create an Access Request on login. If it is
    # set to 'reason', the user will be required to indicate *why* they are
    # generating the Access Request.
    request_access: reason
    # the `request_prompt` field can be used to tell the user what should
    # be supplied in the request reason field.
    request_prompt: Please provide your ticket ID
version: v5
Wildcard and RegEx Tips

Teleport RBAC offers powerful wildcard and RegEx helpers. Below are a few examples.

dev-* - Can request all dev clusters. e.g. dev-prod,dev-stg

^prod.*$ - Can request all prod.* clusters. e.g. prod.us-east

dev-{{regexp.match("us-*")}} - Can request any dev cluster in the US. e.g. dev-us-east-a, dev-us-west-b

dev-{{regexp.not_match("beta")}}-prod - Can request any cluster, apart from beta cluster. e.g. Can access dev-alpha-prod, cannot access dev-beta-prod.

Unprivileged User Login

Login: This will prompt the user to provide a reason in the UI.

tsh login

Login: The user can provide a reason using tsh.

tsh login --request-reason="..."
Note

Notice that the above role does not specify any logins. If a users's roles specify no logins, Teleport will now generate the user's initial SSH certificates with an invalid dummy login of the form -teleport-nologin-<random-suffix> (e.g. -teleport-nologin-1e02dbfd).

Admin Flow: Approve/Deny

A number of new parameters are now available that grant the plugin or administrator greater insight into approvals/denials:

tctl request deny --reason='Please be more specific' --annotations=method=cli,unix-user=${USER} 28a3fb86-0230-439d-ad88-11cfcb213193

Because automatically generated requests always include all roles that the user is allowed to request, approvers can now specify a smaller subset of the requested roles that should actually be applied, allowing for sub-selection in cases where full escalation is not a desirable default:

tctl request approve --roles=role-1,role-3 --reason='Approved, but not role-2 right now' 28a3fb86-0230-439d-ad88-11cfcb213193

Other features of Role Access Requests

  • Users can request multiple roles at one time. e.g roles: ['dba','netsec','cluster-x']
  • Approved requests have no effect on Teleport's behavior outside of allowing additional roles on re-issue. This has the nice effect of making requests "compatible" with older versions of Teleport, since only the issuing Auth Server needs any particular knowledge of the feature.

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.

IntegrationTypeSetup Instructions
SlackMessagingSet up Slack
MattermostMessagingSet up Mattermost
Microsoft TeamsMessagingSet up Microsoft Teams
Jira ServerProject BoardSet up Jira Server
Jira CloudProject BoardSet up Jira Cloud
PagerDutyScheduleSet up PagerDuty
EmailMessagingSet up email