Skip to main content
Version: 7.2405.x.x LTS

JWT plug-in - JWTToken AuthState

Introduction and overview

JWT (JSON Web Token) is a compact and URL-safe format to represent claims and transfer them between two parties. For instance, JWT may be used as an alternative to Nevis SecTokens and SAML tokens to delegate a user identity to back-end applications.

Claims are always signed or encrypted. Plain-text JWT tokens are currently not supported. JWT tokens are encapsulated in a JWS (JSON Web Signature) or JWE (JSON Web Encryption) structure respectively.

The JWTToken AuthState supports the use of the JWT token.

Certificate thumbprint

The auth state automatically generates the X.509 certificate SHA-256 thumbprint header parameter x5t#S256 according to RFC-7515 for signing keys.

In case a backend has issues with this header parameter, the following system property can be used to disable the automatic thumbprint header parameter generation: ch.nevis.auth.jwttoken.x5t.disabled=true We recommend not to use this property, especially for long-term setups and rather invest in getting the affected backend to behave according to the JWT specifications.

Description

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.jwt.JWTToken
LoggingJWT
Auditingnone
Markernone
Methodsauthenticate, stepup, unlock

Properties

  • token.type (string, "JWS")`

    Type of JWT token. Has to be either "JWS" (JSON Web Signature) or "JWE" (JSON Web Encryption).

  • token.identifier (string, "out.JWTToken")

    Name of JWT token in outargs.

  • token.header.includeType (boolean, "false")

    Flag that specifies whether the header type "JWT" is included or not. I.e., if set to "true" the JWT token header property: "typ": "JWT" will be included.

  • token.algorithm (string, "HS256")

    Algorithm to generate the encryption or signing key (included in the JWT header as "alg" parameter).

    All required and recommended algorithms are supported. See the table below for a complete listing.

IdentifierDescriptionSymmetry
JWS algorithms
HS256HMAC using SHA-256 hash algorithmSymmetric
HS384HMAC using SHA-384 hash algorithmSymmetric
HS512HMAC using SHA-512 hash algorithmSymmetric
RS256RSASSA-PKCS-v1_5 using SHA-256 hash algorithmAsymmetric
RS384RSASSA-PKCS-v1_5 using SHA-384 hash algorithmAsymmetric
RS512RSASSA-PKCS-v1_5 using SHA-512 hash algorithmAsymmetric
JWE algorithm
RSA1_5RSAES-PKCS1-V1_5Asymmetric
RSA-OAEPRSAES using Optimal Asymmetric Encryption Padding (OAEP)Asymmetric
RSA-OAEP-256RSAES using Optimal Asymmetric Encryption Padding (OAEP) with the SHA-256 hash function and the MGF1 with SHA-256 mask generation functionAsymmetric
  • token.encryptionMethod (string, "A256GCM")

    Algorithm for encryption of the plain-text JWT payload. This property is only relevant for JWE tokens and will be included in the JWE header as "enc" parameter.

    All required and recommended algorithms are supported. Refer to the table below for a complete listing.

IdentifierDescriptionSymmetry
A128CBC-HS256AES_128_CBC_HMAC_SHA_256 authenticated encryption using a 256 bit keySymmetric
A256CBC-HS512AES_256_CBC_HMAC_SHA_512 authenticated encryption using a 512 bit keySymmetric
A128GCMAES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 128 bit keySymmetric
A256GCMAES in Galois/Counter Mode (GCM) (NIST.800-38D) using a 256 bit keySymmetric
  • token.kid (string, -)

    Optional key ID header parameter, which is a hint indicating the key used to secure the JWS. The parameter allows originators to explicitly signal a change of key to recipients.

  • keystoreref (string, "DefaultKeyStore")

    Create a keystore with the required key material and configure these properties accordingly to encrypt the JWE using the public key of the receiver or sign the JWS using the private key of nevisAuth.

    Required if an asymmetric algorithm (e.g., RS256) is used.

  • keyobjectref (string, "DefaultSigner")

  • keycurve (string, -)

    The curve's name of EC (Elliptic Curve) key. This is only used in case the private key is not extractable from HSM.

    Possible values: P-256, secp256k1, P-384, P-521, Ed25519, Ed448, X25519, X448.

  • token.key (String, -)

    Shared secret for symmetric algorithms.

    Required if a symmetric algorithm (e.g., HS256) is used.

  • out.issuer (string, "nevis")

    Value of "iss" claim.

  • out.subject (string, "${request:userId}")

    Include ID of authenticated user as "sub" claim.

  • out.audience (string, -)

    An arbitrary string which will be included as "aud" claim. Back-end applications may check if they belong to this audience.

    You can use JSON syntax to specify multiple values. Examples:

    <property name="out.audience" value="value1,value2"/>

    Generates a single value ("value1,value2") for "aud".

    <property name="out.audience" value="[&quot;value1&quot;, &quot;value2&quot;]"/>

    Generates two values ("value1" and "value2") for "aud".

  • out.include.jwtId (boolean, "false")

    Add JWT ID to claim set.

  • out.include.not_before (boolean, "true")

    Defines whether the "nbf" (not before) claim is included in the JWT token.

    The nbf claim identifies the time before which the JWT token must not be accepted for processing.

  • out.valid_before (seconds, 10)

    Number of seconds this JWT token should be valid before the issue time

  • out.include.issued_at (boolean, "true")

    Defines whether the "iat" (issued at) claim is included in the JWT token.

    The iat claim identifies the time at which the JWT token was issued.

  • out.time_to_live (seconds, 7200)

    Defines the number of seconds (since issuing time) that the JWT token should be valid. This attribute defines the "exp" claim in the JWT token.

    If you want to generate a token with no expiration time (that is, with no "exp" claim defined), set "none" as the value of the out.time_to_live attribute.

    You can use regular expressions to define the time to live. Examples:

    The issued tokens will expire on 1st January 2020
    <property name="out.time_to_live" value="#{Math.round((nowJoda.withYear(2020).withMonthOfYear(1).withDayOfMonth(1).withTimeAtStartOfDay().getMillis() - nowJoda.getMillis()) / 1000)}"/>
    The issued tokens have no expiration date
    <property name="out.time_to_live" value="none"/>
  • out.custom.* (string, -)

    Use to add a custom JWT claim (e.g., e-mail address of the user)

    You can use JSON syntax to specify arrays and JSON values.

    Examples:

    Generate a single value ('value1,value2') for 'myattr'
    <property name="out.custom.myattr" value="value1,value2"/>
    Generate a single value ('null') for 'myattr'
    <property name="out.custom.myattr" value="null"/>
    Generate an array with three values (1, 'value2' and null) for 'myattr'
    <property name="out.custom.myattr" value="[1,&quot;value2&quot;,null]"/>
    Generates a JSON object with one attribute named 'attr1' with a value ('value1') for 'myattr'
    <property name="out.custom.myattr" value="{&quot;attr1,&quot;:&quot;value1&quot;}"/>

Input

none

Transitions

  • ok

    A transition to the next state is expected)

Output

See property token.identifier

Errors

none

Notes

none

Example

<AuthState name="JWTToken" class="ch.nevis.esauth.auth.states.jwt.JWTToken" final="false">
<ResultCond name="ok" next="AuthDone"/>
<Response value="AUTH_ERROR"/>
<property name="out.audience" value="https://www.adnovum.ch"/>
<property name="out.issuer" value="https://my.nevis.server"/>
<property name="token.key" value="mustFulfillMinimalSizeDependingOnAlgorithmright"/>
</AuthState>