opensource/teleport
3
0
Fork 0
mirror of https://github.com/gravitational/teleport.git synced 2026-09-24 16:17:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refresh the Jira Access Request plugin guide (#35635)

Browse Source 
Closes #14580
Closes #17528

Get the Jira guide to follow the structure of other Access Request
plugin guides, including instructions for Teleport Cloud and Machine ID
users.

Also make some small adjustments for clarity and readability:
- Flesh out the intro to include sarchitectural information.
- Make the prerequisites list more comprehensive.
- Fix the list of columns required in the project board, which is out of
  date.
- Mention the `/status` endpoint of the webhook.
This commit is contained in:
Paul Gottschling
2023-12-19 21:39:53 +00:00
committed by GitHub
parent fd08933d0d
commit 9ff60d63b2
5 changed files with 416 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/img/enterprise/plugins/jira/board-setup.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 486 KiB

docs/img/enterprise/plugins/jira/new-request.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 461 KiB

docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx
+388 -124
View File
@@ -1,188 +1,452 @@
---
title: Run the Jira Access Request Plugin
description: How to configure Access Request approval using Jira and Teleport
description: How to set up the Teleport Jira plugin to notify users when another user requests elevated privileges.
---
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 explains how to set up the Teleport Access Request plugin for Jira.
Teleport's Jira integration allows you to manage Teleport Access Requests as
Jira issues.
The Teleport Jira plugin synchronizes a Jira project board with the Access
Requests processed by your Teleport cluster. When you change the status of an
Access Request within Teleport, the plugin updates the board. And when you
update the status of an Access Request on the board, the plugin notifies a Jira
webhook run by the plugin, which modifies the Access Request in Teleport.
<Details title="This integration is hosted on Teleport Cloud" open={false}>
(!docs/pages/includes/plugins/enroll.mdx name="the Mattermost integration"!)
</Details>
## Prerequisites
(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
- Jira Server or Jira Cloud installation with an owner privileges, specifically
to set up webhooks, issue types, and workflows
(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
- A Jira account with permissions to create applications and webhooks.
- A registered domain name for the Jira webhook. Jira notifies the webhook of
changes in your project board.
- An environment where you will run the Jira plugin. This is either:
- A Linux virtual machine with ports `80` and `8081` open, plus a means of
accessing the host (e.g., OpenSSH with an SSH port exposed to your
workstation).
- A Kubernetes cluster deployed via a cloud provider. This guide shows you how
to allow traffic to the Jira plugin via a `LoadBalancer` service, so your
environment must support services of this type.
- A means of providing TLS credentials for the Jira webhook run by the plugin.
- If you run the plugin on a Linux server, you must provide TLS credentials to
a directory available to the plugin.
- If you run the plugin on Kubernetes, you must write these credentials to a
secret that the plugin can read.
- (!docs/pages/includes/tctl.mdx!)
## Step 1/6. Create a user and role for access
## Step 1/7. Define RBAC resources
### Enable Role Access Requests
Before you set up the Jira plugin, you need to enable Role Access Requests in
your Teleport cluster.
(!docs/pages/includes/plugins/editor-request-rbac.mdx!)
### Create a user and role for the plugin
(!docs/pages/includes/plugins/rbac-update.mdx!)
## Step 2/6. Export the access-plugin certificate
## Step 2/7. Install the Teleport Jira plugin
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)
Install the Teleport Jira plugin following the instructions below, which depend
on whether you are deploying the plugin on a host (e.g., an EC2 instance) or a
Kubernetes cluster.
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](https://id.atlassian.com/manage-profile/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.
<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.
</Admonition>
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
The Teleport Jira plugin must run on a host or Kubernetes cluster that can
access both Jira and your Teleport Proxy Service (or Teleport Enterprise Cloud
tenant).
(!docs/pages/includes/plugins/install-access-request.mdx name="jira"!)
## Step 5/6. Configure the plugin
## Step 3/7. Export the access plugin identity
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:
Give the plugin access to a Teleport identity file. We recommend using Machine
ID for this in order to produce short-lived identity files that are less
susceptible to exfiltration, though in demo deployments, you can generate
longer-lived identity files with `tctl`:
<Tabs>
<TabItem
label="Executable"
>
<TabItem label="Machine ID">
(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-plugin-slack-identity"!)
</TabItem>
<TabItem label="Long-lived identity files">
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin" secret="teleport-plugin-jira-identity"!)
</TabItem>
</Tabs>
The Teleport Jira plugin uses a config file in TOML format. Generate a
boilerplate config by running the following command:
## Step 4/7. Set up a Jira project
In this section, you will create a Jira a project that the Teleport plugin can
modify when a Teleport user creates or updates an Access Request. The plugin
then uses the Jira webhook to monitor the state of the board and respond to any
changes in the tickets it creates.
### Create a project for managing Access Requests
In Jira, find the top navigation bar and click **Projects** -> **Create
project**. Select **Kanban** for the template, then **Use template**. Click
**Select a company-managed project**.
You'll see a screen where you can enter a name for your project. In this guide,
we assume that your project is called "Teleport Access Requests", which
receives the key `TAR` by default.
Make sure "Connect repositories, documents, and more" is unset, then click
**Create project**.
In the three-dots menu on the upper right of your new board, click **Board
settings**, then click **Columns**. Edit the statuses in your board so it
contains the following four:
1. Pending
1. Approved
1. Denied
1. Expired
Create a column with the same name as each status. The result should be the
following:
![Jira board setup](../../../img/enterprise/plugins/jira/board-setup.png)
<Notice type="warning">
If your project board does not contain these (and only these) columns, each with
a status of the same name, the Jira Access Request plugin will behave in
unexpected ways. Remove all other columns and statuses.
</Notice>
Click **Back to board** to review your changes.
### Set up a request ID field
The Teleport Jira plugin expects tasks in the Teleport Access Requests project
to include a field called `teleportAccessRequestId`, which it uses to track
individual Access Requests. This prevents users from tampering with or forging
Access Requests.
To set up the `teleportAccessRequestId` field, click **Project settings** on the
left navigation bar, then click **Issues** -> **Fields**.
In the **Actions** menu, click **Edit fields**. Click the **Custom fields** tab
in the left sidebar, then **Create custom field**. Add a **Short Text** field
named `teleportAccessRequestId`. Click the checkbox next to **Default Screen**
to associate that field with this screen. Click **Update**.
Next, add the custom field to your Teleport Access Requests project. Click
**Projects** > **Teleport Access Requests (TAR)**, then **Project settings**.
Click **Issues** -> **Types** on the left sidebar, then click **Task** >
**Fields**. Find the dropdown menu called **Select Field**, then select the
`teleportAccessRequestId` field you added earlier.
### Retrieve your Jira API token
Obtain an API token that the Teleport Access Request plugin uses to make
changes to your Jira project. Click the gear menu at the upper right of the
screen, then click **Atlassian account settings**. Click **Security** >
**Create and manage API tokens** > **Create API token**.
Choose any label and click **Copy**. Paste the API token into a convenient
location (e.g., a password manager or local text document) so you can use it
later in this guide when you configure the Jira plugin.
### Set up a Jira webhook
Now that you have generated an API key that the Teleport Jira plugin uses to
manage your project, enable Jira to notify the Teleport Jira plugin when your
project is updated by creating a webhook.
Return to Jira. Click the gear menu on the upper right of the screen. Click
**System** > **WebHooks** > **Create a WebHook**.
<Tabs>
<TabItem label="Executable">
Enter "Teleport Access Request Plugin" in the "Name" field. In the "URL" field,
enter the domain name you created for the plugin earlier, plus port `8081`.
</TabItem>
<TabItem label="Helm Chart">
Enter "Teleport Access Request Plugin" in the "Name" field. In the "URL" field,
enter the domain name you created for the plugin earlier, plus port `443`.
</TabItem>
</Tabs>
The webhook needs to be notified only when an issue is created, updated, or
deleted. You can leave all the other boxes empty.
Click **Create**.
## Step 6/7. Configure the Jira Access Request plugin
Earlier, you retrieved credentials that the Jira plugin uses to connect to
Teleport and the Jira API. You will now configure the plugin to use these
credentials and run the Jira webhook at the address you configured earlier.
### Create a configuration file
<Tabs>
<TabItem label="Executable or Docker">
The Teleport Jira plugin uses a configuration file in TOML format. Generate a
boilerplate configuration by running the following command (the plugin will not run
unless the config file is in `/etc/teleport-jira.toml`):
```code
$ teleport-jira configure > teleport-jira.toml
$ sudo mv teleport-jira.toml /etc
$ teleport-jira configure | sudo tee /etc/teleport-jira.toml > /dev/null
```
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:
This should result in a configuration file like the one below:
```toml
(!examples/resources/plugins/teleport-jira-cloud.toml!)
```
</TabItem>
<TabItem
label="Helm Chart"
>
Create a file called `values.yaml` with the following content, which configures
the Helm chart for the plugin. It should resemble the following:
<TabItem label="Helm chart">
The Helm chart for the Jira plugin uses a YAML values file to configure the
plugin. On your local workstation, create a file called
`teleport-jira-helm.yaml` based on the following example:
```yaml
(!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:
```console
kubectl create secret generic teleport-plugin-jira-identity --from-file=auth_id=auth.pem
```
</TabItem>
</Tabs>
The `[teleport]` sections includes configuration options for connecting the Jira
plugin to Teleport.
### Edit the configuration file
The `[jira]` section requires a few things:
Open the configuration file created for the Teleport Jira plugin and update the
following fields:
- Your Jira Cloud or Jira Server URL. For Jira Cloud, it looks something like `yourcompany.atlassian.net`.
- Your username on Jira, i.e. [ben@goteleport.com](mailto:ben@goteleport.com)
- Your Jira API token that you've created above.
- A Jira Project key, available in Project settings.
**`[teleport]`**
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.
The Jira plugin uses this section to connect to your Teleport cluster:
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.
(!docs/pages/includes/plugins/config-toml-teleport.mdx!)
## Step 6/6. Test the plugin
You should be able to run the Teleport plugin now!
(!docs/pages/includes/plugins/refresh-plugin-identity.mdx!)
<Tabs>
<TabItem label="Executable" scopes={["oss", "enterprise", "cloud"]}>
```code
$ teleport-jira start
```
<TabItem label="Executable">
### `jira`
**url:** The URL of your Jira tenant, e.g., `https://[your-jira].atlassian.net`.
**username:** The username you were logged in as when you created your API
token.
**api_token:** The Jira API token you retrieved earlier.
**project:** The project key for your project, which in our case is `TAR`.
You can leave `issue_type` as `Task` or remove the field, as `Task` is the
default.
### `http`
The `[http]` setting block describes how the plugin's webhook works.
**listen_addr** indicates the address that the plugin listens on, and defaults
to `:8081`. If you opened port `8081` on your plugin host as we recommended
earlier in the guide, you can leave this option unset.
**public_addr** is the public address of your webhook. This is the domain name you
added to the DNS A record you created earlier.
**https_key_file** and **https_cert_file** correspond to the private key and
certificate you generated earlier via Caddy. Use the following values, assigning
<Var name="example.com" /> to the domain name you created for the plugin
earlier:
- **https_key_file:**
```code
$ /var/teleport-jira/tls/certificates/acme-v02.api.letsencrypt.org-directory/<Var name="example.com" />/<Var name="example.com" />.key
```
- **https_cert_file:**
```code
$ /var/teleport-jira/tls/certificates/acme-v02.api.letsencrypt.org-directory/<Var name="example.com" />/<Var name="example.com" />.crt
```
</TabItem>
<TabItem label="Helm Chart" scopes={["oss", "enterprise", "cloud"]}>
```code
$ helm install teleport-plugin-jira teleport/teleport-plugin-jira \
--values teleport-jira-helm.yaml \
--version (=teleport.plugin.version=)
```
<TabItem label="Helm Chart">
### `jira`
**url:** The URL of your Jira tenant, e.g., `https://[your-jira].atlassian.net`.
**username:** The username you were logged in as when you created your API
token.
**apiToken:** The API token you retrieved earlier.
**project:** The project key for your project, which in our case is `TAR`.
You can leave `issueType` as `Task` or remove the field, as `Task` is the
default.
### `http`
The `http` setting block describes how the plugin's webhook works.
**publicAddress:** The public address of your webhook. This is the domain name
you created for your webhook. (We will create a DNS record for this domain name
later.)
**tlsFromSecret:** The name of a Kubernetes secret containing TLS credentials
for the webhook. Use `teleport-plugin-jira-tls`. We will create a `Certificate`
resource later that populates this secret with TLS credentials.
</TabItem>
</Tabs>
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.
## Step 7/8. Run the Jira plugin
Go ahead and test it:
After finishing your configuration, you can now run the plugin and test your
Jira-based Access Request flow:
<Tabs>
<TabItem label="Executable">
Run the following on your Linux host:
```code
$ tsh login --request-roles=admin
$ sudo teleport-jira start
INFO Starting Teleport Jira Plugin 12.1.1: jira/app.go:112
INFO Plugin is ready jira/app.go:142
```
</TabItem>
<TabItem label="Helm Chart">
Install the Helm chart for the Teleport Jira plugin:
```code
$ helm install teleport-plugin-jira teleport/teleport-plugin-jira \
--namespace teleport \
--values values.yaml \
--version (=teleport.plugin.version=)
```
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.
Create a DNS record that associates the webhook's domain name with the address
of the load balancer created by the Jira plugin Helm chart.
### Set up systemd
See whether the load balancer has a domain name or IP address:
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:
```code
$ kubectl -n teleport get services/teleport-plugin-jira
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
teleport-plugin-jira LoadBalancer 10.100.135.75 abc123.us-west-2.elb.amazonaws.com 80:30625/TCP,443:31672/TCP 134m
```
If the `EXTERNAL-IP` field has a domain name for the value, create a `CNAME`
record in which the domain name for your webhook points to the domain name of
the load balancer.
If the `EXTERNAL-IP` field's value is an IP address, create a DNS `A` record
instead.
You can then generate signed TLS credentials for the Jira plugin, which expects
them to be written to a Kubernetes secret.
</TabItem>
</Tabs>
### Check the status of the webhook
Confirm that the Jira webhook has started serving by sending a GET request to
the `/status` endpoint. If the webhook is running, it will return a `200` status
code with no document body:
<Tabs>
<TabItem label="Executable">
```code
$ curl -v https://<Var name="example.com" />:8081/status 2>&1 | grep "^< HTTP/2"
< HTTP/2 200
```
</TabItem>
<TabItem label="Helm Chart">
```code
$ curl -v https://<Var name="example.com" />:443/status 2>&1 | grep "^< HTTP/2"
< HTTP/2 200
```
</TabItem>
</Tabs>
### Create an Access Request
Sign in to your cluster as the `myuser` user you created earlier and create an
Access Request:
(!docs/pages/includes/plugins/create-request.mdx!)
When you create the request, you will see a new task in the "Pending" column of
the Teleport Access Requests board:
![New Access Request](../../../img/enterprise/plugins/jira/new-request.png)
### Resolve the request
Move the card corresponding to your new Access Request to the "Denied" column,
then click the card and navigate to Teleport. You will see that the Access
Request has been denied.
<Admonition title="Auditing Access Requests">
Anyone with access to the Jira project board can modify the status of Access
Requests reflected on the board. You can check the Teleport audit log to ensure
that the right users are reviewing the right requests.
When auditing Access Request reviews, check for events with the type `Access
Request Reviewed` in the Teleport Web UI.
</Admonition>
## Step 8/8. Set up systemd
<Notice type="tip">
This step is only applicable if you are running the Teleport Jira plugin on a
Linux machine.
</Notice>
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:
```txt
(!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.
Save this as `teleport-jira.service` or another [unit file load
path](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20File%20Load%20Path)
supported by systemd.
## 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](../../reference/helm-reference/teleport-plugin-jira.mdx).
```code
$ sudo systemctl enable teleport-jira
$ sudo systemctl start teleport-jira
```
examples/resources/plugins/teleport-jira-cloud.toml
+13 -10
View File
@@ -1,20 +1,23 @@
# example jira plugin configuration TOML file
# 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
# Proxy Service domain and HTTPS port
auth_server = "myinstance.teleport.sh:443"
# Teleport identity file location
identity = "/var/lib/teleport/plugins/jira/auth.pem"
[jira]
url = "https://example.com/jira" # JIRA URL. For JIRA Cloud, https://[my-jira].atlassian.net
username = "bot@example.com" # JIRA username
api_token = "token" # JIRA API Basic Auth token
project = "MYPROJ" # JIRA Project key
url = "https://[my-jira].atlassian.net" # JIRA URL
username = "bot@example.com" # JIRA username
api_token = "token" # JIRA API token
project = "TAR" # 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
# URL on which webhook server is accessible externally, for example,
# [https://]teleport-jira.example.com
public_addr = "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".
severity = "INFO" # Logger severity. Could be "INFO", "ERROR", "DEBUG" or "WARN".
examples/resources/plugins/teleport-jira-helm-cloud.yaml
+15 -11
View File
@@ -1,21 +1,25 @@
teleport:
# Teleport HTTPS Proxy web address, for Teleport Enterprise Cloud should be in the form "your-account.teleport.sh:443"
# Teleport Proxy Service domain name and HTTPS port. If you are using Teleport
# Enterprise Cloud, this should be in the form "your-account.teleport.sh:443"
address: "teleport.example.com:443"
# Secret containing identity
identitySecretName: teleport-plugin-jira-identity
# Secret containing a Teleport identity document
identityFromSecret: teleport-plugin-jira-identity
jira:
url: https://jira.example.com/ # URL of the Jira instance
username: bot@example.com # Email of the bot user
apiToken: token # Token of the bot user
project: MYPROJ # Project where issues will be created
url: "https://[my-jira].atlassian.net" # URL of the Jira instance
username: bot@example.com # Email of the bot user
apiToken: token # Token of the bot user
project: TAR # 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
publicAddress: https://jira-teleport.example.com/
# Secret containing the TLS certificate
tlsFromSecret: teleport-plugin-jira-tls
# 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".
serviceType: ClusterIP