Fork me on GitHub

Teleport

Access Requests using Jira and Teleport

  • 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 and tsh 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 version

    Teleport Enterprise v14.0.0 go1.21


    tsh version

    Teleport v14.0.0 go1.21

Cloud is not available for Teleport v.
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 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.

Certificate Lifetime

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.

Plugin Defaults

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.gz
tar -xzf teleport-access-jira-v14.0.0-linux-amd64-bin.tar.gz
cd teleport-access-jira
sudo ./install

Make sure the binary is installed:

teleport-jira version
teleport-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.git
cd teleport-plugins/access/jira
make

Move the teleport-jira binary into your PATH.

Make sure the binary is installed:

teleport-jira version
teleport-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.toml
sudo 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.