Fork me on GitHub
Teleport

Teleport Slack Plugin Setup

This guide will talk through how to setup Teleport with Slack. Teleport to Slack integration allows you to treat Teleport access and permission requests via Slack message and inline interactive components.

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.

Create User and Role for access

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.

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']
    # teleport currently refuses to issue certs for a user with 0 logins,
    # this restriction may be lifted in future versions.
    logins: ['access-plugin-not-used']

Here and below follow along and create yaml resources using tctl create -f:

$ tctl create -f access.yaml
Tip
If you're using other plugins, you might want to create different users and roles for different plugins

Export access-plugin Certificate

Teleport Plugin use the access-plugin role and user to perform the approval. We export the identity files, 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). We'll reference the auth.crt, auth.key, and auth.cas files later when configuring the plugins.

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

Create Slack App

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:

  1. Create a new app, pick a name and select a workspace it belongs to.
  2. 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.
  3. Obtain 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 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 https://get.gravitational.com/teleport-access-slack-v7.1.3-linux-amd64-bin.tar.gz
tar -xzf teleport-access-slack-v7.1.3-linux-amd64-bin.tar.gz
cd teleport-access-slack
./install

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

Configuring Teleport Slack

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

Then, edit the config as needed.

# example slack plugin configuration TOML file

[teleport]
auth_server = "0.0.0.0: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".

Editing the config file

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. The listen URL is the URL the plugin will listen for Slack callbacks.

# example slack plugin configuration TOML file

[teleport]
auth_server = "0.0.0.0: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".

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 7.1.3.1-0-slack/main.go:145

INFO Starting a request watcher... slack/main.go:330

INFO Starting insecure HTTP server on 0.0.0.0:8081 utils/http.go:64

INFO Watcher connected slack/main.go:298

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

TSH User Login and Request Admin 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. You can approve or deny it and tsh should login successfully or error out right after you click an action button on Slack.

Setup with SystemD

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

Have a suggestion or can’t find something?
IMPROVE THE DOCS