Secure your clusters with JWT

These steps show how you can secure your Elasticsearch clusters, and Enterprise Search instances in a deployment by using a JSON Web Token (JWT) realm for authentication.

Before you begin

edit

Elasticsearch Add-On for Heroku supports JWT of ID Token format with Elastic Stack version 8.2 and later. Support for JWT of certain access token format is available since 8.7.

Configure your 8.2 or above cluster to use JWT of ID Token format

edit

xpack:
  security:
    authc:
      realms:
        jwt: 
          jwt-realm-name: 
            order: 2 
            client_authentication.type: "shared_secret" 
            allowed_signature_algorithms: "HS256,HS384,HS512,RS256,RS384,RS512,ES256,ES384,ES512,PS256,PS384,PS512" 
            allowed_issuer: "issuer1" 
            allowed_audiences: "elasticsearch1,elasticsearch2" 
            claims.principal: "sub" 
            claims.groups: "groups"

	Specifies the authentication realm service.
	Defines the JWT realm name.
	The order of the JWT realm in your authentication chain. Allowed values are between `2` and `100`, inclusive.
	Defines the client authenticate type.
	Defines the JWT `alg` header values allowed by the realm.
	Defines the JWT `iss` claim value allowed by the realm.
	Defines the JWT `aud` claim values allowed by the realm.
	Defines the JWT claim name used for the principal (username). No default.
	Defines the JWT claim name used for the groups. No default.

By default, users authenticating through JWT have no roles assigned to them. If you want all users in the group elasticadmins in your identity provider to be assigned the superuser role in your Elasticsearch cluster, issue the following request to Elasticsearch:

POST /_security/role_mapping/CLOUD_JWT_ELASTICADMIN_TO_SUPERUSER 
{
   "enabled": true,
    "roles": [ "superuser" ], 
    "rules": { "all" : [ 
        { "field": { "realm.name": "jwt-realm-name" } }, 
        { "field": { "groups": "elasticadmins" } }
    ]},
    "metadata": { "version": 1 }
}

	The mapping name.
	The Elastic Stack role to map to.
	A rule specifying the JWT role to map from.
	`realm.name` can be any string containing only alphanumeric characters, underscores, and hyphens.

In order to use the field groups in the mapping rule, you need to have mapped the JWT Attribute that conveys the group membership to claims.groups in the previous step.

Configure your 8.7 or above cluster to use JWT of access token format

edit

xpack:
  security:
    authc:
      realms:
        jwt:
          jwt-realm-name:
            order: 2
            token_type: "access_token" 
            client_authentication.type: "shared_secret"
            allowed_signature_algorithms: [ "RS256", "HS256" ]
            allowed_subjects: [ "123456-compute@developer.example.com" ] 
            allowed_issuer: "issuer1"
            allowed_audiences: [ "elasticsearch1", "elasticsearch2" ]
            required_claims: 
              token_use: "access"
            fallback_claims.sub: "client_id" 
            fallback_claims.aud: "scope" 
            claims.principal: "sub" 
            claims.groups: "groups"

	Specifies token type accepted by this JWT realm
	Specifies subjects allowed by the realm. This setting is mandatory for `access_token` JWT realms.
	Additional claims required for successful authentication. The claim name can be any valid variable names and the claim values must be either string or array of strings.
	The name of the JWT claim to extract the subject information if the `sub` claim does not exist. This setting is only available for `access_token` JWT realms.
	The name of the JWT claim to extract the audiences information if the `aud` claim does not exist. This setting is only available for `access_token` JWT realms.
	Since the fallback claim for `sub` is defined as `client_id`, the principal will also be extracted from `client_id` if the `sub` claim does not exist

Refer to JWT authentication documentation for more details and examples.

« Secure your clusters with Kerberos Traffic Filtering »