Version: Search Guard 5 / This is an older version of Search Guard. Switch to Latest version

JSON web tokens

Installation

Download the JWT module:

JWT module

and place it in the folder

<ES installation directory>/plugins/search-guard-5

After that, restart all nodes to activate the module.

Token based authentication

JSON Web Tokens (JWT) are JSON-based access tokens that assert one or more claims. They are commonly used to implement Single-Sign-On solutions and fall in the category of token based authentication system:

• A user logs in to an application by providing credentials, e.g. username and password.
• The application validates the credentials.
• The application creates an access token and signs it.
• The application returns the token to the user.
• The user stores the access token.
• The user sends the access token along with every request.
• The server verifies the user by verifying the sent token.

You can read more about token based authentication in this blog post..

JSON web tokens

A JSON web token is self-contained in the sense that it carries all necessary information within itself. The tokens are basically Base64-encoded and signed JSON objects. So the can be passed around easily.

A JSON web token consists of three parts:

• Header
• Payload
• Signature

Header

The header contains information about the used signing mechanism, for example:

{
  "alg": "HS256",
  "typ": "JWT"
}

In this case, the header states that the message was signed using HMAC-SHA256.

Payload

The payload of a JSON web token contains the so-called JWT Claims. A claim can be any piece of information that the application that created the token has verified.

The specification defines a set of standard claims with reserved names (“registered claims”). These include, for example, the token issue, the expiration date, or the creation date.

Public claims can be created freely by the token issuer of the token. They can contain arbitrary information, such as the user name and the roles of the user.

Example:

{
  "iss": "floragunn.com",
  "exp": 1300819380,
  "name": "John Doe",
  "roles": "admin, devops"
}

Signature

The issuer of the token calculates the signature of the token by using a cryptographic hash function and a secret key over the base-64 encoded header and payload. These three parts are then concatenated via a . dot. We now have a complete JSON web token:

encoded = base64UrlEncode(header) + "." + base64UrlEncode(payload)
signature = HMACSHA256(encoded, 'secretkey');
jwt = encoded + "." + base64UrlEncode(signature)

For example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI3Nzk2Mzh9.gzSraSYS8EXBxLN_oWnFSRgCzcmJmMjLiuyu5CSpyHI

Configuring JWT support in Search Guard

In order to use JWT, set up an security domain and choose jwt as HTTP authentication type. Since the tokens already contain all required information to verify the request, challenge must be set to false.

Example:

jwt_auth_domain:
  enabled: true
  order: 0
  http_authenticator:
    type: jwt
    challenge: false
    config:
      signing_key: "base64 encoded key"
      jwt_header: "Authorization"
      jwt_url_parameter: null
      subject_key: null
      roles_key: null
  authentication_backend:
I    type: noop

Configuration parameter:

Name	Description
signing_key	The base64-encoded secret key that the issuer of the token used to sign the message. This is a shared secret between the token issuer and Search Guard.
jwt_header	The HTTP header in which the token is stored. This is typically the Authentication header with the Bearer schema: Authorization: Bearer <token>. Default is Authentication.
jwt_url_parameter	If the token is not transmitted in the HTTP header, but as an URL parameter, define the name of this parameter here.
subject_key	The key in the JSON payload that stores the users name. If not defined, the subject registered claim is taken.
roles_key	The key in the JSON payload that stores the users roles. The value of this key must be a comma-separated list of roles.

Since JSON web tokens are self-contained and the user is authenticated on HTTP level, no additional authentication_backend is needed, hence it can be set to noop.

Supported formats and algorithms

The following JWT types are supported:

• Creating and parsing plaintext compact JWTs
• Creating, parsing and verifying digitally signed compact JWTs (aka JWSs) with all standard JWS algorithms:

HS256: HMAC using SHA-256
HS384: HMAC using SHA-384
HS512: HMAC using SHA-512
RS256: RSASSA-PKCS-v1_5 using SHA-256
RS384: RSASSA-PKCS-v1_5 using SHA-384
RS512: RSASSA-PKCS-v1_5 using SHA-512
PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384: RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512: RSASSA-PSS using SHA-512 and MGF1 with SHA-512
ES256: ECDSA using P-256 and SHA-256
ES384: ECDSA using P-384 and SHA-384
ES512: ECDSA using P-521 and SHA-512

Using JWT with RS256

While HS256 (HMAC with SHA-256) is based on a shared secret, RS256 (RSA Signature with SHA-256) uses a public/private key pair. Since you only need to configure the public key in the JWT authenticator to validate the token, it’s considered more secure than using HS256.

In order to use RS256, you only need to configure the (non-base-64 encoded) public RSA key as signing_key in the JWT configuration like:

jwt_auth_domain:
  ...
    config:
      signing_key: |-
        -----BEGIN PUBLIC KEY-----
        MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQK...
        -----END PUBLIC KEY-----
      ...

You can also break the key into multiple lines if required.

Search Guard will detect the correct algorithm automatically.

Validated registered claims

The following registered claims are validated:

• “iat” (Issued At) Claim
• “nbf” (Not Before) Claim
• “exp” (Expiration Time) Claim

Misc

• “sub” (Subject) Claim
  • If no subject_key is defined, the value of the sub claim is used as username.