Teleport Access Requests with Email

This guide will explain how to set up Teleport to send Just-in-Time Access Request notifications to users via email. Since all organizations use email for at least some of their communications, Teleport's email plugin makes it straightforward to integrate Access Requests into your existing workflows, letting you implement security best practices without compromising productivity.

Prerequisites

• Access to an SMTP service. The Teleport email plugin supports either Mailgun or a generic SMTP service that authenticates via username and password.

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  10.3.1
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  10.2.2
CA pin   sha256:sha-hash-here

Step 1/7. Define RBAC resources

Before you set up the email plugin, you will need to enable Role Access Requests in your Teleport cluster.

For the purpose of this guide, we will define an editor-requester role, which can request the built-in editor role, and an editor-reviewer role that can review requests for the editor role.

Create a file called editor-request-rbac.yaml with the following content:

kind: role
version: v5
metadata:
  name: editor-reviewer
spec:
  allow:
    review_requests:
      roles: ['editor']
---
kind: role
version: v5
metadata:
  name: editor-requester
spec:
  allow:
    request:
      roles: ['editor']
      thresholds:
        - approve: 1
          deny: 1

Create the roles you defined:

tctl create -f editor-request-rbac.yaml
role 'editor-reviewer' has been created
role 'editor-requester' has been created

Allow yourself to review requests by users with the editor-requester role by assigning yourself the editor-reviewer role. First, retrieve your user definition:

TELEPORT_USER=$(tsh status --format=json | jq -r .active.username)
tctl get user/${TELEPORT_USER?} > user.yaml

Edit user.yaml to add the editor-reviewer role:

 spec:
   roles:
   - access
   - editor
+  - editor-reviewer

Update your user definition:

tctl create -f user.yaml

Log out of Teleport and log in again. You will now have the ability to review requests for the editor role.

Create a user called myuser who has the editor-requester role. This user cannot edit your cluster configuration unless they request the editor role:

tctl users add myuser --roles=editor-requester

tctl will print an invitation URL to your terminal. Visit the URL and log in as myuser for the first time, registering credentials as configured for your Teleport cluster.

Later in this guide, you will have myuser request the editor role so you can review the request using the Teleport plugin.

Step 2/7. Install the Teleport email plugin

We recommend installing Teleport plugins on the same host as the Teleport Proxy Service. This is an ideal location as plugins have a low memory footprint, and will require both public internet access and Teleport Auth Service access.

We currently only provide Linux amd64 binaries. You can also compile the plugin from source.

curl -L https://get.gravitational.com/teleport-access-email-v10.3.1-linux-amd64-bin.tar.gz
tar -xzf teleport-access-email-v10.3.1-linux-amd64-bin.tar.gz
cd teleport-access-email
./install

Checkout teleport-plugins
git clone https://github.com/gravitational/teleport-plugins.git
cd teleport-plugins/access/email
make

Ensure that the plugin is installed correctly:

teleport-email version

Step 3/7. Create a user and role for the plugin

Teleport's Access Request plugins authenticate to your Teleport cluster as a user with permissions to list, read, and update Access Requests. This way, plugins can retrieve Access Requests from the Teleport Auth Service, present them to reviewers, and modify them after a review.

Define a user and role called access-plugin by adding the following content to a file called access-plugin.yaml:

kind: role
version: v5
metadata:
  name: access-plugin
spec:
  allow:
    rules:
      - resources: ['access_request']
        verbs: ['list', 'read', 'update']
      - resources: ['access_plugin_data']
        verbs: ['update']
---
kind: user
metadata:
  name: access-plugin
spec:
  roles: ['access-plugin']
version: v2

Create the user and role:

tctl create -f access-plugin.yaml

As with all Teleport users, the Teleport Auth Service authenticates the access-plugin user by issuing short-lived TLS credentials. In this case, we will need to request the credentials manually by impersonating the access-plugin role and user.

If you are using tctl from the Auth Service host, you will already have impersonation privileges.

To grant your user impersonation privileges for access-plugin, define a role called access-plugin-impersonator by pasting the following YAML document into a file called access-plugin-impersonator.yaml:

kind: role
version: v5
metadata:
  name: access-plugin-impersonator
spec:
  allow:
    impersonate:
      roles:
      - access-plugin
      users:
      - access-plugin

Create the access-plugin-impersonator role:

tctl create -f access-plugin-impersonator.yaml

Retrieve your user definition:

TELEPORT_USER=$(tsh status --format=json | jq -r .active.username)
tctl get users/${TELEPORT_USER?} > myuser.yaml

Edit myuser.yaml to include the role you just created:

  roles:
   - access
   - auditor
   - editor
+  - access-plugin-impersonator

Apply your changes:

tctl create -f myuser.yaml

Log out of your Teleport cluster and log in again. You will now be able to generate signed certificates for the access-plugin role and user.

Step 4/7. Export the access plugin identity

Like all Teleport users, access-plugin needs signed credentials in order to connect to your Teleport cluster. You will use the tctl auth sign command to request these credentials for your plugin.

The format of the credentials depends on whether you have set up your network to give the plugin direct access to the Teleport Auth Service, or if all Teleport clients and services connect to the Teleport Proxy Service instead.

tctl auth sign --user=access-plugin --out=auth.pem

tctl auth sign --format=tls --user=access-plugin --out=auth

tctl auth sign --user=access-plugin --out=auth

kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem

tctl auth sign --user=access-plugin --out=auth

kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem

Step 5/7. Configure the plugin

At this point, you have generated credentials that the email plugin will use to connect to Teleport. You will now configure the plugin to use these credentials to receive Access Request notifications from Teleport and email them to your chosen recipients.

The Teleport email plugin uses a config file in TOML format. Generate a boilerplate config by running the following command:

teleport-email configure | sudo tee /etc/teleport-email.toml

Edit the configuration file for your environment. We will show you how to set each value below.

[teleport]

[mailgun] or [smtp]

Provide the credentials for your SMTP service depending on whether you are using Mailgun or SMTP service.

[delivery]

Assign sender to the email address from which you would like the Teleport plugin to send messages.

[role_to_recipients]

The role_to_recipients map configure the recipients that the email plugin will notify when a user requests access to a specific role. When the plugin receives an Access Request from the Auth Service, it will look up the role being requested and identify the recipients to notify.

Here is an example of a role_to_recipients map:

[role_to_recipients]
"*" = ["[email protected]", "[email protected]"]
"dev" = "[email protected]"
"dba" = "[email protected]"

In the role_to_recipients map, each key is the name of a Teleport role. Each value configures the recipients the plugin will email when it recieves an Access Request for that role. The value can be a single string or an array of strings. Each string must be an email address.

The role_to_recipients map must also include an entry for "*", which the plugin looks up if no other entry matches a given role name. In the example above, requests for roles aside from dev and dba will notify [email protected] and [email protected].

tsh request create --roles=dbadmin [email protected],[email protected]

Configure the email plugin to notify you when a user requests the editor role by adding the following to your role_to_recipients config, replacing YOUR_EMAIL_ADDRESS with the appropriate address:

[role_to_recipients]
"*" = "YOUR_EMAIL_ADDRESS"
"editor" = "YOUR_EMAIL_ADDRESS"

[delivery]
recipients = ["[email protected]", "[email protected]"]

You configuration should resemble the following:

# /etc/teleport-email.toml
[teleport]
addr = "example.com:3025"
identity = "/var/lib/teleport/plugins/email/auth_id"

[mailgun]
domain = "sandboxbd81caddef744a69be0e5b544ab0c3bd.mailgun.org" 
private_key = "xoxb-fakekey62b0eac53565a38c8cc0316f6"                                     

# As an alternative, you can use SMTP server credentials:
#
# [smtp]
# host = "smtp.gmail.com"
# port = 587
# username = "[email protected]"
# password = ""
# password_file = "/var/lib/teleport/plugins/email/smtp_password"

[delivery]
sender = "[email protected]" 

[role_to_recipients]
"*" = "[email protected]"
"editor" = ["[email protected]", "[email protected]"]

[log]
output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/email.log"
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".

Step 7/7. Test the email plugin

After finishing your configuration, you can now run the plugin and test your email-based Access Request flow:

teleport-email start

If everything works as expected, the log output should look like this:

teleport-email start
INFO   Starting Teleport Access Email Plugin (): email/app.go:80
INFO   Plugin is ready email/app.go:101

Create an Access Request

tctl request create myuser --roles=editor

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

The recipients you configured earlier should receive notifications of the request by email.

Resolve the request

Once you receive an Access Request message, click the link to visit Teleport and approve or deny the request:

Replace REQUEST_ID with the id of the request
tctl request approve REQUEST_ID
tctl request deny REQUEST_ID

Replace REQUEST_ID with the id of the request
tsh request review --approve REQUEST_ID
tsh request review --deny REQUEST_ID

Step 8/8. Set up systemd

In production, we recommend starting the Teleport plugin daemon via an init system like systemd. Here's the recommended Teleport plugin service unit file for systemd:

[Unit]
Description=Teleport Email Plugin
After=network.target

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/teleport-email start --config=/etc/teleport-email.toml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport-email.pid

[Install]
WantedBy=multi-user.target

Save this as teleport-email.service in either /usr/lib/systemd/system/ or another unit file load path supported by systemd.

Enable and start the plugin:

sudo systemctl enable teleport-email
sudo systemctl start teleport-email

Feedback

If you have any issues with this plugin please create an issue on GitHub.