Access Requests using Jira and Teleport

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

• 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 run tctl commands on your administrative workstation using your current credentials. For example:

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

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl 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.

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.

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

curl -L -O https://get.gravitational.com/teleport-access-jira-v14.0.0-linux-amd64-bin.tar.gz
tar -xzf teleport-access-jira-v14.0.0-linux-amd64-bin.tar.gz
cd teleport-access-jira
sudo ./install

teleport-jira version
teleport-jira v14.0.0 git:teleport-jira-v14.0.0-fffffffff go1.21

git clone https://github.com/gravitational/teleport-plugins.git
cd teleport-plugins/access/jira
make

teleport-jira version
teleport-jira v14.0.0 git:teleport-jira-v14.0.0-fffffffff go1.21

helm repo add teleport https://charts.releases.teleport.dev

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:

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

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

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

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.