Configure Automatic Reviews

Report an issue with this page

Teleport supports automatic reviews of role Access Requests. This feature enables teams to enforce a zero standing privilege policy, while still allowing users to receive temporary access without manual approval.

resource access request support

Automatic reviews is not currently supported with resource Access Requests. This functionality will be enabled in a future Teleport release.

How it works

Automatic reviews are triggered by Access Monitoring Rules. These rules instruct Teleport to monitor Access Requests and automatically submit a review when certain conditions (such as requested roles or user traits) are met.

For example, an Access Monitoring Rule can perform an automatic Access Request approval when a user with the Teleport traits or IdP attribute team: demo requests access to the access role.

Prerequisites

• A running Teleport Enterprise cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial.

• The tctl admin tool and tsh client tool.

  Visit Installation for instructions on downloading tctl and tsh.

• This feature requires Teleport Identity Governance.

Step 1/4. Create a requester role and user

In this example, we'll first create:

• A role named demo-access-request, which allows requesting access to the access role.
• A user named demo-access-requester, assigned the above role.

Create the role

Create a role configuration file named demo-role.yaml:

# demo-role.yaml
kind: role
version: v7
metadata:
  name: demo-access-request
spec:
  allow:
    request:
      roles:
      - access
      search_as_roles:
      - access

Create the role with:

$ tctl create demo-role.yaml

Create the user

Use the following command to create the user and assign the role:

$ tctl users add --roles=demo-access-request demo-access-requester

Alternatively, you can assign the role after creating the user:

Assign the demo-access-request role to demo-access-requester by running the appropriate commands for your authentication provider:

Local User

1. Retrieve your local user's roles as a comma-separated list:

   ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')

2. Edit your local user to add the new role:

   tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},demo-access-request"

3. Sign out of the Teleport cluster and sign in again to assume the new role.

GitHub

1. Open your github authentication connector in a text editor:

   tctl edit github/github

2. Edit the github connector, adding demo-access-request to the teams_to_roles section.

   The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

   Here is an example:

     teams_to_roles:
       - organization: octocats
         team: admins
         roles:
           - access
   +       - demo-access-request
   

3. Apply your changes by saving closing the file in your editor.

4. Sign out of the Teleport cluster and sign in again to assume the new role.

SAML

1. Retrieve your saml configuration resource:

   tctl get --with-secrets saml/mysaml > saml.yaml

   Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

2. Edit saml.yaml, adding demo-access-request to the attributes_to_roles section.

   The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

     attributes_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - demo-access-request
   

3. Apply your changes:

   tctl create -f saml.yaml

4. Sign out of the Teleport cluster and sign in again to assume the new role.

OIDC

1. Retrieve your oidc configuration resource:

   tctl get oidc/myoidc --with-secrets > oidc.yaml

   Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

2. Edit oidc.yaml, adding demo-access-request to the claims_to_roles section.

   The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

     claims_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - demo-access-request
   

3. Apply your changes:

   tctl create -f oidc.yaml

4. Sign out of the Teleport cluster and sign in again to assume the new role.

Step 2/4. Assign user traits

To allow automatic review rules to evaluate the requesting user, assign them traits via the Teleport Web UI.

1. Go to Zero Trust Access -> Users
2. Next to demo-access-requester, click Options -> Edit...
3. Click Add user trait, and set:
   • Key: team
   • Value: demo
4. Click Save
5. Verify that the user has been updated with the desired trait.

When adding user traits, you can enter any keys and values. The user trait form does not support wildcard or regular expressions.

SSO users

Automatic reviews are compatible with SSO users and the attributes provided by the IdP.

Step 3/4. Create Access Monitoring Rule

Next, define the automatic review rule via the Teleport Web UI.

1. Go to Identity Governance -> Access Requests -> View Access Monitoring Rules
2. Click Create Access Monitoring Rule -> Automatic Review Rule
3. Configure the rule and set:
   • Name of roles to match: access
   • User Traits: team: demo
   • Review decision: APPROVED
4. Click Create Rule

This Access Monitoring Rule will ensure that Access Requests for the access role will be automatically reviewed for approval if the Teleport user traits requirements are satisfied. In this case, any user with the traits team: demo will satisfy the requirement.

Step 4/4. Verify automatic review rule

To verify the new Access Monitoring Rule, create an Access Request via the Teleport Web UI.

1. Log in as demo-access-requester
2. Go to Access Requests and click New Access Request
3. Change the request type from Resources to Roles
4. Add the access role to the Access Request
5. Click Proceed to Request, then Submit Request

At this point, the new Access Request should have been created, automatically reviewed, and transitioned into an APPROVED state. Navigate Back to Listings and verify the Access Request status. It might take a second for the review to process, so you may have to refresh the page.

Troubleshooting

Conflicting automatic review rules

Automatic review rules can automatically approve or deny Access Requests based on the selected review decision. If an Access Request meets the conditions for both an approval rule and a denial rule, the denial rule takes precedence.

Resource access requests

Automatic review rules are not currently supported for resource Access Requests. These rules will not be applied to any Access Requests that include a resource other than a role.

Next Steps

• For more configuration options with Access Monitoring Rules, refer to the Access Monitoring Rules Reference.
• For configuration with Teleport Terraform Provider, refer to the Terraform Resources Index
• For configuration options with SSO, refer to the Single Sign-On Guides