# Using JWT Authentication with Elasticsearch This guide will help you configure Elasticsearch [JWT authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/jwt-realm.html) with Teleport. ## 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 ``` * 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 18.7.3 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. * Running [Application Service](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/connecting-apps.md). * Elasticsearch cluster version >= `8.2.0`. ## Step 1/3. Enable a JWT realm in Elasticsearch Update your Elasticsearch configuration file, `elasticsearch.yaml`, to enable a JWT realm: ``` xpack.security.authc.realms.jwt.teleport: order: 1 client_authentication.type: none pkc_jwkset_path: https://proxy.example.com/.well-known/jwks.json claims.principal: sub claims.groups: roles allowed_issuer: example-cluster allowed_audiences: ["https://elasticsearch.example.com:9200"] ``` --- ELASTIC CLOUD For **hosted deployments** in Elastic Cloud, you can configure the same settings by editing your deployment. Go to "Manage user settings and extensions" for "Elasticsearch", then add the configuration snippet above under "User Settings". You may have to use an order number bigger than 1. Please note that Elastic Cloud **Serverless** projects do not support connecting external realms, and therefore cannot be configured with JWT authentication. --- Let's take a closer look at the parameters and their values: - Set `client_authentication.type` to `none`, otherwise Elasticsearch requires clients to send a shared secret value with each request. - Set `pkc_jwkset_path` to the JWT key set file URL of your Teleport Proxy. It is available at `https:///.well-known/jwks.json` endpoint. You can also download the JSON file from the same URL and point the path directly to it instead of using a URL. - Set `claims.principal` and `claims.groups` to `sub` and `roles` respectively. These are the claims Teleport uses to pass user and role information in JWT tokens. - Set `allowed_issuer` to the name of your Teleport cluster. - Set `allowed_audiences` to the URL which Teleport Application Service will use to connect to Elasticsearch. --- ELASTICSEARCH ROLE MAPPING Note that when using JWT authentication, you cannot map user roles using the standard Elasticsearch `role_mapping.yml` file. Instead, you need to set the role mapping using the API. For example, you can create the following mapping to map Teleport's `access` role to `superuser` role in Elasticsearch: ``` PUT /_security/role_mapping/teleport_access { "roles": [ "superuser" ], "rules": { "all": [ { "field": { "realm.name": "teleport" } }, { "field": { "groups": "access" } } ] }, "enabled": true } ``` See [JWT realm authorization](https://www.elastic.co/guide/en/elasticsearch/reference/current/jwt-realm.html#jwt-authorization) for details. --- ## Step 2/3. Register an Elasticsearch application in Teleport In your Teleport Application Service configuration file, `teleport.yaml`, register an entry for Elasticsearch: ``` app_service: enabled: true apps: - name: "elastic" uri: https://elasticsearch.example.com:9200 rewrite: headers: - "Authorization: Bearer {{internal.jwt}}" ``` Elasticsearch requires a JWT token to be passed inside the `Authorization` header. The header rewrite configuration above will replace the `{{internal.jwt}}` template variable with a Teleport-signed JWT token in each request. ## Step 3/3. Connect to the ElasticSearch API Log into your Teleport cluster with `tsh login` and make sure your Elasticsearch application is available: ``` $ tsh apps ls Application Description Public Address Labels ----------- ------------- ---------------------------- ------------------------------- elastic elastic.teleport.example.com ``` Fetch a short-lived X.509 certificate for Elasticsearch: ``` $ tsh apps login elastic ``` Then you can use the `curl` command to communicate with the Elasticsearch API, which will authenticate you as your Teleport user: ``` $ curl \ --cacert ~/.tsh/keys/teleport.example.com/cas/root.pem \ --cert ~/.tsh/keys/teleport.example.com/alice-app/example-cluster/elastic-x509.pem \ --key ~/.tsh/keys/teleport.example.com/alice \ https://elastic.teleport.example.com/_security/_authenticate | jq ``` ## Next steps - Get more information about integrating with [Teleport JWT tokens](https://goteleport.com/docs/enroll-resources/application-access/jwt/introduction.md). - See the [dynamic registration](https://goteleport.com/docs/enroll-resources/application-access/configuration/dynamic-registration.md) guide. - Learn more about [accessing APIs](https://goteleport.com/docs/enroll-resources/application-access/protect-apps/api-access.md) with the Teleport Application Service. - Take a look at application-related [Access Controls](https://goteleport.com/docs/enroll-resources/application-access/configuration/controls.md).