Skip to content

Commit

Permalink
Backport #23405 to branch/v11 (#23884)
Browse files Browse the repository at this point in the history 
* Edit cluster joining info in Access Request docs

See #21305

Edit Access Request plugin guides to remove the options to connect to
the Auth Service directly. This simplifies the guides and helps us
standardize the docs around connecting services via the Proxy Service.

Also make the Jira guide more consistent with other Access Request
plugin guides (this is not an attempt to refresh the guide, which is
still out of date, but will help us refresh the guide when the time
comes).

* Fix linter issues

* Respond to PR feedback
  • Loading branch information
@ptgott
ptgott authored Mar 31, 2023
1 parent 8bc2fb8 commit 218eea6
Show file tree
Hide file tree
Showing 17 changed files with 68 additions and 669 deletions.
60 changes: 1 addition & 59 deletions docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -191,65 +191,7 @@ Open the configuration file created for the Teleport Discord plugin and update t

The Discord plugin uses this section to connect to the Teleport Auth Service.

<ScopedBlock scope={["oss", "enterprise"]}>

The address and credentials you configure depend on whether your plugin can
access the Auth Service directly:

<Tabs dropdownCaption="Environment type" dropdownSelected="Executable">
<TabItem label="Connect to the Auth Service" scope={["oss", "enterprise"]} options="Executable">

Set `addr` to the address and port of your Auth Service. This address must be
reachable from the Teleport Discord Plugin.

Set `client_key`, `client_crt`, and `root_cas` to the identity files
generated earlier:

```toml
[teleport]
addr = "localhost:3025"
client_key = "/var/lib/teleport/plugins/discord/auth.key" # Teleport GRPC client secret key
client_crt = "/var/lib/teleport/plugins/discord/auth.crt" # Teleport GRPC client certificate
root_cas = "/var/lib/teleport/plugins/discord/auth.cas" # Teleport cluster CA certs
```
</TabItem>
<TabItem label="Connect to the Proxy Service" options="Executable">

Set `addr` to your Proxy Service address with port `443`.

Set `identity` to the identity file generated earlier:

```toml
[teleport]
addr = "teleport.example.com:443"
identity = "/var/lib/teleport/plugins/discord/auth.pem"
```
</TabItem>
<TabItem label="Connect to the Proxy or Auth Service" scope="cloud" options="Helm Chart">

**`address`**: Include the hostname and port of your Teleport Proxy or Auth Service
(e.g., `teleport.example.com:443`).

**`identitySecretName`**: Fill in the `identitySecretName` field with the name
of the Kubernetes secret you created earlier.

</TabItem>
</Tabs>

</ScopedBlock>
<ScopedBlock scope="cloud">

Set `addr` to your Teleport Proxy address with port `443`.

Set `identity` to the identity file generated earlier:

```toml
[teleport]
addr = "teleport.example.com:443"
identity = "/var/lib/teleport/plugins/discord/auth.pem"
```

</ScopedBlock>
(!docs/pages/includes/plugins/config-toml-teleport.mdx!)

**`[discord]`**

Expand Down
34 changes: 2 additions & 32 deletions docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,37 +125,7 @@ each value below.

### `[teleport]`

<Tabs>
<TabItem label="Teleport Enterprise" scope={["oss", "enterprise"]}>

**`addr`**: Include the hostname and HTTPS port of your Teleport Proxy Service
(e.g., `mytenant.teleport.sh:443`). If you are configuring your plugin to
connect directly to the Teleport Auth Service, use your Auth Service's gRPC
endpoint (e.g., `teleport.example.com:3025`).

**`identity`**, **`client_key`**, **`client_crt`**, **`root_cas`**: The values
you will use for these fields depend on whether the email plugin will
connect to the Proxy Service or the Auth Service.

If you exported an identity file earlier, fill in the `identity` field with the
path to the file and comment out the other fields.

If you exported a client key, client certificate, and root CAs earlier, fill in
the `client_key`, `client_crt`, and `root_cas` fields with the paths to these
files and leave `identity` commented out.

</TabItem>
<TabItem label="Teleport Cloud" scope="cloud">

**`addr`**: Include the hostname and HTTPS port of your Teleport Cloud tenant
(e.g., `mytenant.teleport.sh:443`).

**`identity`**, **`client_key`**, **`client_crt`**, **`root_cas`**: Fill in the
`identity` field with the path to the identity file you exported earlier and
comment out the other fields.

</TabItem>
</Tabs>
(!docs/pages/includes/plugins/config-toml-teleport.mdx!)

### `[mailgun]` or `[smtp]`

Expand Down Expand Up @@ -276,7 +246,7 @@ You configuration should resemble the following:
```toml
# /etc/teleport-email.toml
[teleport]
addr = "example.com:3025"
addr = "example.com:443"
identity = "/var/lib/teleport/plugins/email/auth_id"

[mailgun]
Expand Down
89 changes: 21 additions & 68 deletions docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,40 @@
---
title: SSH login approval using Jira and Teleport
description: How to configure SSH login approval using Jira and Teleport
h1: SSH login approvals using Jira
title: Access Requests using Jira and Teleport
description: How to configure Access Request approval using Jira and Teleport
---

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
## Prerequisites

This guide assumes that you have:
(!docs/pages/includes/commercial-prereqs-tabs.mdx!)

- 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/tctl.mdx!)


### Create a user and role for access
## Step 1/6. Create a user and role for access

(!docs/pages/includes/plugins/rbac-update.mdx!)

### Export the access-plugin certificate
## Step 2/6. Export the access-plugin certificate

(!docs/pages/includes/plugins/identity-export.mdx!)

We'll reference these files later when [configuring the plugins](#configuration-file).
We'll reference these files later when configuring the plugin.

## Setting up your Jira project
## Step 3/6. Set up your Jira project

### Creating the permission management 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.

### Setting up the status board
### 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:

Expand All @@ -48,13 +44,13 @@ Create a new board for tasks in the permission management project. The board has

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

### Setting up Jira webhooks
### Set up Jira webhooks

Go to Settings → General → System → Webhooks and create a new webhook for Jira to tell the Teleport plugin about updates.

Expand All @@ -73,7 +69,7 @@ The webhook needs to be notified only about new issues being created, issues bei

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
## Step 4/6. Install the plugin

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
Expand Down Expand Up @@ -109,16 +105,15 @@ Run `./install` from `teleport-jira` or place the executable in `/usr/bin` or `/
</TabItem>
</Tabs>

## Configuration file
## Step 5/6. Configure the plugin

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:

<Tabs dropdownCaption="Environment type" dropDownSelected="Executable">
<Tabs>
<TabItem
label="Connect to the Proxy Service"
options="Executable"
label="Executable"
>

The Teleport Jira plugin uses a config file in TOML format. Generate a
Expand All @@ -140,31 +135,7 @@ The configuration file will resemble the following:
```
</TabItem>
<TabItem
label="Connect to the Auth Service"
options="Executable"
>

The Teleport Jira plugin uses a config file in TOML format. Generate a
boilerplate config by running the following command:

```code
$ 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:

```toml
(!examples/resources/plugins/teleport-jira-self-hosted.toml!)
```
</TabItem>
<TabItem
options="Helm Chart"
label="Connect to the Proxy Service "
label="Helm Chart"
>

Create a file called `values.yaml` with the following content, which configures
Expand All @@ -177,32 +148,14 @@ the Helm chart for the plugin. It should resemble the following:
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>
<TabItem
options="Helm Chart"
label="Connect to the Auth Service "
>

Create a file called `values.yaml` with the following content, which configures
the Helm chart for the plugin. It should resemble the following:

```yaml
(!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:

```console
kubectl create secret generic teleport-plugin-jira-identity --from-file=auth_id=auth.pem
```
</TabItem>
</Tabs>

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 `[teleport]` sections includes configuration options for connecting the Jira
plugin to Teleport.

The `[jira]` section requires a few things:

Expand All @@ -216,7 +169,7 @@ The `[http]` setting block describes how the plugin's HTTP server works. The HTT
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
## Step 6/6. Test the plugin

You should be able to run the Teleport plugin now!

Expand Down
Loading

0 comments on commit 218eea6

Please sign in to comment.