Fork me on GitHub

Teleport

SSH login approvals using Jira Server

Improve

This guide will talk through how to set up Teleport with Jira Server. Teleport's integration with Jira Server allows you to treat Teleport access and permission requests as Jira tasks.

Note

Teleport's tsh request workflow is synchronous and needs to be approved within 1 hour of the request.

Setup

Prerequisites

  • A running Teleport Cluster
  • Admin Privileges with access and control of tctl
  • A Jira Server installation with owner privileges, specifically to set up webhooks, issue types, and workflows. This plugin has been tested with Jira Software 8.8.0

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

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.

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 Server instance

Creating a project

The Teleport Jira plugin relies on your Jira project having a board with at least three statuses (columns): Pending, Approved, and Denied. It's therefore the easiest scenario to create a new Jira project for Teleport to use.

The specific type of project you choose when you create it doesn't matter, as long as you can setup a Kanban Board for it, but we recommend that you go with Kanban Software Development. This will reduce the amount of setup work you'll have to do and provide the board out of the box.

You'll need the project key for the Teleport plugin settings later on. It's usually a 3 character code for the project.

Setting up a request ID field on Jira

Teleport stores the request metadata in a special Jira custom field that must be named teleportAccessRequestId. To create that field, go to Administration -> Issues -> Custom Fields -> Add Custom Field.

Name the field teleportAccessRequestId, and choose Text Field (single line) as the field type. Assign the field to your project, or make it global. Teleport Access Request ID is an internal field and it's not supposed to be edited by users, so you can leave the Screens section blank. That means that the field won't show up in Jira's UI.

Go to Project Settings -> Fields and make sure that the teleportAccessRequestId field shows up on the list of fields available in this project.

Setting up the status board

The default Jira Software workflow has a different board setup than what Teleport needs, so we'll set up another workflow and assign that workflow to the project board.

Go to Administration -> Workflows. You can choose to add a new workflow (recommended), or edit the existing workflow. It will be called Software Simplified Workflow for Project NAME by default. It's only used in your single project, so it's safe to edit it.

Edit the workflow to have these three states:

  1. Pending
  2. Approved
  3. Denied

The rules of the workflow must meet these requirements:

  • New created issues should be in Pending state.
  • It should be possible to move from Pending to Approved
  • It should be possible to move from Pending to Declined.
  • You can choose to make the workflow strict and restrict moving requests from Approved state to Declined state and vice versa, or leave that flexible. Teleport will only change the request status once, i.e. the first time the request is approved or denied on your Jira board.

With the Jira workflow editor, you can set up who can approve or deny an access request based on their Jira user permissions. We won't cover that in this guide as it mostly relates to Jira settings. By default Teleport will allow anyone who can use the workflow to approve or deny the request.

Go to your Project Settings -> Workflows, and make sure that the workflow that you just created or edited is applied to the project you'll use for Teleport integration.

Setting up the webhook

Teleport Jira Plugin will listen for a webhook that Jira Server sends when a request is approved or denied. Go to Settings -> System -> Webhooks to set up the webhook. The webhook needs to be sent when issues are updated or deleted.

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-v10.1.2-linux-amd64-bin.tar.gz
tar -xzf teleport-access-jira-v10.1.2-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 the appropriate /usr/bin or /usr/local/bin on the server installation.

docker pull quay.io/gravitational/teleport-plugin-jira:10.1.2

Configuration file

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.

# 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".
# 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] section describes where the Teleport service is running, and what keys the plugin should use to authenticate itself. Use the keys that you've generated above.

The [jira] section requires a few things:

  1. Your Jira Cloud or Jira Server URL. For Jira Cloud, it looks something like yourcompany.atlassian.net.
  2. Your username on Jira, i.e. benarent Note: Not your email address.
  3. Your Jira API token. For Jira Server, this is a password. It's a good idea to create a separate user record with permissions limited to accessing this particular project board, and use this with the bot.
  4. And the 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, unless you plan on running with --insecure-no-tls, which we don't recommend in production.

Testing

You should be able to run the Teleport plugin now!

teleport-jira start

INFO Starting Teleport Access JIRAbot 0.1.0-alpha.3:teleport-jira-v0.1.0-alpha.3-0-gea1ef8e jira/app.go:74

DEBU Checking Teleport server version jira/app.go:150

DEBU Starting JIRA API health check... jira/app.go:111

DEBU Checking out JIRA project... jira/bot.go:145

DEBU Found project "TEL1": "Tel-kb" jira/bot.go:150

DEBU Checking out JIRA project permissions... jira/bot.go:152

DEBU JIRA API health check finished ok jira/app.go:117

DEBU Starting secure HTTPS server on 66.66.66.66:8081 utils/http.go:235

DEBU Watcher connected access/service_job.go:62

The log output should look familiar to what the 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.

Audit log

The plugin will let anyone with access to the Jira board approve or 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.