diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx index bdc2bb9820a69..7b5d3ac673181 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-discord.mdx @@ -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 diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx index 6ee27df906c2f..ffed4cc27d172 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-email.mdx @@ -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 diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx index 5aca6e6fa685b..134a4c2f3baea 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-jira.mdx @@ -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. diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx index eaccf38559df0..d4f4383ac3922 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-mattermost.mdx @@ -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 diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx index 89612df5a5e3c..8f4be8308eb0b 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-msteams.mdx @@ -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 diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx index 9900ceeadfed5..79cb9e713c177 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-pagerduty.mdx @@ -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 diff --git a/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx b/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx index dfb84503c6cbc..d21b116113536 100644 --- a/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx +++ b/docs/pages/access-controls/access-request-plugins/ssh-approval-slack.mdx @@ -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 diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx index 52d97461d5759..5d85d9d68bfd1 100644 --- a/docs/pages/access-controls/guides/dual-authz.mdx +++ b/docs/pages/access-controls/guides/dual-authz.mdx @@ -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. diff --git a/docs/pages/includes/plugins/identity-export.mdx b/docs/pages/includes/plugins/identity-export.mdx index 1024b9ae160d5..350ab8b7d775d 100644 --- a/docs/pages/includes/plugins/identity-export.mdx +++ b/docs/pages/includes/plugins/identity-export.mdx @@ -1,23 +1,22 @@ -Like all Teleport users, `access-plugin` needs signed credentials in +Like all Teleport users, `{{ user }}` needs signed credentials in 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. diff --git a/docs/pages/management/export-audit-events/datadog.mdx b/docs/pages/management/export-audit-events/datadog.mdx index 364ebd6049886..589c7e857242b 100644 --- a/docs/pages/management/export-audit-events/datadog.mdx +++ b/docs/pages/management/export-audit-events/datadog.mdx @@ -158,29 +158,15 @@ command. -```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"!) -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 @@ -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 diff --git a/docs/pages/management/export-audit-events/elastic-stack.mdx b/docs/pages/management/export-audit-events/elastic-stack.mdx index 67bdd8ebfda4b..822e009bbf350 100644 --- a/docs/pages/management/export-audit-events/elastic-stack.mdx +++ b/docs/pages/management/export-audit-events/elastic-stack.mdx @@ -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" --- @@ -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. - - - -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. - - - - -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. - - - - -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. - - - - - - - - -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. - - - - - - 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. - - +(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler"!) ## Step 2/4. Configure a Logstash pipeline @@ -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`. - - - -Assign `teleport.identity` to a path to the identity file you exported earlier, -e.g., `/home/auth.pem`. - - - - -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. - - - +(!docs/pages/includes/plugins/config-toml-teleport.mdx!) ### Start the Event Handler diff --git a/docs/pages/management/export-audit-events/splunk.mdx b/docs/pages/management/export-audit-events/splunk.mdx index 09a08ffb0b41a..d2c4feb382a91 100644 --- a/docs/pages/management/export-audit-events/splunk.mdx +++ b/docs/pages/management/export-audit-events/splunk.mdx @@ -141,89 +141,9 @@ $ tctl create -f teleport-event-handler-impersonator.yaml Log out of your Teleport cluster and log in again to assume the new role. -### Export the access plugin identity +### Export the 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. - - - -The format of the credentials depends on whether you have set up your Teleport -cluster so clients and services connect to the Teleport Proxy Service or to the -Teleport Auth Service instead. - - - - -The following `tctl auth sign` command impersonates the `teleport-event-handler` -user, generates signed credentials, and writes an identity file to the local -directory. It uses the `--ttl` flag to request a certificate with a lifetime of -10 days: - -```code -$ tctl auth sign --user=teleport-event-handler --out=auth.pem --ttl=240h -``` - -The Event Handler plugin listens for audit logs 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. - - - - -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, which uses the -`--ttl` flag to request a certificate with a lifetime of 10 days: - -```code -$ tctl auth sign --format=tls --user=teleport-event-handler --out=auth --ttl=240h -``` - -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. - - - - - - - - -The following `tctl auth sign` command impersonates the `teleport-event-handler` -user, generates signed credentials, and writes an identity file to the local -directory. It uses the `--ttl` flag to request a certificate with a lifetime of -10 days: - -```code -$ tctl auth sign --user=teleport-event-handler --out=auth.pem --ttl=240h -``` - -Teleport's Event Handler plugin listens for new and updated audit logs 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. - - +(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler"!) Move the credentials you generated to the host where you are running the Teleport Event Handler plugin. @@ -498,38 +418,16 @@ Adding the `noop` query parameter causes the Teleport Event Handler to append the routing information as the parameter's value so the Universal Forwarder can discard it. -Change `teleport.addr` to the host and port of your Teleport Proxy Service, or -the Auth Service if you have configured the Teleport Event Handler to connect to -it directly, e.g., `mytenant.teleport.sh:443`. - - - +Next, edit the `teleport` section of the configuration as follows: -Assign `teleport.identity` to a path to the identity file you exported earlier, -e.g., `/home/auth.pem`. +(!docs/pages/includes/plugins/config-toml-teleport.mdx!) -Ensure that the Teleport Event Handler can read these credentials: +Ensure that the Teleport Event Handler can read the identity file: ```code $ chmod +r auth.pem ``` - - - -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. - -Ensure that the Teleport Event Handler can read these credentials: - -```code -$ chmod +r auth.cas auth.crt auth.key -``` - - - - ### Start the Teleport Event Handler Start the Teleport Teleport Event Handler as a daemon. To do so, create a @@ -622,7 +520,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