
This guide will talk through how to set up Teleport with Jira. Teleport's Jira integration allows you to treat Teleport access and permission requests using Jira tickets.
Setup
This guide assumes that you have:
- A running Teleport Cluster
- Admin privileges with access to
tctl
- Jira Server or Jira Cloud installation with an owner privileges, specifically to set up webhooks, issue types, and workflows
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.
Create a user and role for access
Teleport's Access Request plugins authenticate to your Teleport cluster as a user with permissions to list, read, and update Access Requests. This way, plugins can retrieve Access Requests from the Teleport Auth Service, present them to reviewers, and modify them after a review.
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', 'update']
- 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
Retrieve your user definition:
TELEPORT_USER=$(tsh status --format=json | jq -r .active.username)tctl get users/${TELEPORT_USER?} > myuser.yaml
Edit myuser.yaml
to include the role you just created:
roles:
- access
- auditor
- editor
+ - access-plugin-impersonator
Apply your changes:
tctl create -f myuser.yaml
Log out of your Teleport cluster and log in again. You will now be able to
generate signed certificates for the access-plugin
role and user.
Export the access-plugin certificate
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 these files later when configuring the plugins.
Setting up your Jira project
Creating the permission management project
All new permission requests are going to show up in a project you choose. We recommend that you create a separate project for permissions management, and a new board in said project.
You'll need the project Jira key to configure the plugin.
Setting up the status board
Create a new board for tasks in the permission management project. The board has to have at least these three columns:
- Pending
- Approved
- Denied
Teleport's Jira plugin will create a new issue for each new permission request in the first available column on the board. When you drag the request task to the Approved column in Jira, the request will be approved. If you drag the request task to the Denied column in Jira, the request will be denied.
Getting your Jira API token
If you're using Jira Cloud, navigate to Account Settings → Security → API Tokens and create a new app specific API token in your Jira installation. You'll need this token later to configure the plugin.
For Jira Server, the URL of the API tokens page will be different depending on your installation.
Setting up Jira webhooks
Go to Settings → General → System → Webhooks and create a new webhook for Jira to tell the Teleport plugin about updates.
For the webhook URL, use the URL that you'll run the plugin on. It needs to be a publicly accessible URL (we will show you how to set this up later). Jira requires the webhook listener to run over HTTPS.
The webhook needs to be notified only about new issues being created, issues being updated, or deleted. You can leave all the other boxes empty.
Jira will send updates about any issues in any projects in your Jira installation to the webhook. We suggest that you use JQL filters to limit which issues are being sent to the plugin.
The plugin's web server will run with TLS, but you can disable it with --insecure-no-tls
to test things out in a dev environment.
In the webhook settings page, make sure that the webhook will only send Issue Updated updates. It's not critical if anything else gets sent, since the plugin will just ignore everything else.
Installing
We recommend installing 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-jira-v12.1.1-linux-amd64-bin.tar.gztar -xzf teleport-access-jira-v12.1.1-linux-amd64-bin.tar.gzcd teleport-access-jira./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.gitcd teleport-plugins/access/jiramake
Run ./install
from teleport-jira
or place the executable in /usr/bin
or /usr/local/bin
on the server installation.
docker pull public.ecr.aws/gravitational/teleport-plugin-jira:12.1.1
To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add
:
helm repo add teleport https://charts.releases.teleport.dev
To update the cache of charts from the remote repository, run helm repo update
:
helm repo update
Configuration file
Depending on whether you are running the plugin as an executable in a non-containerized environment or on Kubernetes, follow the appropriate instructions for your environment to configure the plugin:
Environment type
The Teleport Jira plugin uses a config file in TOML format. Generate a boilerplate config by running the following command:
teleport-jira configure > teleport-jira.tomlsudo mv teleport-jira.toml /etc
By default, the Jira Teleport plugin will use a config in
/etc/teleport-jira.toml
, and you can override it with -c config/file/path.toml
flag.
The configuration file will resemble the following:
# example jira plugin configuration TOML file
[teleport]
auth_server = "myinstance.teleport.sh:443" # Teleport Cloud proxy HTTPS address
identity = "/var/lib/teleport/plugins/jira/auth.pem" # Teleport identity file location
[jira]
url = "https://example.com/jira" # JIRA URL. For JIRA Cloud, https://[my-jira].atlassian.net
username = "[email protected]" # JIRA username
api_token = "token" # JIRA API Basic Auth token
project = "MYPROJ" # JIRA Project key
[http]
# listen_addr = ":8081" # Network address in format [addr]:port on which webhook server listens, e.g. 0.0.0.0:443
# public_addr = "example.com" # URL on which webhook server is accessible externally, e.g. [https://]teleport-jira.example.com
https_key_file = "/var/lib/teleport/plugins/jira/server.key" # TLS private key
https_cert_file = "/var/lib/teleport/plugins/jira/server.crt" # TLS certificate
[log]
output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/jira.log"
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
The Teleport Jira plugin uses a config file in TOML format. Generate a boilerplate config by running the following command:
teleport-jira configure > teleport-jira.tomlsudo mv teleport-jira.toml /etc
By default, the Jira Teleport plugin will use a config in
/etc/teleport-jira.toml
, and you can override it with -c config/file/path.toml
flag.
The configuration file will resemble the following:
# example jira plugin configuration TOML file
[teleport]
auth_server = "example.com:3025" # Teleport Auth Server GRPC API address
client_key = "/var/lib/teleport/plugins/jira/auth.key" # Teleport GRPC client secret key
client_crt = "/var/lib/teleport/plugins/jira/auth.crt" # Teleport GRPC client certificate
root_cas = "/var/lib/teleport/plugins/jira/auth.cas" # Teleport cluster CA certs
[jira]
url = "https://example.com/jira" # JIRA URL. For JIRA Cloud, https://[my-jira].atlassian.net
username = "[email protected]" # JIRA username
api_token = "token" # JIRA API Basic Auth token
project = "MYPROJ" # JIRA Project key
[http]
# listen_addr = ":8081" # Network address in format [addr]:port on which webhook server listens, e.g. 0.0.0.0:443
# public_addr = "example.com" # URL on which webhook server is accessible externally, e.g. [https://]teleport-jira.example.com
https_key_file = "/var/lib/teleport/plugins/jira/server.key" # TLS private key
https_cert_file = "/var/lib/teleport/plugins/jira/server.crt" # TLS certificate
[log]
output = "stderr" # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/jira.log"
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
Create a file called values.yaml
with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
teleport:
address: "myinstance.teleport.sh:443" # Teleport Cloud proxy HTTPS address
identityFromSecret: teleport-plugin-jira-identity # Secret containing identity
jira:
url: https://jira.example.com/ # URL of the Jira instance
username: [email protected] # Email of the bot user
apiToken: token # Token of the bot user
project: MYPROJ # Project where issues will be created
http:
publicAddress: https://jira-teleport.example.com/ # Publicly available
tlsFromSecret: teleport-plugin-jira-tls # Secret containing the TLS certificate
# tlsKeySecretPath: tls.key # Name of the key inside the secret
# tlsCertSecretPath: tls.crt # Name of the certificate inside the secret
log:
output: stderr # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/jira.log"
severity: INFO # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
Use the following command to create the Kubernetes secret referenced in the values file from the identity file you generated earlier:
kubectl create secret generic teleport-plugin-jira-identity --from-file=auth_id=auth.pem
Create a file called values.yaml
with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
teleport:
address: "teleportauth:3025" # Teleport Auth Server GRPC API address
identityFromSecret: teleport-plugin-jira-identity # Secret containing identity
jira:
url: https://jira.example.com/ # URL of the Jira instance
username: [email protected] # Email of the bot user
apiToken: token # Token of the bot user
project: MYPROJ # Project where issues will be created
http:
publicAddress: https://jira-teleport.example.com/ # Publicly available
tlsFromSecret: teleport-plugin-jira-tls # Secret containing the TLS certificate
# tlsKeySecretPath: tls.key # Name of the key inside the secret
# tlsCertSecretPath: tls.crt # Name of the certificate inside the secret
log:
output: stderr # Logger output. Could be "stdout", "stderr" or "/var/lib/teleport/jira.log"
severity: INFO # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
Use the following command to create the Kubernetes secret referenced in the values file from the identity file you generated earlier:
kubectl create secret generic teleport-plugin-jira-identity --from-file=auth_id=auth.pem
The [teleport]
section describes where the teleport service running, and what keys should the plugin use to authenticate itself. Use the keys that you've generated.
The [jira]
section requires a few things:
- Your Jira Cloud or Jira Server URL. For Jira Cloud, it looks something like
yourcompany.atlassian.net
. - Your username on Jira, i.e. [email protected]
- Your Jira API token that you've created above.
- A Jira Project key, available in Project settings.
The [http]
setting block describes how the plugin's HTTP server works. The HTTP server is responsible for listening for updates from Jira, and processing updates, like when someone drags a task from Inbox to Approved column.
You must provide an address the server should listen on, and a certificate to use. It's possible to run the Jira plugin on the same server as the Teleport Proxy, so you can use the same TLS certificate.
Testing
You should be able to run the Teleport plugin now!
teleport-jira start
helm install teleport-plugin-jira teleport/teleport-plugin-jira \ --values teleport-jira-helm.yaml \ --version 12.1.1
The log output should look familiar to what Teleport service logs. You should see that it connected to Teleport, and is listening for new Teleport requests and Jira webhooks.
Go ahead and test it:
tsh login --request-roles=admin
That should create a new permission request on Teleport (you can test if it did with tctl request ls
), and you should see a new task on your Jira project board.
Set up 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 Jira Plugin
After=network.target
[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/teleport-jira start --config=/etc/teleport-jira.toml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/teleport-jira.pid
[Install]
WantedBy=multi-user.target
Save this as teleport-jira.service
. Make sure the teleport-jira start
command includes a --config
flag that refers to the configuration file you created earlier.
Audit log
The plugin will let anyone with access to the Jira board approve/deny 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.
Next steps
To see all of the options available to you when using the Helm chart for the Teleport Jira plugin, consult our reference guide.