Skip to content

Commit

Permalink
Add plugin setup instructions for cloud users (#11006)
Browse files Browse the repository at this point in the history 
Backports #9470

* Add plugin setup instructions for cloud users

- Turn the identity file export and RBAC instructions into
includes, since these instructions are the same for each
plugin.

- Change the tab set re: an impersonation role to a detail box
scoped to cloud users.

- Add separate example config files for cloud and self-hosted
deployments of each plugin.

- Misc. changes for clarity

Fixes #8936

* Respond to PR feedback

Also make minor stylistic tweaks

* Respond to PR feedback with stylistic tweaks
  • Loading branch information
@ptgott
ptgott authored Mar 22, 2022
1 parent 30a518b commit 2885563
Show file tree
Hide file tree
Showing 16 changed files with 364 additions and 490 deletions.
93 changes: 29 additions & 64 deletions docs/pages/access-controls/guides/dual-authz.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ description: Dual Authorization for SSH and Kubernetes.
videoBanner: b_iqJm_o15I
---

# Dual Authorization

You can set up Teleport to require require the approval of multiple team members to perform some critical actions.
Here are the most common scenarios:

Expand Down Expand Up @@ -41,84 +39,42 @@ two team members for a privileged role `dbadmin`.
```code
$ docker run --name mattermost-preview -d --publish 8065:8065 --add-host dockerhost:127.0.0.1 mattermost/mattermost-preview
```

</Admonition>

(!docs/pages/includes/tctl.mdx!)

## Set up Teleport bot

<Tabs>
<TabItem label="Mattermost">

Enable bot account creation in "System Console -> Integrations".

Toggle `Enable Bot Account Creation`.
### Create a bot within Mattermost

![Enable bots](../../../img/access-controls/dual-authz/mattermost-0-enable.png)
Enable bot account creation in "System Console -> Integrations".

Go back to your team settings, navigate to "Integrations -> Bot Accounts". Press "Add Bot Account".
Toggle `Enable Bot Account Creation`.

![Enable bots](../../../img/access-controls/dual-authz/mattermost-1-bot.png)
![Enable bots](../../../img/access-controls/dual-authz/mattermost-0-enable.png)

Add the "Post All" permission on the new account.
Go back to your team settings, navigate to "Integrations -> Bot Accounts". Press "Add Bot Account".

![Enable bots](../../../img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png)

Create the bot and save the access token.

</TabItem>
</Tabs>
![Enable bots](../../../img/access-controls/dual-authz/mattermost-1-bot.png)

Create a non-interactive bot `access-plugin` user and role.

```yaml
kind: user
metadata:
name: access-plugin
spec:
roles: ['access-plugin']
version: v2
---
kind: role
version: v4
metadata:
name: access-plugin
spec:
allow:
rules:
- resources: ['access_request']
verbs: ['list', 'read']
- resources: ['access_plugin_data']
verbs: ['update']
# teleport currently refuses to issue certs for a user with 0 logins,
# this restriction may be lifted in future versions.
logins: ['access-plugin-not-used']
```
Add the "Post All" permission on the new account.

<Admonition
type="note"
title="Creating resources"
>
Here and below follow along and create yaml resources using `tctl create -f`:
![Enable bots](../../../img/access-controls/dual-authz/mattermost-2-all-permissions@2x.png)

```code
$ tctl create -f access.yaml
```
</Admonition>
Create the bot and save the access token.

### Set up RBAC for the plugin

**Export access-plugin cert**
(!docs/pages/includes/plugins/rbac.mdx!)

Teleport Plugin uses the `access-plugin` role and user to perform the approval.
We export the identify files, using `tctl auth sign`.
### Export the access-plugin identity files

```code
$ tctl auth sign --format=tls --user=access-plugin --out=auth --ttl=720h
```
(!docs/pages/includes/plugins/identity-export.mdx!)

Teleport will generate `auth.crt`, `auth.key`, and `auth.cas` - a certificate, a private key, and a set of CA certs respectively.
We'll reference the exported file(s) later when configuring the plugin.

**Install the plugin**
### Install the plugin

<Tabs>
<TabItem label="Download">
Expand Down Expand Up @@ -146,11 +102,20 @@ Teleport will generate `auth.crt`, `auth.key`, and `auth.cas` - a certificate, a
$ teleport-mattermost configure > /etc/teleport-mattermost.toml
```

Update the config with Teleport address, Mattermost URL, and a bot token.
Update the config with the Teleport address, Mattermost URL, and a bot token.

```toml
(!examples/resources/plugins/teleport-mattermost.toml!)
<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
```yaml
(!examples/resources/plugins/teleport-mattermost-self.toml!)
```
</TabItem>
<TabItem scope={["cloud"]} label="Cloud">
```yaml
(!examples/resources/plugins/teleport-mattermost-cloud.toml!)
```
</TabItem>
</Tabs>

## Dual authorization

Expand Down Expand Up @@ -252,7 +217,7 @@ Bob can also assume granted access request roles using Web UI:

## Troubleshooting

**Cert errors**
### Cert errors in self-hosted deployments

You may be getting certificate errors if Teleport's auth server is missing an address in the server certificate:

Expand Down
4 changes: 2 additions & 2 deletions docs/pages/database-access/guides/cockroachdb-self-hosted.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ This guide will help you to:

(!docs/pages/includes/database-access/token.mdx!)
<Tabs>
<TabItem label="Self Hosted" scope={["enterprise","oss"]}>
<TabItem label="Self-Hosted" scope={["enterprise","oss"]}>
Start the Teleport Database Service, pointing the `--auth-server` flag to the address of your Teleport Proxy Service:

```code
Expand Down Expand Up @@ -142,7 +142,7 @@ Log into your Teleport cluster. Your CockroachDB cluster should appear in the
list of available databases:

<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self Hosted">
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">
```code
$ tsh login --proxy=teleport.example.com --user=alice
$ tsh db ls
Expand Down
6 changes: 3 additions & 3 deletions docs/pages/database-access/guides/mongodb-atlas.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ In this guide you will:
(!docs/pages/includes/database-access/token.mdx!)

<Tabs>
<TabItem label="Self Hosted" scope={["enterprise","oss"]}>
<TabItem label="Self-Hosted" scope={["enterprise","oss"]}>
Start the Teleport Database Service, pointing the `--auth-server` flag at the address of your Teleport Proxy Service:

```code
Expand Down Expand Up @@ -74,7 +74,7 @@ If you're starting the Database Agent with a YAML configuration instead of CLI f
the following config is equivalent to the `teleport db start` command shown earlier:

<Tabs>
<TabItem label="Self Hosted" scope={["enterprise","oss"]}>
<TabItem label="Self-Hosted" scope={["enterprise","oss"]}>
```yaml
teleport:
auth_token: "/tmp/token"
Expand Down Expand Up @@ -193,7 +193,7 @@ certificate with `CN=alice` subject.
Log into your Teleport cluster and see available databases:

<Tabs>
<TabItem scope={["enterprise", "oss"]} label="Self Hosted">
<TabItem scope={["enterprise", "oss"]} label="Self-Hosted">

```code
$ tsh login --proxy=teleport.example.com --user=alice
Expand Down
115 changes: 40 additions & 75 deletions docs/pages/enterprise/workflow/ssh-approval-jira-cloud.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,7 @@ description: How to configure SSH login approval using Jira and Teleport
h1: SSH login approvals using Jira
---

## 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.
This guide will talk through how to setup Teleport with Jira. Teleport's Jira integration allows you to treat Teleport access and permission requests using Jira tickets.

## Setup

Expand All @@ -16,62 +14,20 @@ This guide assumes that you have:
- 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
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.

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
### Create a 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.
(!docs/pages/includes/plugins/rbac.mdx!)

```bash
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 the access-plugin certificate

#### Export access-plugin Certificate
(!docs/pages/includes/plugins/identity-export.mdx!)

Teleport Plugin use the `access-plugin-jira` role and user to perform the approval. We export the identity files, using [`tctl auth sign`](../../setup/reference/cli.mdx#tctl-auth-sign).
We'll reference these files later when [configuring the plugins](#configuration-file).

```bash
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](#configuration-file).

<Admonition
type="note"
title="Certificate Lifetime"
>
By default, [`tctl auth sign`](../../setup/reference/cli.mdx#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
</Admonition>

## Setting up your Jira Project
## Setting up your Jira project

### Creating the permission management project

Expand All @@ -87,11 +43,11 @@ Create a new board for tasks in the permission management project. The board has
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.
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.

### Setting up Request ID field on Jira
### Setting up a request ID field on Jira

Teleport Jira Plugin requires a custom issue field to be created.
The 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`.

Expand All @@ -103,30 +59,30 @@ If you're using Jira Cloud, navigate to [Account Settings → Security → API T

For Jira Server, the URL of the API tokens page will be different depending on your installation.

### Setting up Jira Webhooks
### Setting up Jira webhooks

Go to Settings → General → System → Webhooks and create a new Webhook for Jira to tell the Teleport Plugin about updates.
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.
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 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.
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 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.
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.
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, the plugin will just ignore everything else.
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

We recommend installing the Teleport Plugins alongside the Teleport Proxy. This is an ideal
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 access. We currently only provide linux-amd64 binaries, you can also
and Teleport Auth access. We currently only provide linux-amd64 binaries, you can also
compile these plugins from [source](https://github.com/gravitational/teleport-plugins/tree/master/access/jira).

```code
Expand All @@ -142,19 +98,28 @@ Run `./install` in from 'teleport-jira' or place the executable in the appropria

### Configuration file

Teleport Jira Plugin uses a config file in TOML format. Generate a boilerplate config by
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, Jira Teleport Plugin will use a config in `/etc/teleport-jira.toml`, and you can override it with `-c config/file/path.toml` flag.
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.

<Tabs>
<TabItem label="Self-Hosted" scopes={["oss", "enterprise"]}>
```toml
(!examples/resources/plugins/teleport-jira-self-hosted.toml!)
```
</TabItem>
<TabItem label="Cloud" scopes={["cloud"]}>
```toml
(!examples/resources/plugins/teleport-jira.toml!)
(!examples/resources/plugins/teleport-jira-cloud.toml!)
```
</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.

Expand All @@ -165,10 +130,10 @@ The `[jira]` section requires a few things:
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.
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
setup on the same server as the Teleport Proxy, so you can use the same TLS certificate.
run the Jira plugin on the same server as the Teleport Proxy, so you can use the same TLS certificate.

## Testing

Expand All @@ -186,20 +151,20 @@ 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.
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
### Set up 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:
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`.
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.

## Audit Log
## 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.
Expand Down
Loading

0 comments on commit 2885563

Please sign in to comment.