Fork me on GitHub
Teleport

Teleport Slack Plugin Setup

Improve

This guide will talk through how to set up Teleport with Slack. Teleport's Slack integration notifies individuals and channels of Access Requests.

Example Slack Request

Setup

Prerequisites

This guide assumes that you have:

  • A running Teleport Cluster
  • Admin privileges with access to tctl
  • 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 (auth.example.com:3025) directly.

Create a user and role for access

Using an existing Teleport cluster, create the following user and 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 access-plugin.

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']
Tip

If you're using other plugins, you might want to create different users and roles for different plugins

Export the access-plugin certificate

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.crt, auth.key, and 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: auth.pem.

Certificate Lifetime

By default, 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.

Create a Slack app

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:

  1. Create a new app, pick a name and select a workspace it belongs to.
  2. Add an OAuth Scope, which is required by Slack for the app to be installed.
  3. Obtain an OAuth token.

Creating a new Slack app

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

Create Slack App

Selecting OAuth scopes

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.

API Scopes

Obtain an OAuth token

OAuth Tokens

Add to workspace

OAuth Tokens 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. Invite bot to channel

Installing the Teleport Slack plugin

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.gz
tar -xzf teleport-access-slack-v9.3.7-linux-amd64-bin.tar.gz
cd teleport-access-slack
./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.git
cd teleport-plugins/access/slack
make

Run ./install from teleport-slack or place the executable in the appropriate /usr/bin or /usr/local/bin on the server installation.

docker pull quay.io/gravitational/teleport-plugin-slack:9.3.7

Configuring the Teleport Slack plugin

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

teleport-slack configure > teleport-slack.toml
sudo mv teleport-slack.toml /etc

Editing the config file

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 /var/lib/teleport/plugins/slack/.

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".

Test run

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!

teleport-slack start

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

teleport-slack start

INFO Starting Teleport Access Slack Plugin 7.2.1: slack/app.go:80

INFO Plugin is ready slack/app.go:101

Testing the approval workflow

You can create a test permissions request with tctl and check if the plugin works as expected like this:

Create a test permissions request behalf of a user

Replace USERNAME with a Teleport local user, and TARGET_ROLE with a Teleport Role

tctl request create USERNAME --roles=TARGET_ROLE

A user can also try using --request-roles flag.

Example with a user trying to request a role DBA.

tsh login --request-roles=dba

Approve or deny the request on Slack

The messages should automatically get updated to reflect the action you just clicked. You can also check the request status with tctl:

tctl request ls

Log in and request a role

You can also test the full workflow from the user's perspective using tsh:

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.

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 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 teleport-slack.service.

Audit log

The plugin will let anyone with access to the Slack Channel so it's important to review Teleport' audit log.

Feedback

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