This guide will talk through how to setup Teleport with Slack. Teleport to 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 connecting through the proxy service (
If you want the Slack plugin to connect through the web port (
teleport.example.com:443) follow the Teleport Cloud instructions.
OpenSource and Enterprise installations can connect to the auth service (
Log into Teleport Authentication Server, this is where you normally run
tctl. Create a
new user and role that only has API access to the
access_request API. The below script
will create a yaml resource file for a new user and role.
The Teleport Cloud requires authenticating with a role that has
impersonation rights and can create the
access-plugin role and user.
Login in with
tsh with a user that has this role or has a role with these allows.
kind: role version: v4 metadata: name: plugin-admin spec: allow: impersonate: roles: - access-plugin users: - access-plugin rules: - resources: ['roles'] verbs: ['create','update','read','list','delete'] - resources: ['user'] verbs: ['create','update','read','list','delete']
Create a non-interactive bot
access-plugin user and role.
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']
Here and below follow along and create yaml resources using
tctl create -f:
$ tctl create -f access.yaml
If you're using other plugins, you might want to create different users and roles for different plugins
Teleport Plugin use the
access-plugin role and user to perform the approval. We export the identity files, using
tctl auth sign. You have the option of connecting through the proxy or auth server. Teleport Cloud must use the proxy server.
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.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when configuring the plugins.
tctl auth sign --user=access-plugin --out=auth.pem --ttl=2190h
The above sequence should result in one PEM encoded file being generated: auth.pem. We'll reference the auth.pem file later when configuring the plugins.
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 create a new Slack app and setup 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 OAuth Scopes. This is required by Slack for the app to be installed — we'll only need a single scope to post messages to your Slack account.
- Obtain 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 https://get.gravitational.com/teleport-access-slack-v7.3.2-linux-amd64-bin.tar.gztar -xzf teleport-access-slack-v7.3.2-linux-amd64-bin.tar.gzcd teleport-access-slack./install
To install from source you need
go >= 1.16 installed.
Checkout teleport-pluginsgit clone https://github.com/gravitational/teleport-plugins.gitcd teleport-plugins/access/slackmake
./install in from
teleport-slack or place the executable in the appropriate
/usr/local/bin on the server installation.
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
Then, edit the config as needed.
# Example slack plugin configuration TOML file [teleport] # Teleport Auth/Proxy Server address. # # Should be port 3025 for Auth Server and 3080 or 443 for Proxy. # For Teleport Cloud, should be in the form "your-account.teleport.sh:443". addr = "example.com:3025" # Credentials. # # When using --format=file: # identity = "/var/lib/teleport/plugins/slack/auth_id" # Identity file # # When using --format=tls: # client_key = "/var/lib/teleport/plugins/slack/auth.key" # Teleport TLS secret key # client_crt = "/var/lib/teleport/plugins/slack/auth.crt" # Teleport TLS certificate # root_cas = "/var/lib/teleport/plugins/slack/auth.cas" # Teleport CA certs [slack] token = "xoxb-11xx" # Slack Bot OAuth token # recipients = ["[email protected]","YYYYYYY"] # Optional Slack Rooms # Can also set suggested_reviewers for each role [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".
In the Teleport section, use the certificates you've generated with
tctl auth sign before. The plugin installer creates a folder for those certificates in
/var/lib/teleport/plugins/slack/ — so just move the certificates there and make sure the config points to them.
In Slack section, use the OAuth token, signing token, setup the desired channel name.
# 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 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.