Fork me on GitHub
Teleport

Teleport Slack Plugin Setup

Improve

This guide will talk through how to setup Teleport with Slack. Teleport to 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 connecting through the proxy service (mytenant.teleport.sh:443). 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 (auth.example.com:3025) directly.

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.

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

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.3.2-linux-amd64-bin.tar.gz
tar -xzf teleport-access-slack-v7.3.2-linux-amd64-bin.tar.gz
cd teleport-access-slack
./install

To install from source you need git and go >= 1.16 installed.

Checkout teleport-plugins

git clone https://github.com/gravitational/teleport-plugins.git
cd teleport-plugins/access/slack
make

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

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.

# 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

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

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