Skip to content

Recommend Proxy Service in event-handler guides #23879

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ptgott merged 1 commit into from
Mar 31, 2023
Merged

Recommend Proxy Service in event-handler guides #23879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ and will require access to both the public internet and the Teleport Auth Servic

## Step 4/8. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

The rest of this guide assumes that you have placed any files generated by this
command into `/var/lib/teleport/plugins/discord` for later reference when
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ $ teleport-email version

## Step 4/7. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

## Step 5/7. Configure the plugin

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Jira tickets.

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

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

We'll reference these files later when configuring the plugin.

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ Run `./install` from `teleport-mattermost` or place the executable in the approp

## Step 4/8. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

## Step 5/8. Register a Mattermost bot

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ and will require access to both the public internet and the Teleport Auth Servic

## Step 4/9. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

The rest of this guide assumes that you have placed any files generated by this
command into `/var/lib/teleport/plugins/msteams` for later reference when
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,7 +413,7 @@ Run `./install` from `teleport-pagerduty`.

## Step 4/8. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

## Step 5/8. Set up a PagerDuty API key

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ and will require access to both the public internet and the Teleport Auth Servic

## Step 4/8. Export the access plugin identity

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

The rest of this guide assumes that you have placed any files generated by this
command into `/var/lib/teleport/plugins/slack` for later reference when
Expand Down
2 changes: 1 addition & 1 deletion docs/pages/access-controls/guides/dual-authz.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Create the bot and save the access token.

### Export the access-plugin identity files

(!docs/pages/includes/plugins/identity-export.mdx!)
(!docs/pages/includes/plugins/identity-export.mdx user="access-plugin"!)

We'll reference the exported file(s) later when configuring the plugin.

Expand Down
19 changes: 9 additions & 10 deletions docs/pages/includes/plugins/identity-export.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,22 @@
Like all Teleport users, `access-plugin` needs signed credentials in
Like all Teleport users, `{{ user }}` needs signed credentials in
Copy link
Copy Markdown
Collaborator

@zmb3 zmb3 Mar 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this some new templating language, or will this literally show {{ user }} in the docs?

Copy link
Copy Markdown
Contributor

@alexfornuto alexfornuto Mar 31, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's how we add variables when calling partials. See the add-role-to-user partial for an existing example.

order to connect to your Teleport cluster. You will use the `tctl auth sign`
command to request these credentials for your plugin.

The following `tctl auth sign` command impersonates the `access-plugin` user,
The following `tctl auth sign` command impersonates the `{{ user }}` user,
generates signed credentials, and writes an identity file to the local
directory:

```code
$ tctl auth sign --user=access-plugin --out=auth.pem
$ tctl auth sign --user={{ user }} --out=auth.pem
```

Teleport's Access Request plugins listen for new and updated Access Requests by
connecting to the Teleport Auth Service's gRPC endpoint over TLS.
The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS.

The identity file, `auth.pem`, includes both TLS and SSH credentials. Your
Access Request plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.
The identity file, `auth.pem`, includes both TLS and SSH credentials. The plugin
uses the SSH credentials to connect to the Proxy Service, which establishes a
reverse tunnel connection to the Auth Service. The plugin uses this reverse
tunnel, along with your TLS credentials, to connect to the Auth Service's gRPC
endpoint.

You will refer to this file later when configuring the plugin.

Expand Down
22 changes: 4 additions & 18 deletions docs/pages/management/export-audit-events/datadog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,29 +158,15 @@ command.

<Tabs>
<TabItem label="Executable" scope={["oss","enterprise"]}>
```code
$ tctl auth sign --user=teleport-event-handler --out=identity
```

This command creates one PEM-encoded file, `identity`. The identity file
includes both TLS and SSH credentials. The Event Handler plugin uses the SSH
credentials to connect to the Proxy Service, which establishes a reverse tunnel
connection to the Auth Service. The plugin uses this reverse tunnel, along with
your TLS credentials, to connect to the Auth Service's gRPC endpoint.
(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler"!)

</TabItem>
<TabItem label="Helm Chart" scope={["cloud"]}>

If you are planning to use the Helm Chart, you'll need to generate the keys
with the `file` format, then create a secret in Kubernetes.

Create the identity using the following command:

```code
$ tctl auth sign --format=file --user=teleport-event-handler --out=identity
```
(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler"!)

Then create the Kubernetes secret:
Next, create a Kubernetes secret for the Teleport identity file:

```code
$ kubectl create secret generic teleport-event-handler-identity --from-file=auth_id=identity
Expand Down Expand Up @@ -390,7 +376,7 @@ Teleport Cluster, ensure that:
`--ttl` flag in the `tctl auth sign` command, which is 12 hours by default.
- Ensure that in your Teleport Event Handler configuration file
(`teleport-event-handler.toml`), you have provided the correct host *and* port
for the Teleport Proxy Service or Auth Service.
for the Teleport Proxy Service.

## Next steps

Expand Down
108 changes: 3 additions & 105 deletions docs/pages/management/export-audit-events/elastic-stack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "Export Teleport Audit Events with to Elastic Stack"
title: "Export Teleport Audit Events to the Elastic Stack"
description: "How to configure Teleport's Event Handler plugin to send audit events to the Elastic Stack"
---

Expand Down Expand Up @@ -144,95 +144,7 @@ $ tctl create teleport-event-handler-impersonator.yaml

### Export the access plugin identity

Like all Teleport users, `teleport-event-handler` needs signed credentials in
order to connect to your Teleport cluster. You will use the `tctl auth sign`
command to request these credentials for the plugin.

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

The format of the credentials depends on whether you have set up your network to
give the plugin direct access to the Teleport Auth Service, or if all Teleport
clients and services connect to the Teleport Proxy Service instead.

<Tabs>
<TabItem label="Connect to the Proxy Service">

The following `tctl auth sign` command impersonates the `teleport-event-handler`
user, generates signed credentials, and writes an identity file to the local
directory:

```code
$ tctl auth sign --user=teleport-event-handler --out=auth.pem
```

The Event Handler plugin listens for audit events by connecting to the Teleport
Auth Service's gRPC endpoint over TLS.

The identity file, `auth.pem`, includes both TLS and SSH credentials. Your
Event Handler plugin uses the SSH credentials to connect to the Proxy Service,
which establishes a reverse tunnel connection to the Auth Service. The plugin
uses this reverse tunnel, along with your TLS credentials, to connect to the
Auth Service's gRPC endpoint.

You will refer to this file later when configuring the plugin.

</TabItem>
<TabItem label="Connect to the Auth Service">

If your network allows your plugin to access the Auth Service directly, e.g.,
you are running the plugin on the Auth Service host, the plugin uses TLS
credentials to connect to the Auth Service's gRPC endpoint and listen for audit
events.

You can generate TLS credentials with the following command:

```code
$ tctl auth sign --format=tls --user=teleport-event-handler --out=auth
```

This command should result in three PEM-encoded files: `auth.crt`,
`auth.key`, and `auth.cas` (certificate, private key, and CA certs
respectively). Later, you will configure the plugin to use these credentials to
connect to the Auth Service.

</TabItem>
</Tabs>

</ScopedBlock>

<ScopedBlock scope="cloud">

The following `tctl auth sign` command impersonates the `teleport-event-handler`
user, generates signed credentials, and writes an identity file to the local
directory:

```code
$ tctl auth sign --user=teleport-event-handler --out=auth.pem
```

Teleport's Event Handler plugin listens for new and updated audit events by
connecting to the Teleport Auth Service's gRPC endpoint over TLS.

The identity file, `auth.pem`, includes both TLS and SSH credentials. The Event
Handler plugin uses the SSH credentials to connect to the Proxy Service, which
establishes a reverse tunnel connection to the Auth Service. The plugin uses
this reverse tunnel, along with your TLS credentials, to connect to the Auth
Service's gRPC endpoint.

You will refer to this file later when configuring the plugin.

</ScopedBlock>

<Admonition
title="Certificate Lifetime"
>

By default, `tctl auth sign` produces certificates with a relatively short
lifetime. For production deployments, you can use the `--ttl` flag to ensure a
more practical certificate lifetime, e.g., `--ttl=8760h` to export a one-year
certificate.

</Admonition>
(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler"!)

## Step 2/4. Configure a Logstash pipeline

Expand Down Expand Up @@ -557,21 +469,7 @@ Change `teleport.addr` to the host and port of your Teleport Proxy Service, or
the Auth Service if you have configured the Event Handler to connect to it
directly, e.g., `mytenant.teleport.sh:443`.

<Tabs>
<TabItem label="Connect to the Proxy Service">

Assign `teleport.identity` to a path to the identity file you exported earlier,
e.g., `/home/auth.pem`.

</TabItem>
<TabItem label="Connect to the Auth Service">

Assign `teleport.ca`, `teleport.cert`, and `teleport.key` to the paths of the
TLS credentials you generated earlier. Respectively, these are the certificate
authority, certificate, and private key.

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

### Start the Event Handler

Expand Down
Loading