Skip to main content

Using JWT authentication with Elasticsearch

Report an issue with this page

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

Prerequisites​

  • A running Teleport cluster. If you do not have one, read Getting Started.

  • 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:

      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.

  • 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  19.0.0-dev
    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.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://<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.
  • 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 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: true
  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/_authenticate | jq

Next steps​