

Teleport Role-based access request
Length: 01:17
You can set up Teleport to require the approval of multiple team members to perform some critical actions. Here are the most common scenarios:
- Improve the security of your system and prevent one successful phishing attack from compromising your system.
- Satisfy FedRAMP AC-3 Dual authorization control that requires approval of two authorized individuals.
In this guide, we will set up Teleport's Just-in-Time Access Requests to require the approval
of two team members for a privileged role dbadmin
.
This guide requires a commercial edition of Teleport. The open source edition of Teleport only supports GitHub as an SSO provider.
The steps below describe how to use Teleport with Mattermost. You can also integrate with many other providers.
Prerequisites
- Mattermost installed.
-
A running Teleport cluster, including the Auth Service and Proxy Service. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 12.1.1, which you can download by visiting the customer portal.tctl versionTeleport Enterprise v12.1.1 go1.19
tsh versionTeleport v12.1.1 go1.19
Please use the latest version of Teleport Enterprise documentation.
docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 12.1.1
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 statusCluster myinstance.teleport.sh
Version 12.1.1
CA pin sha256:sha-hash-here
You must run subsequent tctl
commands in this guide on your local machine.
Step 1/3. Set up a Teleport bot
Create a bot within Mattermost
Enable bot account creation in "System Console -> Integrations".
Toggle Enable Bot Account Creation
.

Go back to your team settings, navigate to "Integrations -> Bot Accounts". Press "Add Bot Account".

Add the "Post All" permission on the new account.

Create the bot and save the access token.
Set up RBAC for the plugin
Teleport's Access Request plugins authenticate to your Teleport cluster as a user with permissions to list and read Access Requests. This way, plugins can retrieve Access Requests from the Teleport Auth Service and present them to reviewers.
Define a user and role called access-plugin
by adding the following content to
a file called access-plugin.yaml
:
kind: role
version: v5
metadata:
name: access-plugin
spec:
allow:
rules:
- resources: ['access_request']
verbs: ['list', 'read']
- resources: ['access_plugin_data']
verbs: ['update']
---
kind: user
metadata:
name: access-plugin
spec:
roles: ['access-plugin']
version: v2
Create the user and role:
tctl create -f access-plugin.yaml
As with all Teleport users, the Teleport Auth Service authenticates the
access-plugin
user by issuing short-lived TLS credentials. In this case, we
will need to request the credentials manually by impersonating the
access-plugin
role and user.
If you are using tctl
from the Auth
Service host, you will already have impersonation privileges.
To grant your user impersonation privileges for access-plugin
, define a role
called access-plugin-impersonator
by pasting the following YAML document into
a file called access-plugin-impersonator.yaml
:
kind: role
version: v5
metadata:
name: access-plugin-impersonator
spec:
allow:
impersonate:
roles:
- access-plugin
users:
- access-plugin
Create the access-plugin-impersonator
role:
tctl create -f access-plugin-impersonator.yaml
Assign the access-plugin-impersonator
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding access-plugin-impersonator
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - access-plugin-impersonator
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding access-plugin-impersonator
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f github.yaml
Retrieve your saml
configuration resource:
tctl get saml/mysaml --with-secrets > saml.yaml
Edit saml.yaml
, adding access-plugin-impersonator
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding access-plugin-impersonator
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - access-plugin-impersonator
Apply your changes:
tctl create -f saml.yaml
Log out of your Teleport cluster and log in again to assume the new role.
You will now be able to generate signed certificates for the access-plugin
role and user.
Export the access-plugin identity files
Like all Teleport users, access-plugin
needs signed credentials in
order to connect to your Teleport cluster. You will use the tctl auth sign
command to request these credentials for your plugin.
The format of the credentials depends on whether you have set up your network to give the plugin direct access to the Teleport Auth Service, or if all Teleport clients and services connect to the Teleport Proxy Service instead.
Environment type
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
If your network allows your plugin to access the Auth Service directly, e.g., you are running the plugin on the Auth Service host, the plugin uses TLS credentials to connect to the Auth Service's gRPC endpoint and listen for new and updated Access Requests.
You can generate TLS credentials with the following command:
tctl auth sign --format=tls --user=access-plugin --out=auth
This command should result in three PEM-encoded files: auth.crt
,
auth.key
, and auth.cas
(certificate, private key, and CA certs
respectively). Later, you will configure the plugin to use these credentials to
connect to the Auth Service directly.
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth
Then create a Kubernetes secret:
kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
You will refer to this file later when configuring the plugin.
The following tctl auth sign
command impersonates the access-plugin
user,
generates signed credentials, and writes an identity file to the local
directory:
tctl auth sign --user=access-plugin --out=auth
Then create a Kubernetes secret:
kubectl create secret generic teleport-mattermost-identity --from-file=auth_id=auth.pem
Teleport's Access Request plugins listen for new and updated Access Requests by connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
The Helm chart only supports the file
format.
You will refer to this file later when configuring the plugin.
By default, tctl auth sign
produces certificates with a relatively short
lifetime. For production deployments, you can use the --ttl
flag to ensure a
more practical certificate lifetime, e.g., --ttl=8760h
to export a one-year
certificate.
We'll reference the exported file(s) later when configuring the plugin.
Install the plugin
curl -L https://get.gravitational.com/teleport-access-mattermost-v12.1.1-linux-amd64-bin.tar.gztar -xzf teleport-access-mattermost-v12.1.1-linux-amd64-bin.tar.gzcd teleport-access-mattermost./install
To install from source you need git
and go >= 1.19
installed.
Checkout teleport-plugins
git clone https://github.com/gravitational/teleport-plugins.gitcd teleport-plugins/access/mattermostmake
teleport-mattermost configure > /etc/teleport-mattermost.toml
Update the config with the Teleport address, Mattermost URL, and a bot token.
# 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" # Mattermost 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".
Please use the latest version of Teleport Enterprise documentation.
Step 2/3. Configure dual authorization
In this section, we will use an example to show you how to require dual authorization for a user to assume a role.
Require dual authorization for a role
Alice and Ivan are reviewers. They can approve requests for assuming role
dbadmin
. Bob is a DevOps engineer and can assume the dbadmin
role if two members
of the reviewer
role approve the request.
Create the following dbadmin
, reviewer
and devops
roles:
kind: role
version: v5
metadata:
name: reviewer
spec:
allow:
review_requests:
roles: ['dbadmin']
---
kind: role
version: v5
metadata:
name: devops
spec:
allow:
request:
roles: ['dbadmin']
thresholds:
- approve: 2
deny: 1
---
kind: role
version: v5
metadata:
name: dbadmin
spec:
allow:
logins: ['root']
node_labels:
'env': 'prod'
'type': 'db'
The commands below create the local users Bob, Alice, and Ivan.
tctl users add [email protected] --roles=devopstctl users add [email protected] --roles=reviewertctl users add [email protected] --roles=reviewer
Create an Access Request
Bob does not have a role dbadmin
assigned to him, but can create an Access Request for it.
Bob can create an Access Request for the dbadmin
role in the Web UI or CLI:

Bob has to set valid emails of Alice and Ivan matching in Mattermost.
tsh request create --roles=dbadmin [email protected],[email protected]
Chatbot will notify both Alice and Ivan:

Alice and Ivan can review and approve request using Web UI or CLI:

tsh request listID User Roles Created (UTC) Status
------------------------------------ --------------- ------- ------------------- -------
9c721e54-b049-4ef8-a7f6-c777aa066764 [email protected] dbadmin 03 Apr 21 03:58 UTC PENDING
tsh request review --approve --reason="hello" 9c721e54-b049-4ef8-a7f6-c777aa066764Successfully submitted review. Request state: APPROVED
If Bob has created a request using CLI, he will assume it once it has been approved. Bob can also assume granted Access Request roles using Web UI:

Troubleshooting
Cert errors in self-hosted deployments
You may be getting certificate errors if Teleport's Auth Service is missing an address in the server certificate:
authentication handshake failed: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs
x509: certificate is valid for,*.teleport.cluster.local, teleport.cluster.local, not example.com
To fix the problem, update the Auth Service with a public address, and restart Teleport:
auth_service:
public_addr: ['localhost:3025', 'example.com:3025']