
Teleport
Access Requests using Jira and Teleport
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- Enterprise
- Cloud
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.
Prerequisites
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0. You can download these tools by visiting your Teleport account. You can verify the tools you have installed by running the following commands:tctl versionTeleport Enterprise v14.0.0 go1.21
tsh versionTeleport v14.0.0 go1.21
Please use the latest version of Teleport Enterprise documentation.
- Jira Server or Jira Cloud installation with an owner privileges, specifically to set up webhooks, issue types, and workflows
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/6. 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 running a self-hosted Teleport Enterprise deployment and 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.
Step 2/6. 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 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
The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS.
The identity file, auth.pem
, includes both TLS and SSH credentials. The 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.
By default, tctl auth sign
produces certificates with a relatively short
lifetime. For production deployments, we suggest using Machine
ID to programmatically issue and renew
certificates for your plugin. See our Machine ID getting started
guide to learn more.
Note that you cannot issue certificates that are valid longer than your existing credentials.
For example, to issue certificates with a 1000-hour TTL, you must be logged in with a session that is
valid for at least 1000 hours. This means your user must have a role allowing
a max_session_ttl
of at least 1000 hours (60000 minutes), and you must specify a --ttl
when logging in:
tsh login --proxy=teleport.example.com --ttl=60060
We'll reference these files later when configuring the plugin.
Step 3/6. Set up your Jira project
Create 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.
Set 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.
Get 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.
Set 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.
Step 4/6. Install the plugin
We currently only provide linux-amd64
binaries. You can also compile these
plugins from source. You can run the plugin from a remote host or your local
development machine.
curl -L -O https://get.gravitational.com/teleport-access-jira-v14.0.0-linux-amd64-bin.tar.gztar -xzf teleport-access-jira-v14.0.0-linux-amd64-bin.tar.gzcd teleport-access-jirasudo ./install
Make sure the binary is installed:
teleport-jira versionteleport-jira v14.0.0 git:teleport-jira-v14.0.0-fffffffff go1.21
To install from source you need git
and go
installed. If you do not have Go
installed, visit the Go downloads page.
git clone https://github.com/gravitational/teleport-plugins.gitcd teleport-plugins/access/jiramake
Move the teleport-jira
binary into your PATH.
Make sure the binary is installed:
teleport-jira versionteleport-jira v14.0.0 git:teleport-jira-v14.0.0-fffffffff go1.21
Allow Helm to install charts that are hosted in the Teleport Helm repository:
helm repo add teleport https://charts.releases.teleport.dev
Update the cache of charts from the remote repository:
helm repo update
Step 5/6. Configure the plugin
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:
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".
Create a file called values.yaml
with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
teleport:
# Teleport HTTPS Proxy web address, for Teleport Enterprise Cloud should be in the form "your-account.teleport.sh:443"
address: "teleport.example.com:443"
# Secret containing identity
identitySecretName: teleport-plugin-jira-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]
sections includes configuration options for connecting the Jira
plugin to Teleport.
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.
Step 6/6. Test the plugin
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 14.0.0
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.
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.