Fork me on GitHub
Teleport

Teleport Access Requests

Improve

Approving Requests using an External Integration

Access Requests Setup

Teleport has the ability for users to request additional roles. The Access Request API makes it easy to dynamically approve or deny these requests.

Setup

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

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

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

kind: role
version: v4
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: v4
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: v4
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: v3
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 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

IntegrationFeatureTypeSetup Instructions
SlackChatbotSetup Slack
MattermostChatbotSetup Mattermost
Jira ServerProject BoardSetup Jira Server
Jira CloudProject BoardSetup Jira Cloud
PagerDutyScheduleSetup PagerDuty
Have a suggestion or can’t find something?
IMPROVE THE DOCS