| title | description | h1 |
|---|---|---|
SSH login approval using Jira and Teleport |
How to configure SSH login approval using Jira and Teleport |
SSH login approvals using Jira |
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.
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.
(!docs/pages/includes/plugins/rbac-update.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx!)
We'll reference these files later when configuring the plugins.
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.
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.
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.
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.
<Admonition type="note" title="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.
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.
```code $ curl -L -O https://get.gravitational.com/teleport-access-jira-v(=teleport.plugin.version=)-linux-amd64-bin.tar.gz $ tar -xzf teleport-access-jira-v(=teleport.plugin.version=)-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](https://go.dev/dl/).# 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:(=teleport.plugin.version=)
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:
(!examples/resources/plugins/teleport-jira-cloud.toml!)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:
(!examples/resources/plugins/teleport-jira-self-hosted.toml!)Create a file called values.yaml with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
(!examples/resources/plugins/teleport-jira-helm-cloud.yaml!)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.pemCreate a file called values.yaml with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
(!examples/resources/plugins/teleport-jira-helm-self.yaml!)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.pemThe [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.
You should be able to run the Teleport plugin now!
```code $ teleport-jira start ``` ```code $ helm install teleport-plugin-jira teleport/teleport-plugin-jira \ --values teleport-jira-helm.yaml \ --version (=teleport.plugin.version=) ```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.
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:
(!examples/systemd/plugins/teleport-jira.service!)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.
The plugin will let anyone with access to the Jira board approve/deny requests so it's important to review Teleport's audit log.
If you have any issues with this plugin please create an issue here.
To see all of the options available to you when using the Helm chart for the Teleport Jira plugin, consult our reference guide.