Using JWT authentication with Elasticsearch

This guide will help you configure Elasticsearch JWT authentication with Teleport.

Prerequisites

• A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

• The tctl admin tool and tsh client tool version >= 15.2.2.

  On Teleport Enterprise, you must use the Enterprise version of tctl, which you can download from your Teleport account workspace. Otherwise, visit Installation for instructions on downloading tctl and tsh for Teleport Community Edition.

• 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. tctl is supported on macOS and Linux machines. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  15.2.2
  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.
• 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.jwt1:
  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"]

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://<proxy>/.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. Keep in mind that users and roles must exist in Elasticsearch.
• 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.

Step 2/3. Register an Elasticsearch application in Teleport

In your Teleport App Service configuration file, teleport.yaml, register an entry for Elasticsearch:

app_service:
  enabled: "yes"
  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/user | jq

Next steps

• Get more information about integrating with Teleport JWT tokens.
• Learn more about accessing APIs with the Teleport Application Service.
• Take a look at application-related Access Controls.