Fork me on GitHub
Teleport

SSH login approvals using Jira

Improve

Teleport Jira Plugin Setup

This guide will talk through how to setup Teleport with Jira. Teleport to 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 setup webhooks, issue types, and workflows

Create an access-plugin role and user within Teleport

First off, using an existing Teleport Cluster, we are going to create a new Teleport User and Role to access Teleport.

Create User and Role for access

Log into Teleport Authentication Server, this is where you normally run tctl. Create a new user and role that only has API access to the access_request API. The below script will create a yaml resource file for a new user and role.

cat > rscs.yaml <<EOF
kind: user
metadata:
  name: access-plugin-jira
spec:
  roles: ['access-plugin-jira']
version: v2
---
kind: role
metadata:
  name: access-plugin-jira
spec:
  allow:
    rules:
      - resources: ['access_request']
        verbs: ['list','read','update']
    # teleport currently refuses to issue certs for a user with 0 logins,
    # this restriction may be lifted in future versions.
    logins: ['access-plugin-jira']
version: v4
EOF

# ...
$ tctl create -f rscs.yaml

Export access-plugin Certificate

Teleport Plugin use the access-plugin-jira role and user to perform the approval. We export the identity files, using tctl auth sign.

tctl auth sign --format=tls --user=access-plugin-jira --out=auth --ttl=2190h
# ...

The above sequence should result in three PEM encoded files being generated: auth.crt, auth.key, and auth.cas (certificate, private key, and CA certs respectively). We'll reference the auth.crt, auth.key, and auth.cas files later when configuring the plugins.

Certificate Lifetime

By default, tctl auth sign produces certificates with a relatively short lifetime. For production deployments, the --ttl flag can be used to ensure a more practical certificate lifetime. --ttl=8760h exports a 1 year token

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:

  1. Pending
  2. Approved
  3. Denied

Teleport 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 Approved column on Jira, the request will be approved. If you drag the request task to the Denied column in Jira, the request will be denied.

Setting up Request ID field on Jira

Teleport Jira Plugin requires a custom issue field to be created.

Go to your Jira Project settings → Issue Types → Select type Task → add a new Short Text field named TeleportAccessRequestId.

Teleport uses this field to reference its internal request ID. If anyone changes this field on Jira, or tries to forge the permission request, Teleport will validate it and ignore it.

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 that we'll set up later. Jira requires the webhook listener to run over HTTPS.

The Teleport Jira plugin 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 Webhook 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, the plugin will just ignore everything else.

Installing

We recommend installing the 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 access. We currently only provide linux-amd64 binaries, you can also compile these plugins from source.

wget https://get.gravitational.com/teleport-access-jira-v7.3.2-linux-amd64-bin.tar.gz
tar -xzf teleport-access-jira-v7.3.2-linux-amd64-bin.tar.gz
cd teleport-access-jira/
./install
which teleport-jira

/usr/local/bin/teleport-jira

Run ./install in from 'teleport-jira' or place the executable in the appropriate /usr/bin or /usr/local/bin on the server installation.

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

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:

  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. [email protected]
  3. Your Jira API token that you've created above.
  4. A Jira Project key, available in Project settings.

[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 setup 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

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.

Setup with SystemD

In production, we recommend starting 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/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.

Have a suggestion or can’t find something?
IMPROVE THE DOCS