Teleport

SSH login approvals using Jira

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.

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.

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 Helm chart only supports the file format.

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

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.

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.gz
tar -xzf teleport-access-jira-v12.1.1-linux-amd64-bin.tar.gz
cd 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.git
cd teleport-plugins/access/jira
make

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

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

Have a suggestion or can’t find something?

IMPROVE THE DOCS