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
-
A running Teleport cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 11.3.1, which you can download by visiting the customer portal.tctl versionTeleport v11.3.1 go1.19
tsh versionTeleport v11.3.1 go1.19
-
A Teleport Cloud account, which includes a running Auth Service and Proxy Service. If you do not have a Teleport Cloud account, visit the sign up page to begin your free trial.
-
The
tctl
admin tool andtsh
client tool version >= 11.2.1. To download these tools, visit the Downloads page.tctl versionTeleport v11.2.1 go1.19
tsh versionTeleport v11.2.1 go1.19
- Access to an SMTP service. The Teleport email plugin supports either Mailgun or a generic SMTP service that authenticates via username and password.
The Teleport plugin needs to use a username and password to authenticate to your SMTP service. To mitigate the risk of these credentials being leaked, you should set up a dedicated email account for the Teleport plugin and rotate the password regularly.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 11.3.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent tctl
commands in this guide on your local machine.
For full privileges, you can also run tctl
commands on your Auth Service host.
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=myinstance.teleport.sh [email protected]tctl statusCluster myinstance.teleport.sh
Version 11.2.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
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.yamlrole '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.
If you are using a local SMTP server to test the plugin, you should install the plugin on your local machine. This is because the plugin needs to dial out to your SMTP server and perform any necessary DNS lookups in order to send email.
Your Teleport cluster does not need to perform DNS lookups for your plugin, as the plugin dials out to the Proxy Service or Auth Service.
We currently only provide Linux amd64 binaries. You can also compile the plugin from source.
curl -L https://get.gravitational.com/teleport-access-email-v11.3.1-linux-amd64-bin.tar.gztar -xzf teleport-access-email-v11.3.1-linux-amd64-bin.tar.gzcd teleport-access-email./install
To install from source you need git
and go
installed. If you do not have
Go installed, visit the Go downloads page.
Checkout teleport-plugins
git clone https://github.com/gravitational/teleport-plugins.gitcd teleport-plugins/access/emailmake
Move the teleport-email
binary from teleport-plugins/access/email/build
into a directory in your PATH
.
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 and read Access Requests. This way, plugins can retrieve Access Requests from the Teleport Auth Service and present them to reviewers.
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']
- 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
Assign the access-plugin-impersonator
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding access-plugin-impersonator
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - access-plugin-impersonator
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github > github.yaml
Edit github.yaml
, adding access-plugin-impersonator
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f github.yaml
Retrieve your saml
configuration resource:
tctl get saml/mysaml > saml.yaml
Edit saml.yaml
, adding access-plugin-impersonator
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc > oidc.yaml
Edit oidc.yaml
, adding access-plugin-impersonator
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Log out of your Teleport cluster and log in again to assume the new role.
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.
Environment type
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
If your network allows your plugin to access the Auth Service directly, e.g., you are running the plugin on the Auth Service host, the plugin uses TLS credentials to connect to the Auth Service's gRPC endpoint and listen for new and updated Access Requests.
You can generate TLS credentials with the following command:
tctl auth sign --format=tls --user=access-plugin --out=auth
This command should result in three PEM-encoded files: auth.crt
,
auth.key
, and auth.cas
(certificate, private key, and CA certs
respectively). Later, you will configure the plugin to use these credentials to
connect to the Auth Service directly.
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth
Then create a Kubernetes secret:
kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth
Then create a Kubernetes secret:
kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
The Helm chart only supports the file
format.
You will refer to this file later when configuring the plugin.
By default, tctl auth sign
produces certificates with a relatively short
lifetime. For production deployments, you can use the --ttl
flag to ensure a
more practical certificate lifetime, e.g., --ttl=8760h
to export a one-year
certificate.
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]
addr
: Include the hostname and HTTPS port of your Teleport Proxy Service
(e.g., mytenant.teleport.sh:443
). If you are configuring your plugin to
connect directly to the Teleport Auth Service, use your Auth Service's gRPC
endpoint (e.g., teleport.example.com:3025
).
identity
, client_key
, client_crt
, root_cas
: The values
you will use for these fields depend on whether the email plugin will
connect to the Proxy Service or the Auth Service.
If you exported an identity file earlier, fill in the identity
field with the
path to the file and comment out the other fields.
If you exported a client key, client certificate, and root CAs earlier, fill in
the client_key
, client_crt
, and root_cas
fields with the paths to these
files and leave identity
commented out.
addr
: Include the hostname and HTTPS port of your Teleport Cloud tenant
(e.g., mytenant.teleport.sh:443
).
identity
, client_key
, client_crt
, root_cas
: Fill in the
identity
field with the path to the identity file you exported earlier and
comment out the other fields.
[mailgun]
or [smtp]
Provide the credentials for your SMTP service depending on whether you are using Mailgun or SMTP service.
In the mailgun
section, assign domain
to the domain name and subdomain of
your Mailgun account. Assign private_key
to your Mailgun private key.
Assign host
to the fully qualified domain name of your SMTP service, omitting
the URL scheme and port. (If you're using a local SMTP server for testing, use
"localhost"
for host
.) Assign port
to the port of your SMTP service, then
fill in username
and password
.
You can also save your password to a separate file and assign password_file
to
the file's path. The plugin reads the file and uses the file's content as the
password.
If you are testing the email plugin against a trusted internal SMTP server where
you would rather not use TLS—e.g., a local SMTP server on your development
machine—you can assign the starttls_policy
setting to disabled
(always
disable TLS) or opportunistic
(disable TLS if the server does not advertise
the STARTTLS
extension). The default is to always enforce TLS, and you should
leave this setting unassigned unless you know what you are doing and understand
the risks.
[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 receives 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]
.
Users can suggest reviewers when they create an Access Request, e.g.,:
tsh request create --roles=dbadmin [email protected],[email protected]
If an Access Request includes suggested reviewers, the email plugin will add
these to the list of recipients to notify. If a suggested reviewer is an email
address, the plugin will send a message to that recipient in addition to those
configured in role_to_recipients
.
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"
If you do not plan to use role-to-recipient mapping, you can configure the
Teleport email plugin to notify a static list of recipients for every Access
Request event by using the delivery.recipients
field:
[delivery]
recipients = ["[email protected]", "[email protected]"]
If you use delivery.recipients
, you must remove the role_to_recipients
configuration section. Behind the scenes, delivery.recipients
assigns the
recipient list to a role_to_recipients
mapping under the wildcard value "*"
.
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 6/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 startINFO Starting Teleport Access Email Plugin (): email/app.go:80
INFO Plugin is ready email/app.go:101
Create an Access Request
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=editorSeeking 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":
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:
You can also review an Access Request from the command line:
Replace REQUEST_ID with the id of the request
tctl request approve REQUEST_IDtctl request deny REQUEST_ID
Replace REQUEST_ID with the id of the request
tsh request review --approve REQUEST_IDtsh request review --deny REQUEST_ID
Step 7/7. 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-emailsudo systemctl start teleport-email
Feedback
If you have any issues with this plugin please create an issue on GitHub.