Skip to main content
Version: 4.32.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.

Description

The following table describes the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.jwt.JWTToken
LoggingJWT
Auditingnone
Properties (format)token.type (string, "JWS")Type of JWT token. Has to be either "JWS" (JSON Web Signature) or "JWE" (JSON Web Encryption).
Properties (output)token.identifier (string, "out.JWTToken")Name of JWT token in outargs.
Properties (header)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.
Properties (encryption and signing)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
TopicDescription
Properties (encryption and signing)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
TopicDescription
Properties (encryption and signing)keystoreref (string, "DefaultKeyStore") keyobjectref (string, "DefaultSigner")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.
token.key (String, -)Shared secret for symmetric algorithms.Required if a symmetric algorithm (e.g., HS256) is used.
Properties (claims)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:In the following example, 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)}"/> In this example, 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: <property name="out.custom.myattr" value="value1,value2"/> Generates a single value ("value1,value2") for "myattr". <property name="out.custom.myattr" value="null"/> Generates a single value ("null") for "myattr". <property name="out.custom.myattr" value=1,&quot;value2&quot;,null/> Generates an array with three values (1, "value2" and null) for "myattr". <property name="out.custom.myattr" value="{&quot;attr1,&quot;:&quot;value1&quot;}"/> Generates a JSON object with one attribute named "attr1" with a value ("value1") for "myattr".
Methodsauthenticatestepupunlock
Inputnone
Transitionsok (a transition to the next state is expected)
Outputsee property token.identifier
Errorsnone
Notesnone

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>