JWT authentication

The header claims indicate the token type and the algorithm used to sign the token.

Tokens contain several claims, which provide information about the user who is issuing the token, and the token itself. Depending on the token type, these information can optionally be identified by different claims.

You can use the create or update role mappings API to define role mappings that determine which roles should be assigned to each user based on their username, groups, or other metadata.

resp = client.security.put_role_mapping(
    name="jwt1_users",
    refresh=True,
    roles=[
        "user"
    ],
    rules={
        "all": [
            {
                "field": {
                    "realm.name": "jwt1"
                }
            },
            {
                "field": {
                    "username": "principalname1"
                }
            },
            {
                "field": {
                    "dn": "CN=Principal Name 1,DC=example.com"
                }
            },
            {
                "field": {
                    "groups": "group1"
                }
            },
            {
                "field": {
                    "metadata.jwt_claim_other": "other1"
                }
            }
        ]
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "jwt1_users",
  refresh: "true",
  roles: ["user"],
  rules: {
    all: [
      {
        field: {
          "realm.name": "jwt1",
        },
      },
      {
        field: {
          username: "principalname1",
        },
      },
      {
        field: {
          dn: "CN=Principal Name 1,DC=example.com",
        },
      },
      {
        field: {
          groups: "group1",
        },
      },
      {
        field: {
          "metadata.jwt_claim_other": "other1",
        },
      },
    ],
  },
  enabled: true,
});
console.log(response);

PUT /_security/role_mapping/jwt1_users?refresh=true
{
  "roles" : [ "user" ],
  "rules" : { "all" : [
      { "field": { "realm.name": "jwt1" } },
      { "field": { "username": "principalname1" } },
      { "field": { "dn": "CN=Principal Name 1,DC=example.com" } },
      { "field": { "groups": "group1" } },
      { "field": { "metadata.jwt_claim_other": "other1" } }
  ] },
  "enabled": true
}

If you use this API in the JWT realm, the following claims are available for role mapping:

If you delegate authorization to other realms from the JWT realm, only the principal claim is available for role lookup. When delegating the assignment and lookup of roles to another realm from the JWT realm, claims for dn, groups, mail, metadata, and name are not used for the Elasticsearch user’s values. Only the JWT principal claim is passed to the delegated authorization realms. The realms that are delegated for authorization - not the JWT realm - become responsible for populating all of the Elasticsearch user’s values.

The following example shows how you define delegation authorization in the elasticsearch.yml file to multiple other realms from the JWT realm. A JWT realm named jwt2 is delegating authorization to multiple realms:

xpack.security.authc.realms.jwt.jwt2.authorization_realms: file1,native1,ldap1,ad1

You can then use the create or update role mappings API to map roles to the authorizing realm. The following example maps roles in the native1 realm for the principalname1 JWT principal.

resp = client.security.put_role_mapping(
    name="native1_users",
    refresh=True,
    roles=[
        "user"
    ],
    rules={
        "all": [
            {
                "field": {
                    "realm.name": "native1"
                }
            },
            {
                "field": {
                    "username": "principalname1"
                }
            }
        ]
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "native1_users",
  refresh: "true",
  roles: ["user"],
  rules: {
    all: [
      {
        field: {
          "realm.name": "native1",
        },
      },
      {
        field: {
          username: "principalname1",
        },
      },
    ],
  },
  enabled: true,
});
console.log(response);

PUT /_security/role_mapping/native1_users?refresh=true
{
  "roles" : [ "user" ],
  "rules" : { "all" : [
      { "field": { "realm.name": "native1" } },
      { "field": { "username": "principalname1" } }
  ] },
  "enabled": true
}

If realm jwt2 successfully authenticates a client with a JWT for principal principalname1, and delegates authorization to one of the listed realms (such as native1), then that realm can look up the Elasticsearch user’s values. With this defined role mapping, the realm can also look up this role mapping rule linked to realm native1.

Elasticsearch can retrieve roles for a JWT user through either role mapping or delegated authorization. Regardless of which option you choose, you can apply the run_as privilege to a role so that a user can submit authenticated requests to "run as" a different user. To submit requests as another user, include the es-security-runas-user header in your requests. Requests run as if they were issued from that user and Elasticsearch uses their roles.

For example, let’s assume that there’s a user with the username user123_runas. The following request creates a user role named jwt_role1, which specifies a run_as user with the user123_runas username. Any user with the jwt_role1 role can issue requests as the specified run_as user.

resp = client.security.put_role(
    name="jwt_role1",
    refresh=True,
    cluster=[
        "manage"
    ],
    indices=[
        {
            "names": [
                "*"
            ],
            "privileges": [
                "read"
            ]
        }
    ],
    run_as=[
        "user123_runas"
    ],
    metadata={
        "version": 1
    },
)
print(resp)

const response = await client.security.putRole({
  name: "jwt_role1",
  refresh: "true",
  cluster: ["manage"],
  indices: [
    {
      names: ["*"],
      privileges: ["read"],
    },
  ],
  run_as: ["user123_runas"],
  metadata: {
    version: 1,
  },
});
console.log(response);

POST /_security/role/jwt_role1?refresh=true
{
  "cluster": ["manage"],
  "indices": [ { "names": [ "*" ], "privileges": ["read"] } ],
  "run_as": [ "user123_runas" ],
  "metadata" : { "version" : 1 }
}

You can then map that role to a user in a specific realm. The following request maps the jwt_role1 role to a user with the username user2 in the jwt2 JWT realm. This means that Elasticsearch will use the jwt2 realm to authenticate the user named user2. Because user2 has a role (the jwt_role1 role) that includes the run_as privilege, Elasticsearch retrieves the role mappings for the user123_runas user and uses the roles for that user to submit requests.

resp = client.security.put_role_mapping(
    name="jwt_user1",
    refresh=True,
    roles=[
        "jwt_role1"
    ],
    rules={
        "all": [
            {
                "field": {
                    "realm.name": "jwt2"
                }
            },
            {
                "field": {
                    "username": "user2"
                }
            }
        ]
    },
    enabled=True,
    metadata={
        "version": 1
    },
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "jwt_user1",
  refresh: "true",
  roles: ["jwt_role1"],
  rules: {
    all: [
      {
        field: {
          "realm.name": "jwt2",
        },
      },
      {
        field: {
          username: "user2",
        },
      },
    ],
  },
  enabled: true,
  metadata: {
    version: 1,
  },
});
console.log(response);

POST /_security/role_mapping/jwt_user1?refresh=true
{
  "roles": [ "jwt_role1"],
  "rules" : { "all" : [
      { "field": { "realm.name": "jwt2" } },
      { "field": { "username": "user2" } }
  ] },
  "enabled": true,
  "metadata" : { "version" : 1 }
}

After mapping the roles, you can make an authenticated call to Elasticsearch using a JWT and include the ES-Client-Authentication header:

curl -s -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZXMwMSIsImVzMDIiLCJlczAzIl0sInN1YiI6InVzZXIyIiwiaXNzIjoibXktaXNzdWVyIiwiZXhwIjo0MDcwOTA4ODAwLCJpYXQiOjk0NjY4NDgwMCwiZW1haWwiOiJ1c2VyMkBzb21ldGhpbmcuZXhhbXBsZS5jb20ifQ.UgO_9w--EoRyUKcWM5xh9SimTfMzl1aVu6ZBsRWhxQA" -H "ES-Client-Authentication: sharedsecret test-secret" https://localhost:9200/_security/_authenticate

The response includes the user who submitted the request (user2), including the jwt_role1 role that you mapped to this user in the JWT realm:

{"username":"user2","roles":["jwt_role1"],"full_name":null,"email":"user2@something.example.com",
"metadata":{"jwt_claim_email":"user2@something.example.com","jwt_claim_aud":["es01","es02","es03"],
"jwt_claim_sub":"user2","jwt_claim_iss":"my-issuer"},"enabled":true,"authentication_realm":
{"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"jwt2","type":"jwt"},"authentication_type":"realm"}
%

If you want to specify a request as the run_as user, include the es-security-runas-user header with the name of the user that you want to submit requests as. The following request uses the user123_runas user:

curl -s -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOlsiZXMwMSIsImVzMDIiLCJlczAzIl0sInN1YiI6InVzZXIyIiwiaXNzIjoibXktaXNzdWVyIiwiZXhwIjo0MDcwOTA4ODAwLCJpYXQiOjk0NjY4NDgwMCwiZW1haWwiOiJ1c2VyMkBzb21ldGhpbmcuZXhhbXBsZS5jb20ifQ.UgO_9w--EoRyUKcWM5xh9SimTfMzl1aVu6ZBsRWhxQA" -H "ES-Client-Authentication: sharedsecret test-secret" -H "es-security-runas-user: user123_runas" https://localhost:9200/_security/_authenticate

In the response, you’ll see that the user123_runas user submitted the request, and Elasticsearch used the jwt_role1 role:

{"username":"user123_runas","roles":["jwt_role1"],"full_name":null,"email":null,"metadata":{},
"enabled":true,"authentication_realm":{"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"native",
"type":"native"},"authentication_type":"realm"}%

JWT authentication supports signature verification using PKC (Public Key Cryptography) or HMAC algorithms.

PKC JSON Web Token Key Sets (JWKS) can contain public RSA and EC keys. HMAC JWKS or an HMAC UTF-8 JWK contain secret keys. JWT issuers typically rotate PKC JWKS more frequently (such as daily), because RSA and EC public keys are designed to be easier to distribute than secret keys like HMAC.

JWT realms load a PKC JWKS and an HMAC JWKS or HMAC UTF-8 JWK at startup. JWT realms can also reload PKC JWKS contents at runtime; a reload is triggered by signature validation failures.

Load failures, parse errors, and configuration errors prevent a node from starting (and restarting). However, runtime PKC reload errors and recoveries are handled gracefully.

All other JWT realm validations are checked before a signature failure can trigger a PKC JWKS reload. If multiple JWT authentication signature failures occur simultaneously with a single Elasticsearch node, reloads are combined to reduce the reloads that are sent externally.

Separate reload requests cannot be combined if JWT signature failures trigger:

The following values are for the bespoke JWT issuer.

Issuer:     iss8
Audiences:  aud8
Algorithms: HS256
HMAC UTF-8: hmac-oidc-key-string-for-hs256-algorithm

To define a JWT realm, add the following realm settings to elasticsearch.yml.

xpack.security.authc.realms.jwt.jwt8.order: 8 
xpack.security.authc.realms.jwt.jwt8.allowed_issuer: iss8
xpack.security.authc.realms.jwt.jwt8.allowed_audiences: [aud8]
xpack.security.authc.realms.jwt.jwt8.allowed_signature_algorithms: [HS256]
xpack.security.authc.realms.jwt.jwt8.claims.principal: sub
xpack.security.authc.realms.jwt.jwt8.client_authentication.type: shared_secret

After defining the realm settings, use the elasticsearch-keystore tool to add the following secure settings to the Elasticsearch keystore. In Elastic Cloud, you define settings for the Elasticsearch keystore under Security in your deployment.

xpack.security.authc.realms.jwt.jwt8.hmac_key: hmac-oidc-key-string-for-hs256-algorithm
xpack.security.authc.realms.jwt.jwt8.client_authentication.shared_secret: client-shared-secret-string

The following request creates role mappings for Elasticsearch in the jwt8 realm for the user principalname1:

resp = client.security.put_role_mapping(
    name="jwt8_users",
    refresh=True,
    roles=[
        "user"
    ],
    rules={
        "all": [
            {
                "field": {
                    "realm.name": "jwt8"
                }
            },
            {
                "field": {
                    "username": "principalname1"
                }
            }
        ]
    },
    enabled=True,
)
print(resp)

const response = await client.security.putRoleMapping({
  name: "jwt8_users",
  refresh: "true",
  roles: ["user"],
  rules: {
    all: [
      {
        field: {
          "realm.name": "jwt8",
        },
      },
      {
        field: {
          username: "principalname1",
        },
      },
    ],
  },
  enabled: true,
});
console.log(response);

PUT /_security/role_mapping/jwt8_users?refresh=true
{
  "roles" : [ "user" ],
  "rules" : { "all" : [
      { "field": { "realm.name": "jwt8" } },
      { "field": { "username": "principalname1" } }
  ] },
  "enabled": true
}

The following header settings are for an Elasticsearch client.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJpc3M4IiwiYXVkIjoiYXVkOCIsInN1YiI6InNlY3VyaXR5X3Rlc3RfdXNlciIsImV4cCI6NDA3MDkwODgwMCwiaWF0Ijo5NDY2ODQ4MDB9.UnnFmsoFKfNmKMsVoDQmKI_3-j95PCaKdgqqau3jPMY
ES-Client-Authentication: SharedSecret client-shared-secret-string

You can use this header in a curl request to make an authenticated call to Elasticsearch. Both the bearer token and the client authorization token must be specified as separate headers with the -H option:

curl -s -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJpc3M4IiwiYXVkIjoiYXVkOCIsInN1YiI6InNlY3VyaXR5X3Rlc3RfdXNlciIsImV4cCI6NDA3MDkwODgwMCwiaWF0Ijo5NDY2ODQ4MDB9.UnnFmsoFKfNmKMsVoDQmKI_3-j95PCaKdgqqau3jPMY" -H "ES-Client-Authentication: SharedSecret client-shared-secret-string" https://localhost:9200/_security/_authenticate

If you used role mapping in the JWT realm, the response includes the user’s username, their roles, metadata about the user, and the details about the JWT realm itself.

{"username":"user2","roles":["jwt_role1"],"full_name":null,"email":"user2@something.example.com",
"metadata":{"jwt_claim_email":"user2@something.example.com","jwt_claim_aud":["es01","es02","es03"],
"jwt_claim_sub":"user2","jwt_claim_iss":"my-issuer"},"enabled":true,"authentication_realm":
{"name":"jwt2","type":"jwt"},"lookup_realm":{"name":"jwt2","type":"jwt"},"authentication_type":"realm"}