Routing Access Request notifications

How it works

With Teleport's Access Monitoring Rules, Access Request notifications can be routed to plugins based on based on several conditions. For example, you may wish to send notifications to different Slack channels based on what roles or resources are being accessed, or based on what user is making the request.

Currently only the Slack access plugin is supported.

Prerequisites

• A managed Teleport Enterprise account.

• The tctl admin tool and tsh client tool version >= 16.0.0.

  You can verify the tools you have installed by running the following commands:

  tctl version
  Teleport Enterprise v16.0.0 go1.22
  
  tsh version
  Teleport v16.0.0 go1.22

  You can download these tools by following the appropriate Installation instructions for your environment and Teleport edition.

• At least one of the Teleport Access Plugins that support Access Monitoring Rules is enrolled.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. tctl is supported on macOS and Linux machines.

  For example:

  tsh login --proxy=teleport.example.com --user=email@example.com
  tctl status
  Cluster  teleport.example.com
  Version  16.0.0
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  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.

Step 1/2. Create an Access Monitoring Rule

You can define an Access Request notification rule in two ways:

• Using the Web UI dialog.
• Creating a YAML resource file containing the definition of a rule.

Create an Access Monitoring Rule via the Web UI

To create an Access Monitoring Rule via the Web UI, first navigate to the Access Request page and click on View Notification Routing Rules.

Then click Create Notification Rule.

If a plugin that supports Access Monitoring Rule based routing is not enrolled the UI will prompt you to enroll one.

Create an Access Monitoring Rule using YAML resource

Here is an example Access Monitoring Rule. This rule will notify your_slack_channel via the Slack plugin if an Access Request containing the role your_role_name is made.

kind: access_monitoring_rule
version: v1
metadata:
  name: your-plugin-name
spec:
  subjects: ['access_request']
  condition: 'access_request.spec.roles.contains("your_role_name")'
  notification:
    name: 'slack'
    recipients: ['your_slack_channel']

The above routing rule can be created using tctl create -f your-file-name.yaml from the command line.

Multiple recipients can be specified in an Access Monitoring Rule. The condition field of the rule is set to a predicate expression defining the conditions under which you wish the rule to apply.

Fields of the Access Request that are currently supported are

Predicate expressions used in the condition of Access Monitoring Rules must evaluate to either true or false.

Some example values for the condition field and their possible uses.

• access_request.spec.user == "some_user" - Routing based on requesting user.
• access_request.spec.roles.contains("some_role") - Routing based on the requested roles.
• access_request.spec.roles.contains_any(set("role_1", "role_2")) - Routing based on multiple roles.

Step 2/2. Testing your new Access Monitoring Rule

In the above example rule for the Slack plugin.

• Replace the role "your_role_name" with a role of your choice.
• Replace "your_slack_channel" with a slack channel your plugin has access to.

Afterwards create an Access Request for the role you specified in the rule.

Then check the Slack channel you have set in your Access Monitoring Rule earlier to verify that the notification has been sent.

• As an Admin
• As a User
• From the Web UI

A Teleport admin can create an Access Request for another user with tctl:

tctl request create myuser --roles=editor

Users can use tsh to create an Access Request and log in with approved roles:

tsh request create --roles=editor
Seeking request approval... (id: 8f77d2d1-2bbf-4031-a300-58926237a807)

Users can request access using the Web UI by visiting the "Access Requests" tab and clicking "New Request":