Teleport
Using JWT authentication with Elasticsearch
Version preview- Older Versions
This guide will help you configure Elasticsearch JWT authentication with Teleport.
Prerequisites
-
A running Teleport cluster version 16.4.7 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 andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=email@example.comtctl statusCluster teleport.example.com
Version 16.4.7
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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
tonone
, 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 athttps://<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
andclaims.groups
tosub
androles
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.
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}}"
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 lsApplication 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.