Version: SG FLX

JWT Authentication Quick Start

Search Guard supports user authentication with JSON Web Tokens (JWT).

This chapter describes the basic setup of JWT with Search Guard. This will work in many cases; some setups, however, require special configurations. Please refer to the section Advanced Configuration for this.


To use JWT based authentication, you need the keys which are used to sign the JWT. You can provide these in form of a JSON Web Key or JSON Web Key Set (JWK/JWKS) or in form of EC or RSA public keys or certificates in PEM format. You can also use an OIDC .well-known/openid-configuration URL to retrieve the signing keys.

Additionally, you need to clarify from where to retrieve the roles of a user. These can be encoded in form of a claim inside of the JWT. However, there is no standardized format or claim name for this.

Search Guard setup

A minimal sg_authc.yml file for JWT authentication using JWKS looks like this:

- type: jwt
  - kty: RSA
    use: sig
    alg: RS256
    n: "jicRTT-2H3U6jAoBeUKh8s..."
    e: "AQAB"
  user_mapping.roles.from_comma_separated_string: jwt.roles

The section below jwt.signing.jwks.keys is a JWKS document encoded into the YAML structure.

If you have a config variable containing a PEM file with an RSA certificate, you can use a configuration similar to the following:

- type: jwt
  jwt.signing.rsa.certificate: "#{var:jwt_rsa_cert}"
  jwt.signing.rsa.algorithm: RS256
  user_mapping.roles.from_comma_separated_string: jwt.roles

If you have a PEM with with an EC certificate, use this:

- type: jwt "#{var:jwt_ec_cert}" "P-521"
  user_mapping.roles.from_comma_separated_string: jwt.roles

Note that you must specify a curve for EC, which is either P-256, P-384 or P-521.

For options on how to retrieve the keys from external endpoints, see advanced configuration.

Audience validation

JWT contain an “audience claim” which defines the system which is supposed to use the JWT. You can configure Search Guard to validate the audience claim. For this, use the option jwt.required_audience.


The examples above assumed that the JWT contains an attribute called roles which is a simple, comma-separated string of role names. Thus, the user_mapping.roles configuration was set like this:

  user_mapping.roles.from_comma_separated_string: jwt.roles

If your JWT contain the roles in a different attribute, you can change the attribute path specification accordingly.

It is also possible that your JWT contain the roles as an actual array of strings. Then, use this configuration:

  user_mapping.roles.from: jwt.roles

In some cases, JWT do not contain role information. In that case, you need a user information backend to retrieve role information.

Activate the setup

After having applied the changes to sg_authc.yml, use sgctl to upload the file to Search Guard:

$ ./ update-config sg_authc.yml

That’s it. You can test the JWT setup with your favorite REST client. If you are using curl, you can try this command:

$ curl -H "Authorization: Bearer ${JWT}" ""

Where to go next

Not what you were looking for? Try the search.