Fork me on GitHub


Using JWT authentication with Elasticsearch

  • Available for:
  • OpenSource
  • Team
  • Cloud
  • Enterprise

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


  • A running Teleport cluster. For details on how to set this up, see the Getting Started guide.

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

    See Installation for details.

  • A Teleport Team account. If you don't have an account, sign up to begin your free trial.

  • The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

    You can download these tools from the Cloud Downloads page.

  • A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

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

    You can download these tools by visiting your Teleport account workspace.

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To check version information, run the tctl version and tsh version commands. For example:

tctl version

Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version

Teleport v13.3.9 go1.21

Proxy version: 13.3.9Proxy:
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:
    tsh login --user=[email protected]
    tctl status


    Version 14.0.0

    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