# Set up the Teleport Event Handler Plugin In this guide, we will set up the Teleport Event Handler plugin with credentials to authenticate to the Teleport Auth Service and access the events API. ## How it works The Event Handler plugin is a binary that runs independently of your Teleport cluster. It authenticates to your Teleport cluster using mutual TLS to begin forwarding events. ## Prerequisites - A running Teleport cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/get-started/deploy-community.md). - The `tctl` and `tsh` clients. Installing `tctl` and `tsh` clients 1. Determine the version of your Teleport cluster. The `tctl` and `tsh` clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at `/v1/webapi/find` and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service: ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** Download the signed macOS .pkg installer for Teleport, which includes the `tctl` and `tsh` clients: ``` $ curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg ``` In Finder double-click the `pkg` file to begin installation. --- DANGER Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` **Recommended:** Configure Machine & Workload Identity to provide short-lived Teleport credentials to the plugin. Before following this guide, follow a Machine & Workload Identity [deployment guide](https://goteleport.com/docs/machine-workload-identity/deployment.md) to run the `tbot` binary on your infrastructure. - A server, virtual machine, Kubernetes cluster, or Docker environment to run the Teleport Event Handler plugin. - To check that you can connect to your Teleport cluster, sign in with `tsh login`, then verify that you can run `tctl` commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. - On your workstation, create a folder called `event-handler`, to hold configuration files and plugin state: ``` $ mkdir -p event-handler $ cd event-handler ``` ## Step 1/2. Install the Event Handler plugin **Linux** The Event Handler plugin is provided in `amd64` and `arm64` binaries for downloading. Replace `ARCH` with your required version. ``` $ curl -L -O https://cdn.teleport.dev/teleport-event-handler-v19.0.0-dev-linux-ARCH-bin.tar.gz $ tar -zxvf teleport-event-handler-v19.0.0-dev-linux-ARCH-bin.tar.gz $ sudo ./teleport-event-handler/install ``` **macOS** The Event Handler plugin is provided in `amd64` and `arm64` binaries for downloading. Replace `ARCH` with your required version. ``` $ curl -L -O https://cdn.teleport.dev/teleport-event-handler-v19.0.0-dev-darwin-ARCH-bin.tar.gz $ tar -zxvf teleport-event-handler-v19.0.0-dev-darwin-ARCH-bin.tar.gz $ sudo ./teleport-event-handler/install ``` **Docker** Ensure that you have Docker installed and running. ``` $ docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:19.0.0-dev ``` **Helm** To allow Helm to install charts that are hosted in the Teleport Helm repository, use `helm repo add`: ``` $ helm repo add teleport https://charts.releases.teleport.dev ``` To update the cache of charts from the remote repository, run `helm repo update`: ``` $ helm repo update ``` **Build via Go** You will need Go >= 1.25.9 installed. Run the following commands: ``` $ git clone https://github.com/gravitational/teleport.git --depth 1 -b branch/v19 $ cd teleport/integrations/event-handler $ make build ``` The resulting executable will have the name `event-handler`. To follow the rest of this guide, rename this file to `teleport-event-handler` and move it to `/usr/local/bin`. ## Step 2/2. Set up the Event Handler plugin In this section, you will set up the Teleport Event Handler plugin and generate credentials that the plugin will use for authentication. ### Generate a starter config file Generate a configuration file with placeholder values for the Teleport Event Handler plugin. Later in this guide, we will edit the configuration file for your environment. **Cloud-Hosted** Run the `configure` command to generate a sample configuration. Assign teleport.example.com:443 to the DNS name and port of your Teleport Enterprise Cloud account. Assign localhost to the DNS name of your log forwarder. ``` $ teleport-event-handler configure . teleport.example.com:443 --dns-names=localhost ``` **Self-Hosted** Run the `configure` command to generate a sample configuration. Assign teleport.example.com:443 to the DNS name and port of your Teleport Auth Service or Proxy Service. Assign localhost to the DNS name of your log forwarder. ``` $ teleport-event-handler configure . teleport.example.com:443 --dns-names=localhost ``` **Helm Chart** Run the `configure` command to generate a sample configuration. Assign teleport.example.com:443 to the DNS name and port of your Teleport Auth Service or Proxy Service. Assign fluentd.fluentd.svc.cluster.local to the DNS name of your log forwarder. ``` $ docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:19.0.0-dev configure . teleport.example.com:443 --dns-names=fluentd.fluentd.svc.cluster.local ``` In order to export audit events, you'll need to have the root certificate and the client credentials available as a secret. Use the following command to create that secret in Kubernetes: ``` $ kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key ``` This will pack the content of `ca.crt`, `client.crt`, and `client.key` into the secret so the Helm chart can mount them to their appropriate path. **Local Docker test** Run the `configure` command to generate a sample configuration. Assign teleport.example.com:443 to the DNS name and port of your Teleport Auth Service or Proxy Service. Assign localhost to the DNS name of your log forwarder. ``` $ docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:19.0.0-dev configure . teleport.example.com:443 --dns-names=localhost ``` The plugin generates several setup files: | File(s) | Purpose | | ---------------------------------- | ------------------------------------------------------------------- | | `ca.crt` and `ca.key` | Self-signed CA certificate and private key for Fluentd | | `server.crt` and `server.key` | Fluentd server certificate and key | | `client.crt` and `client.key` | Fluentd client certificate and key, all signed by the generated CA | | `teleport-event-handler-role.yaml` | `user` and `role` resource definitions for Teleport's event handler | | `teleport-event-handler.toml` | Example event handler configuration | | `fluent.conf` | Fluentd plugin configuration | Running the Event Handler separately from the log forwarder This guide assumes that you are running the Event Handler on the same host or Kubernetes pod as your log forwarder. If you are not, you will need to instruct the Event Handler to generate mTLS certificates for subjects besides `localhost`. To do this, use the `--dns-names` flag of the `teleport-event-handler` configure command. For example, if your log forwarder is addressable at `fluentd.example.com`, you would run the following `configure` command: ``` $ teleport-event-handler configure --dns-names=fluentd.example.com ``` The `--dns-names` flag accepts a comma-separated list of DNS names. It will append subject alternative names (SANs) to the server certificate (the one you will provide to your log forwarder) for each DNS name in the list. If you have an existing Fluentd setup with TLS, issue a client certificate and key from the same certificate authority for the Teleport Event Handler to use. ### Define the Event Handler role The `teleport-event-handler configure` command generated a file called `teleport-event-handler-role.yaml`. This file defines a `teleport-event-handler` role and a user with read-only access to the `event` API: ``` kind: role metadata: name: teleport-event-handler spec: allow: rules: - resources: ['event', 'session'] verbs: ['list','read'] version: v5 --- kind: user metadata: name: teleport-event-handler spec: roles: ['teleport-event-handler'] version: v2 ``` Move this file to your workstation (or recreate it by pasting the snippet above) and use `tctl` on your workstation to create the role and the user: ``` $ tctl create -f teleport-event-handler-role.yaml user "teleport-event-handler" has been created role 'teleport-event-handler' has been created ``` --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- ### Enable issuing of credentials for the Event Handler role **Machine & Workload Identity** With the role created, you now need to allow the Machine & Workload Identity bot to produce credentials for this role. This can be done with `tctl`, replacing `my-bot` with the name of your bot: ``` $ tctl bots update my-bot --add-roles teleport-event-handler ``` **Long-lived identity files** In order for the Event Handler plugin to forward events from your Teleport cluster, it needs signed credentials from the cluster's certificate authority. The `teleport-event-handler` user cannot request this itself, and requires another user to **impersonate** this account in order to request credentials. Create a role that enables your user to impersonate the `teleport-event-handler` user. First, paste the following YAML document into a file called `teleport-event-handler-impersonator.yaml`: ``` kind: role version: v5 metadata: name: teleport-event-handler-impersonator spec: options: # max_session_ttl defines the TTL (time to live) of SSH certificates # issued to the users with this role. max_session_ttl: 10h # This section declares a list of resource/verb combinations that are # allowed for the users of this role. By default nothing is allowed. allow: impersonate: users: ["teleport-event-handler"] roles: ["teleport-event-handler"] ``` Next, create the role: ``` $ tctl create teleport-event-handler-impersonator.yaml ``` --- TIP You can also create and edit roles using the Web UI. Go to **Access -> Roles** and click **Create New Role** or pick an existing role to edit. --- Add this role to the user that generates signed credentials for the Event Handler: Assign the `teleport-event-handler-impersonator` role to your Teleport user by running the appropriate commands for your authentication provider: **Local User** 1. Retrieve your local user's roles as a comma-separated list: ``` $ ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")') ``` 2. Edit your local user to add the new role: ``` $ tctl users update $(tsh status -f json | jq -r '.active.username') \ --set-roles "${ROLES?},teleport-event-handler-impersonator" ``` 3. Sign out of the Teleport cluster and sign in again to assume the new role. **GitHub** 1. Open your `github` authentication connector in a text editor: ``` $ tctl edit github/github ``` 2. Edit the `github` connector, adding `teleport-event-handler-impersonator` to the `teams_to_roles` section. The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization. Here is an example: ``` teams_to_roles: - organization: octocats team: admins roles: - access + - teleport-event-handler-impersonator ``` 3. Apply your changes by saving and closing the file in your editor. 4. Sign out of the Teleport cluster and sign in again to assume the new role. **SAML** 1. Retrieve your `saml` configuration resource: ``` $ tctl get --with-secrets saml/mysaml > saml.yaml ``` Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `saml.yaml` file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource. 2. Edit `saml.yaml`, adding `teleport-event-handler-impersonator` to the `attributes_to_roles` section. The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization. Here is an example: ``` attributes_to_roles: - name: "groups" value: "my-group" roles: - access + - teleport-event-handler-impersonator ``` 3. Apply your changes: ``` $ tctl create -f saml.yaml ``` 4. Sign out of the Teleport cluster and sign in again to assume the new role. **OIDC** 1. Retrieve your `oidc` configuration resource: ``` $ tctl get oidc/myoidc --with-secrets > oidc.yaml ``` Note that the `--with-secrets` flag adds the value of `spec.signing_key_pair.private_key` to the `oidc.yaml` file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource. 2. Edit `oidc.yaml`, adding `teleport-event-handler-impersonator` to the `claims_to_roles` section. The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization. Here is an example: ``` claims_to_roles: - name: "groups" value: "my-group" roles: - access + - teleport-event-handler-impersonator ``` 3. Apply your changes: ``` $ tctl create -f oidc.yaml ``` 4. Sign out of the Teleport cluster and sign in again to assume the new role. ### Export an identity file for the Event Handler user 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 dangerous if exfiltrated, though in demo deployments, you can generate longer-lived identity files with `tctl`: **Machine & Workload Identity** Configure `tbot` with an output that will produce the credentials needed by the plugin. As the plugin will be accessing the Teleport API, the correct output type to use is `identity`. For this guide, the `directory` destination will be used. This will write these credentials to a specified directory on disk. Ensure that this directory can be written to by the Linux user that `tbot` runs as, and that it can be read by the Linux user that the plugin will run as. Modify your `tbot` configuration to add an `identity` output. If running `tbot` on a Linux server, use the `directory` output to write identity files to the `/opt/machine-id` directory: ``` services: - type: identity destination: type: directory # For this guide, /opt/machine-id is used as the destination directory. # You may wish to customize this. Multiple outputs cannot share the same # destination. path: /opt/machine-id ``` If running `tbot` on Kubernetes, write the identity file to Kubernetes secret instead: ``` services: - type: identity destination: type: kubernetes_secret name: teleport-event-handler-identity ``` If operating `tbot` as a background service, restart it. If running `tbot` in one-shot mode, execute it now. You should now see an `identity` file under `/opt/machine-id` or a Kubernetes secret named `teleport-event-handler-identity`. This contains the private key and signed certificates needed by the plugin to authenticate with the Teleport Auth Service. **Long-lived identity files** 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. The following `tctl auth sign` command impersonates the `teleport-event-handler` user, generates signed credentials, and writes an identity file to the local directory: ``` $ tctl auth sign --user=teleport-event-handler --out=identity ``` The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS. The identity file, `identity`, 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. Certificate Lifetime By default, `tctl auth sign` produces certificates with a relatively short lifetime. For production deployments, we suggest using [Machine & Workload Identity](https://goteleport.com/docs/machine-workload-identity/introduction.md) to programmatically issue and renew certificates for your plugin. See our Machine & Workload Identity [getting started guide](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to learn more. Note that you cannot issue certificates that are valid longer than your existing credentials. For example, to issue certificates with a 1000-hour TTL, you must be logged in with a session that is valid for at least 1000 hours. This means your user must have a role allowing a `max_session_ttl` of at least 1000 hours (60000 minutes), and you must specify a `--ttl` when logging in: ``` $ tsh login --proxy=teleport.example.com --ttl=60060 ``` If you are running the plugin on a Linux server, create a data directory to hold certificate files for the plugin: ``` $ sudo mkdir -p /var/lib/teleport/plugins/api-credentials $ sudo mv identity /var/lib/teleport/plugins/api-credentials ``` If you are running the plugin on Kubernetes, create a Kubernetes secret that contains the Teleport identity file: ``` $ kubectl -n teleport create secret generic --from-file=identity teleport-event-handler-identity ``` Once the Teleport credentials expire, you will need to renew them by running the `tctl auth sign` command again. ## Next steps You have now configured the Teleport Event Handler plugin with credentials to access the Teleport events API. If you are new to exporting audit events with Teleport, read [Forwarding Events with Fluentd](https://goteleport.com/docs/zero-trust-access/export-audit-events/fluentd.md) to learn the basics of how our Event Handler plugin works. While this guide focuses on Fluentd, the Event Handler plugin can export audit events to any endpoint that ingests JSON messages via HTTP. Next, read our guides to setting up the Event Handler plugin to export audit events to your solution of choice: - [Export Teleport Audit Events with the Elastic Stack](https://goteleport.com/docs/zero-trust-access/export-audit-events/elastic-stack.md): How to configure the Event Handler plugin to forward Teleport audit logs to Logstash for ingestion in Elasticsearch so you can explore them in Kibana. - [Export Teleport Audit Events with Panther](https://goteleport.com/docs/zero-trust-access/export-audit-events/panther.md): How to configure the Event Handler plugin to send logs to Panther via Fluentd so you can explore your audit events in Panther. - [Export Teleport Audit Events with Splunk](https://goteleport.com/docs/zero-trust-access/export-audit-events/splunk.md): How to configure the Event Handler plugin to send logs to Splunk's Universal Forwarder so you can explore your audit events in Splunk. - [Export Teleport Audit Events with Datadog](https://goteleport.com/docs/zero-trust-access/export-audit-events/datadog.md): How to configure the Event Handler plugin to export audit logs to Datadog via Fluentd.