Skip to main content
Version: 8.2505.x RR

JWT Authentication (Preview)

Preview

JWT bearer token authentication is a preview feature. The configuration interface may change in future releases.

Overview​

In addition to Nevis SecTokens and SAML assertions, Ninja can verify JSON Web Token (JWT) bearer tokens. JWT authentication is enabled by configuring the jwt.verify.sig.key.type property with the appropriate key type. When a JWT is received, Ninja validates the signature and claims using the configured key material, then establishes the authenticated identity in the same way as for SecTokens.

Both SecToken and JWT verification can be active at the same time. When a request arrives with an Authorization: Bearer header, it is processed as a JWT and takes precedence over the SecToken path. Requests arriving with Authorization: Basic (the SecToken transport used by nevisProxy) continue to be processed as SecTokens.

Only signed JWTs, known as JSON Web Signatures (JWS), are supported. Encrypted JWTs, known as JSON Web Encryption (JWE), are not currently supported. Unsecured JWTs (alg=none) are also rejected.

The exp claim is required. Tokens without an exp claim are rejected per RFC 8725 §3.3.

For guidance on integrating JWT authentication in a Nevis deployment — including nevisProxy configuration, nevisAuth authstate examples, and signing key patterns — see Integration with Nevis Components.

Identity mapping​

The following JWT claims are mapped to the Ninja identity:

JWT claimNinja fieldNotes
subPrincipal name (user ID)Required for identity resolution
rolesNinja rolesString or JSON string array
groupsNinja roles (merged with roles)String or JSON string array
All other claimsToken attributesAccessible via NinjaTokenPrincipal.getAttributes()

Configuration properties​

All JWT-related properties use the jwt. prefix. They are passed to the underlying nevis-jwt library (with the prefix stripped) alongside all other Ninja options.

jwt.verify.sig.key.type​

The type of key source used for JWT signature verification. Setting this property (together with jwt.verify.sig.key.value) enables JWT authentication. When absent or blank, JWT authentication is disabled.

Accepted values:

  • pem — a PEM-encoded RSA or EC public key, supplied inline or as a file path
  • jwks — a JWKS endpoint URL (http://, https://, or file://), or an inline JWKS JSON object (a value starting with {)
  • jks — a JKS truststore file containing one or more CA certificates
  • pkcs12 — a PKCS12 truststore file containing one or more CA certificates
  • hmac — a shared secret for symmetric HS256/HS384/HS512 verification

Syntax: pem | jwks | jks | pkcs12 | hmac

Default: none (JWT authentication disabled when absent)

jwt.verify.sig.key.value​

The key material for JWT signature verification. Interpretation depends on jwt.verify.sig.key.type:

  • pem — inline PEM text or a filesystem path to a PEM file
  • jwks — a URL (http://, https://, file://), an absolute filesystem path (for example /etc/nevis/jwks.json), or an inline JWKS JSON object
  • jks / pkcs12 — a filesystem path to the keystore file
  • hmac — the shared secret string (UTF-8), at least 32 bytes (256 bits)

This property is required when jwt.verify.sig.key.type is configured.

Syntax: <inline-value-or-path>

Default: none

jwt.verify.sig.key.password​

Password for the keystore. Used only when jwt.verify.sig.key.type is jks or pkcs12 and required only if the keystore is password-protected.

Syntax: <password>

Default: none

jwt.verify.claims.issuer​

Accepted iss claim values. Any one match is sufficient. Use a plain string for a single value, or a JSON string array for multiple values (for example ["issuer-a","issuer-b"]).

Configuring at least one expected issuer is strongly recommended to prevent tokens from a different issuer being accepted.

Syntax: <issuer> or ["<issuer-a>","<issuer-b>",...]

Default: none (issuer not validated)

jwt.verify.claims.audience​

Accepted aud claim values. Any one match is sufficient. Use a plain string for a single value, or a JSON string array for multiple values.

Configuring at least one expected audience is strongly recommended to prevent token substitution attacks across services.

Syntax: <audience> or ["<audience-a>","<audience-b>",...]

Default: none (audience not validated)

jwt.verify.claims.clock-skew​

Symmetric clock-skew leeway applied to both the exp and nbf claims. A token whose exp is in the past by at most this duration, or whose nbf is in the future by at most this duration, is still accepted. The exp claim is always required regardless of this setting — clock skew only widens the acceptance window, it does not make a missing exp acceptable.

Accepts a human-readable duration string (for example 30s, 1m) or a plain millisecond count.

Syntax: <duration>

Default: 0 (no leeway)

jwt.verify.sig.allowed-algorithms​

Comma-separated allowlist of permitted signing algorithm identifiers. When configured with one or more values, JWTs signed with any algorithm not in this list are rejected. When absent or configured as an empty value, all algorithms supported by the configured key type are accepted.

Standard algorithm identifiers (RFC 7518): RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

Syntax: <alg>,<alg>,...

Default: none (all algorithms for the key type are accepted)

jwt.verify.sig.required-typ​

Required value of the typ JOSE header (case-insensitive). When set, JWTs with a different or missing typ header are rejected. Typical values are JWT or at+JWT (RFC 9068).

Configuring this is recommended (RFC 8725 §3.11) to prevent token substitution attacks between different applications or token types.

Syntax: <typ-value>

Default: none (typ header is not checked)

JWKS-specific options​

The following properties apply only when jwt.verify.sig.key.type is jwks and jwt.verify.sig.key.value points to a remote JWKS endpoint. When an inline JWKS JSON object is used, proxy and TLS options do not apply.

jwt.verify.sig.jwks.proxy.url​

Forward-proxy URL for JWKS endpoint retrieval, for example http://proxy.example.com:3128.

The URL must contain both host and port.

Syntax: <url>

Default: none

jwt.verify.sig.jwks.proxy.username​

Username for proxy authentication.

Syntax: <username>

Default: none

jwt.verify.sig.jwks.proxy.password​

Password for proxy authentication.

Syntax: <password>

Default: none

jwt.verify.sig.jwks.cache.enabled​

Enables or disables caching of JWKS responses. Disable only for testing.

Syntax: true | false

Default: true

jwt.verify.sig.jwks.cache.ttl​

Time-to-live for cached JWKS responses. Accepts a human-readable duration string (for example 30m, 1h) or a plain millisecond count.

Syntax: <duration>

Default: 30m

jwt.verify.sig.jwks.timeout​

HTTP connect-and-request timeout for JWKS endpoint retrieval. Accepts a human-readable duration string (for example 10s, 1m30s) or a plain millisecond count.

Syntax: <duration>

Default: 10s

jwt.verify.sig.jwks.tls.truststore.path​

Path to a TLS truststore file (JKS or PKCS12) containing the CA certificates to trust when fetching JWKS over HTTPS.

Syntax: <path>

Default: none (JVM default truststore is used)

jwt.verify.sig.jwks.tls.truststore.password​

Password for the TLS truststore.

Syntax: <password>

Default: none

jwt.verify.sig.jwks.tls.truststore.type​

Type of the TLS truststore. Accepted values are JKS and PKCS12.

Syntax: JKS | PKCS12

Default: JVM default (KeyStore.getDefaultType())

Example configuration​

The following example shows JWT verification against a third-party identity provider using a remote JWKS endpoint. sectoken.signer.cert is included here because this filter also verifies Nevis SecTokens; in a JWT-only deployment it can be omitted.

<filter>
<filter-name>NinjaAuthenticationFilter</filter-name>
<filter-class>ch.nevis.ninja.filter.NinjaAuthenticationFilter</filter-class>
<init-param>
<param-name>sectoken.signer.cert</param-name>
<param-value>/opt/nevis/truststore.jks</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.sig.key.type</param-name>
<param-value>jwks</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.sig.key.value</param-name>
<param-value>https://idp.example.com/.well-known/jwks.json</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.issuer</param-name>
<param-value>https://idp.example.com</param-value>
</init-param>
<init-param>
<param-name>jwt.verify.claims.audience</param-name>
<param-value>my-service</param-value>
</init-param>
</filter>

Security recommendations​

  • Always configure jwt.verify.claims.issuer and jwt.verify.claims.audience. Without these, any JWT signed with the correct key is accepted regardless of its intended recipient or origin.
  • Use jwt.verify.sig.required-typ to prevent token substitution across different token types.
  • Consider jwt.verify.sig.allowed-algorithms to restrict accepted algorithms explicitly.
  • Keep jwt.verify.sig.jwks.cache.ttl at a reasonable value (the default of 30 minutes is appropriate for most deployments) to limit the impact of a compromised key.
  • Note that this implementation does not enforce jti uniqueness; replay protection must be implemented at the application layer if required.