Skip to content

Authenticate Using JSON Web Tokens

Okera can use JSON Web Tokens (JWTs) for authentication. These tokens can either be generated externally and provided to Okera, or else Okera can be configured to work with an external service (via REST) to acquire and validate JWTs. If only JWTs are used for authentication, Okera also requires that a system token be generated for use in authentication with internal services. This is typically a token with okera as the subject.

Okera supports the standard JWT claims including:

  • sub
  • exp
  • nbf

Okera requires that JWTs have a sub claim. For specifying groups in which the token subject is a member, Okera suggests using the claim groups and storing the associated value as a list of strings.

Example JWT payload: 

{
  "sub": "John Doe",
  "iss": "okera.com",
  "groups": [
    "web_user",
    "philatelist",
    "cat_person"
  ],
  "exp": 1590510807
}

Okera can be configured for JWT support using two approaches:

  1. Provide services with the public key used to verify the tokens and the algorithm used (RSA256 or RSA512).
  2. Configure an endpoint for validating tokens.

For either of these approaches, you must also provide:

  1. A system token that Okera uses internally for interservice communication.
  2. A separate private key and public key pair (along with the algorithm for the public key) for Okera to use to create its own tokens when needed.

Using Both Approaches for JWT Validation

To support both approaches, configure the settings for both, and each is instantiated. The external endpoint is used first. If the JWT is not validated by that service, it is passed to the public-key authenticator for validation.

Configuration Settings

For information on the Okera configuration settings used to configure SSL in the values.yaml file used by the Helm chart for your Okera cluster, see JWT Configuration Parameters.

Remote Endpoint Validation

To configure the remote endpoint approach for validation, configure an endpoint for validating tokens remotely by way of the JWT_AUTHENTICATION_SERVER_URL setting.

For example:

JWT_AUTHENTICATION_SERVER_URL: http://10.1.10.1:8000/idp/userinfo.openid

The call from Okera to the REST endpoint is a POST request that passes the JWT to validate as a bearer token and expects JSON as the return value. As a REST call, it looks like this:

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <token>' http://<ip>:<port>/<endpoint>

The return value must contain the key "sub" and the value must be a string that contains the username that corresponds to the passed token. Example: 

{
    "sub": "santa@okera.com"
}

System Token

To configure Okera to do interservice communication when JWT authentication is enabled, the setting SYSTEM_TOKEN must be set to the full path of the token to use.

For example:

SYSTEM_TOKEN: file:///path/to/system.token

This token should have a sub value of okera.

Group Resolution Using JWTs

When a request is authenticated with JWTs, the following sequence is used to determine what groups this request will use for the authenticated user:

  1. If the JWT contains a groups field, then the value of this field is used as the set of groups.
  2. If an AD/LDAP group resolver is defined, then the sub field of the JWT is used as the user passed to the resolver.
  3. If an endpoint-based group resolver is defined, then the sub field of the JWT is used as the user passed to the resolver.