Skip to content

Latest commit

 

History

History
266 lines (217 loc) · 8.17 KB

role-requests.mdx

File metadata and controls

266 lines (217 loc) · 8.17 KB
title description h1
Role Access Requests
Teleport allows users to request new roles with elevated privileges from the CLI or UI. Requests can be escalated via ChatOps or anywhere else via our flexible Authorization Workflow API.
Teleport Role Access Requests

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.

<ScopedBlock scope={["oss"]}>

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

(!docs/pages/includes/commercial-prereqs-tabs.mdx!)

(!docs/pages/includes/tctl.mdx!)

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

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

<Admonition type="tip" title="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="..."

<Admonition type="tip" title="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

(!docs/pages/includes/access-request-integrations.mdx!)