Fork me on GitHub

Teleport Mattermost Plugin Setup


This guide will talk through how to setup Teleport with Mattermost. Teleport to Mattermost integration allows teams to approve or deny Teleport access requests using Mattermost an open source messaging platform.

Example Mattermost Request



This guide assumes that you have:

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

Setting up Mattermost to work with the bot

Enable Mattermost bots

In Mattermost, go to System Console → Integrations → Enable Bot Account Creation → Set to True. This will allow us 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

Enable Mattermost Bots
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
Create OAuth Application

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

# This command will create two Teleport Yaml resources, a new Teleport user and a
# Role for that users that can only approve / list requests.
$ cat > rscs.yaml <<EOF
kind: user
  name: access-plugin-mattermost
  roles: ['access-plugin-mattermost']
version: v2
kind: role
  name: access-plugin-mattermost
      - resources: ['access_request']
        verbs: ['list','read','update']
    # teleport currently refuses to issue certs for a user with 0 logins,
    # this restriction may be lifted in future versions.
    logins: ['access-plugin-mattermost']
version: v4

# Run this to create the user and role in Teleport.
$ tctl create -f rscs.yaml

Export access-plugin Certificate

Teleport Plugin use the access-plugin-mattermost role and user to perform the approval. We export the identity files, using tctl auth sign.

tctl auth sign --format=tls --user=access-plugin-mattermost --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

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 access. We currently only provide linux-amd64 binaries, you can also compile these plugins from source.

tar -xzf teleport-access-mattermost-v7.3.2-linux-amd64-bin.tar.gz
cd teleport-access-mattermost
which teleport-mattermost


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

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
auth_server = ""                             # 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

url = "" # 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

public_addr = "" # URL on which callback server is accessible externally, e.g. [https://]
# listen_addr = ":8081" # Network address in format [addr]:port on which callback server listens, e.g.
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

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

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:

Description=Teleport Mattermost Plugin

ExecStart=/usr/local/bin/teleport-mattermost start --config=/etc/teleport-mattermost.toml
ExecReload=/bin/kill -HUP $MAINPID


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.


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

Have a suggestion or can’t find something?