Teleport Slack Plugin Setup
This guide will talk through how to set up Teleport with Slack. Teleport's Slack integration notifies individuals and channels of Access Requests.
This guide assumes that you have:
- A running Teleport Cluster
- Admin privileges with access to
- Slack admin privileges to create an app and install it to your workspace
Teleport Cloud requires that plugins connect through the Proxy Service (
mytenant.teleport.sh:443). Open Source and Enterprise installations can connect to the Auth Service (
Using an existing Teleport cluster, create the following
role resources with the command below, replacing
YAML_PATH with the path to each resource spec.
$ tctl create -f YAML_PATH.yaml
Create a non-interactive bot user and role called
kind: user metadata: name: access-plugin spec: roles: ['access-plugin'] version: v2 kind: role version: v4 metadata: name: access-plugin spec: allow: rules: - resources: ['access_request'] verbs: ['list', 'read'] - resources: ['access_plugin_data'] verbs: ['update']
If you're using other plugins, you might want to create different users and roles for different plugins
Teleport's plugins use the
access-plugin role and user to approve access requests. We export the identity files to this plugin using
tctl auth sign.
tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=2190h
The above sequence should result in three PEM encoded files being generated:
auth.cas (certificate, private key, and CA certs respectively).
tctl auth sign --user=access-plugin --out=auth.pem --ttl=2190h
The above sequence should result in one PEM encoded file:
tctl auth sign produces certificates with a relatively short lifetime. For production deployments, the
--ttl flag can be used to ensure a more practical certificate lifetime.
--ttl=8760h exports a 1 year token
We'll reference these files later when configuring the plugins.
We'll create a new Slack app and set up auth tokens and callback URLs, so that Slack knows how to notify the Teleport plugin when Approve / Deny buttons are clicked.
You'll need to:
- Create a new app, pick a name and select a workspace it belongs to.
- Add an OAuth Scope, which is required by Slack for the app to be installed.
- Obtain an OAuth token.
Visit https://api.slack.com/apps to create a new Slack App.
App Name: Teleport
Development Slack Workspace: Pick the workspace you'd like the requests to show up in.
App Icon: Download Teleport Bot Icon
On the App screen, go to “OAuth and Permissions” under Features in the sidebar menu. Then scroll to Scopes, and add
chat:write, incoming-webhook, users:read, users:read.email scopes so that our plugin can post messages to your Slack channels.
After adding to the workspace, you still need to invite the bot to the channel. Do this by using the @ command, and inviting them to the channel.
We recommend installing the Teleport Plugins alongside the Teleport Proxy. This is an ideal location as plugins have a low memory footprint, and will require both public internet access and Teleport Auth access. We currently only provide linux-amd64 binaries, you can also compile these plugins from source.
Install the plugin
curl -L -O https://get.gravitational.com/teleport-access-slack-v9.3.7-linux-amd64-bin.tar.gztar -xzf teleport-access-slack-v9.3.7-linux-amd64-bin.tar.gzcd teleport-access-slack./install
To install from source you need
go installed. If you do not have Go installed, visit the Go downloads page.
Checkout teleport-pluginsgit clone https://github.com/gravitational/teleport-plugins.gitcd teleport-plugins/access/slackmake
teleport-slack or place the executable in the appropriate
/usr/local/bin on the server installation.
docker pull quay.io/gravitational/teleport-plugin-slack:9.3.7
Teleport Slack uses a config file in TOML format. Generate a boilerplate config by running the following command:
teleport-slack configure > teleport-slack.tomlsudo mv teleport-slack.toml /etc
In the Teleport section, use the identity file(s) you generated with
tctl auth sign. The plugin installer creates a folder for those files in
Move the certificates to this folder, then edit the configuration file (
teleport-slack.toml) based on the reference below to ensure that the appropriate settings point to your identity file(s).
# example slack plugin configuration TOML file [teleport] addr = "auth.example.com:3025" # Teleport Auth Server GRPC API address client_key = "/var/lib/teleport/plugins/slack/auth.key" # Teleport GRPC client secret key client_crt = "/var/lib/teleport/plugins/slack/auth.crt" # Teleport GRPC client certificate root_cas = "/var/lib/teleport/plugins/slack/auth.cas" # Teleport cluster CA certs [slack] token = "xoxb-11xx" # Slack Bot OAuth token # Optional Slack Rooms recipients = ["team","devops"] [log] output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/slack.log" severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
# example slack plugin configuration TOML file [teleport] addr = "teleport.example.com:443" # Teleport Auth Server GRPC API address identity = "/var/lib/teleport-plugin/access-plugin-slack.pem" [slack] token = "xoxb-11xx" # Slack Bot OAuth token # Optional Slack Rooms recipients = ["team","devops"] [log] output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/slack.log" severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
Assuming that Teleport is running, and you've created the Slack app, the plugin config, and provided all the certificates — you can now run the plugin and test the workflow!
If everything works fine, the log output should look like this:
INFO Starting Teleport Access Slack Plugin 7.2.1: slack/app.go:80
INFO Plugin is ready slack/app.go:101
You can create a test permissions request with
tctl and check if the plugin works as expected like this:
Replace USERNAME with a Teleport local user, and TARGET_ROLE with a Teleport Roletctl request create USERNAME --roles=TARGET_ROLE
A user can also try using
Example with a user trying to request a role DBA.tsh login --request-roles=dba
The messages should automatically get updated to reflect the action you just clicked. You can also check the request status with
tctl request ls
You can also test the full workflow from the user's perspective using
tsh login --request-roles=REQUESTED_ROLE
Seeking request approval... (id: 8f77d2d1-2bbf-4031-a300-58926237a807)
You should now see a new request in Teleport, and a message about the request on Slack with instructions.
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 Slack Plugin After=network.target [Service] Type=simple Restart=on-failure ExecStart=/usr/local/bin/teleport-slack start --config=/etc/teleport-slack.toml ExecReload=/bin/kill -HUP $MAINPID PIDFile=/run/teleport-slack.pid [Install] WantedBy=multi-user.target
Save this as
The plugin will let anyone with access to the Slack Channel so it's important to review Teleport' audit log.
If you have any issues with this plugin please create an issue here.