Teleport

Teleport Mattermost Plugin Setup

This guide will explain how to set up Teleport with Mattermost, an open source messaging platform. Teleport's Mattermost integration allows teams to approve or deny Teleport Access Requests using Mattermost.

Example Mattermost request

Setup

Prerequisites

This guide assumes that you have:

A running Teleport Cluster
Admin privileges with access to tctl
A Mattermost account with admin privileges. This plugin has been tested with Mattermost 5.x

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.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

Setting up Mattermost to work with the bot

In Mattermost, go to System Console → Integrations → Enable Bot Account Creation → Set to True. This will allow you to create a new bot account that the Teleport bot will use.

Go back to your team, then Integrations → Bot Accounts → Add Bot Account.

The new bot account will need Post All permission.

App Icon: Download Teleport Bot Icon

Create an OAuth 2.0 application

In Mattermost, go to System Console → Integrations → OAuth 2.0 Applications.

Set Callback URLs to the location of your Teleport Proxy

The confirmation screen after you've created the bot will give you the access token. We'll use this in the config later.

Create User and Role resources 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 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.

Downloading and installing the 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 Service access.

curl -L -O https://get.gravitational.com/teleport-access-mattermost-v9.3.7-linux-amd64-bin.tar.gz
tar -xzf teleport-access-mattermost-v9.3.7-linux-amd64-bin.tar.gz
cd teleport-access-mattermost
./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/mattermost
make

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

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

Configuring Mattermost bot

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

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

Then, edit the config as needed.

# example mattermost configuration TOML file
[teleport]
auth_server = "example.com:3025"                             # Teleport Auth Server GRPC API address
client_key = "/var/lib/teleport/plugins/mattermost/auth.key" # Teleport GRPC client secret key
client_crt = "/var/lib/teleport/plugins/mattermost/auth.crt" # Teleport GRPC client certificate
root_cas = "/var/lib/teleport/plugins/mattermost/auth.cas"   # Teleport cluster CA certs

[mattermost]
url = "https://mattermost.example.com" # Mattermost Server URL
team = "team-name"                     # Mattermsot team in which the channel resides.
channel = "channel-name"               # Mattermost Channel name to post requests to
token = "api-token"                    # Mattermost Bot OAuth token
secret = "signing-secret-value"        # Mattermost API signing Secret

[http]
public_addr = "example.com" # URL on which callback server is accessible externally, e.g. [https://]teleport-mattermost.example.com
# listen_addr = ":8081" # Network address in format [addr]:port on which callback server listens, e.g. 0.0.0.0:443
https_key_file = "/var/lib/teleport/plugins/mattermost/server.key"  # TLS private key
https_cert_file = "/var/lib/teleport/plugins/mattermost/server.crt" # TLS certificate

[log]
output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/mattermost.log"
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".

# example mattermost configuration TOML file
[teleport]
auth_server = "myinstance.teleport.sh:443"                   # Teleport Cloud proxy HTTPS address
identity = "/var/lib/teleport/plugins/mattermost/auth.pem"   # Identity file path

[mattermost]
url = "https://mattermost.example.com" # Mattermost Server URL
team = "team-name"                     # Mattermsot team in which the channel resides.
channel = "channel-name"               # Mattermost Channel name to post requests to
token = "api-token"                    # Mattermost Bot OAuth token
secret = "signing-secret-value"        # Mattermost API signing Secret

[http]
public_addr = "example.com" # URL on which callback server is accessible externally, e.g. [https://]teleport-mattermost.example.com
# listen_addr = ":8081" # Network address in format [addr]:port on which callback server listens, e.g. 0.0.0.0:443
https_key_file = "/var/lib/teleport/plugins/mattermost/server.key"  # TLS private key
https_cert_file = "/var/lib/teleport/plugins/mattermost/server.crt" # TLS certificate

[log]
output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/mattermost.log"
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".

Testing the plugin

With the config above, you should be able to run the bot invoking teleport-mattermost start -d. The will provide some debug information to make sure the bot can connect to Mattermost.

teleport-mattermost start -d
DEBU   DEBUG logging enabled logrus/exported.go:117
INFO   Starting Teleport Access Mattermost Bot 9.3.7-dev.1: mattermost/main.go:140
DEBU   Checking Teleport server version mattermost/main.go:234
DEBU   Starting a request watcher... mattermost/main.go:296
DEBU   Starting Mattermost API health check... mattermost/main.go:186
DEBU   Starting secure HTTPS server on :8081 utils/http.go:146
DEBU   Watcher connected mattermost/main.go:260
DEBU   Mattermost API health check finished ok mattermost/main.go:19

Set up with 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 Mattermost Plugin
After=network.target

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/teleport-mattermost start --config=/etc/teleport-mattermost.toml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport-mattermost.pid

[Install]
WantedBy=multi-user.target

Save this as teleport-mattermost.service.

Audit log

The plugin will let anyone with access to the Mattermost channel requests so it's important to review Teleport's 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