# Routing Access Request Notifications With Teleport's Access Monitoring Rules, Access Request notifications can be routed to plugins 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. ## How it works The Access Monitoring Rule (AMR) is a dynamic Teleport resource that matches audit events with certain characteristics and instructs Teleport plugins to take action when it receives these events. Teleport plugins connect to the Teleport Auth Service and listen for AMRs. If an AMR matches the plugin, the plugin loads the AMR and uses it to process incoming events. Plugins implement AMR handling logic separately from one another. Currently, only a subset of hosted plugins support notification routing rules. We are working on extending support to the rest of hosted plugins. Keep an eye on Teleport [changelog](https://goteleport.com/docs/changelog.md) to learn about new plugins. ## Prerequisites - A running Teleport Enterprise Cloud cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.7.3 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`. ![View Notification Routing Rules](/docs/assets/images/view_routing_rules-c604428974417f76436004dd5904c257.png) Then click `Create Notification Rule`. ![Create Access Monitoring Rule](/docs/assets/images/access_monitoring_rule_ui-7c32cf79848eba85a10738c58deb04f9.png) 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 | Field | Description | | ----------------------------------------- | ---------------------------------------------- | | access\_request.spec.roles | The set of roles requested. | | access\_request.spec.suggested\_reviewers | The set of reviewers specified in the request. | | access\_request.spec.system\_annotations | A map of system annotations on the request. | | access\_request.spec.user | The requesting user. | | access\_request.spec.request\_reason | The request reason. | | access\_request.spec.creation\_time | The creation time of the request. | | access\_request.spec.expiry | The expiry time of the request. | 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** A Teleport admin can create an Access Request for another user with `tctl`: ``` $ tctl request create myuser --roles=editor ``` **As a User** 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) ``` **From the Web UI** Users can request access using the Web UI by visiting "Identity", clicking "Access Requests" and then "New Request": ![Creating an Access Request using the Web UI](/docs/assets/images/request-access-be784784ab25db7e651c87817044f082.png)