Skip to main content
Version: 15.x

Using JWT authentication with Elasticsearch

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

Prerequisites​

  • A running Teleport cluster version 15.4.22 or above. 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.

    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 [email protected]
    $ tctl status
    # Cluster  teleport.example.com
    # Version  15.4.22
    # 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.
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:

app_service:
  enabled: "yes"
  apps:
  - name: "elastic"
    uri: https://elasticsearch.example.com:9200
    rewrite:
      headers:
      - "Authorization: Bearer {{internal.jwt}}"
tip

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                   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​