Scaling Privileged Access for Modern Infrastructure: Real-World Insights
Apr 25
Register Today
Teleport logoTry For Free
Fork me on GitHub


Using JWT authentication with Elasticsearch

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


  • 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 --user=[email protected]
    tctl status


    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:
  order: 1
  client_authentication.type: none
  claims.principal: sub
  claims.groups: roles
  allowed_issuer: example-cluster
  allowed_audiences: [""]

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.
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. See JWT realm authorization for details.

Step 2/3. Register an Elasticsearch application in Teleport

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

  enabled: "yes"
  - name: "elastic"
      - "Authorization: Bearer {{internal.jwt}}"

You can also use dynamic registration.

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

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/ \ --cert ~/.tsh/keys/ \ --key ~/.tsh/keys/ \ | jq

Next steps