JWTs are handled by declaring a reference to a JwtTokenConfiguration-type object in the <jaxrs:server> element of the beans.xml file:
<jaxrs:server ...>
<jaxrs:properties>
<entry key="jwtTokenConfiguration">
<ref bean="jwtTokenConfiguration"/>
</entry>
</jaxrs:properties>
</jaxrs:server>
The JwtTokenConfiguration object displays different properties relating to using the token:
<bean id="jwtTokenConfiguration" class="com.hardis.adelia.webservice.JwtTokenConfiguration"> <!-- Authentication scheme ; ex : value ="JWT" ; Authorization: JWT Header.Payload.Signature --> <property name="jwtAuthScheme" value="JWT"/> <!-- Token validation URL pattern --> <property name="jwtBasePath" value="/ws/*"/> <!-- Enable confidential transport (default:false) --> <property name="jwtConfidential" value="false"/> <!-- Swagger URI resources listing authentication passthrough --> <property name="jwtSwaggerURI" value="/ws/swagger.json"/> <!-- TimeToLeave value (s) for iat token validity checking --> <property name="jwtTtl" value="3600"/> <!-- ClockOffset value (s) for iat or exp (adjustment) token validity checking --> <property name="jwtClockOffset" value="0"/> <!-- Users roles token claim name --> <property name="jwtUserRoleClaim" value="roles"/> <!-- Enable audience claim validation (default:false)--> <property name="jwtValidateAudience" value="false" /> <!-- Enable confidential transport (default:false) --> <property name="jwtConfidential" value="false"/> </bean>
Description of properties:
jwtAuthScheme |
Scheme used in the Authorization HTTP header to transmit the token. By default: JWT. The HTTP header used to transmit the token follows the following syntax: Authorization : <jwtAuthScheme> Token Example: Authorization : JWT eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJoYXJkaXMiLCJpc3MiOiJKV1RQcm92aWRlciIsImlhdCI6MTQ2MzQwMzk2NCwiYXVkIjoiaHR0cDovL2xvY2Fs aG9zdDo4MDgwL2pheHJzIiwianRpIjoiaWRUb2tlbl8xIiwicm9sZXMiOlsiYWRtaW4iLCJ1c2VyIl19.o-qhcj9X-G0np3zxeLt2BSfQxVSMxcCO4AUjSS21m72XD2fC MmQbJmnR86wT_lRIDkWxU0UowcDUOhEUYkmRhhMjN0vPsseWjgcXoj96vJ0X7cTxxpNSpjGmQtyez7IwL3iWkmUtNN-2OlHU4CSzUuj0JNnGfu3dMzC8vum_ E81cT8IJDKxKyTV_NDrQQ2GKx8wGAPC9ZxAi_qBD3UHuFvr70vNEQUVka5azCMMnpAXIoBuZk0oeTPLlTf4rYYCQ7WjsirzSylp8a47Xfgj_e6Qb-J01V9ohD5bgHvv B-fp63vT9dODPz_WKJO37_pdfvJALGIewzec0YU6iJUu5gQ |
jwtBasePath |
Url-pattern defining all the resources secured by the JWT. Resources with a URI starting with <ContextPath><jwtBasePath> are secured using the JWT. Example : If the ContextPath of the Web application is "/services" and the value of the jwtBasePath property is "/rest/*", all resources with a URL beginning with /services/rest/ are secured by the JWT. |
jwtUserRoleClaim |
Name of the claim containing the list of roles of the authenticated used. By default: roles. |
| jwtUserRoleJsonPath |
If the claim listing the roles takes the value of a Json document, then jwtUserRoleJsonPath allows you to define a JsonPath which specifies the field in the document to which the list of roles is attached. Note: the jwtUserRoleJsonPath is only useful when a Json object is assigned to the claim listing the roles. Example: Extract ( Jwt ) : ";header ";: { " alg ": "HS256", " typ ": "JWT" }, backend: { "; roles ";: [role1, role2,...] }, frontend: { "; roles ";: [role1, role2,...] } }, ... } Use the "frontend.roles" JsonPath to specify the list of roles to be used. Extract (beans.xml): ... <!-- Users roles JsonPath pattern --> <property name="jwtUserRoleClaim" value="roles"/> <property name="jwtUserRoleJsonPath" value="frontend.roles"/> ... |
jwtTtl |
Lifespan expressed in seconds. The token lifespan is calculated by adding this value to that of the predefined iat (Issued At) claim. If the current time exceeds the calculated time, the token is no longer valid. |
jwtClockOffset |
Offset expressed in seconds. Used to manage an offset in relation to the time defined by the token issuer. This offset enters into the time calculation and therefore the validity of the token for predefined iat (Issued At), exp (Expiry Time) and nbf (Not Before) claims. |
jwtValidateAudience |
Indicates whether the predefined aud claim must be validated. The validation type depends on the audience type defined by the jwtAudienceKind property. By default: false. |
| jwtAudienceKind | Validation type required when checking the aud claim. The possible values are:
|
jwtConfidential |
Used to reject (value= "true") a request without secure transport. By default: false. |
jwtSwaggerURI |
Dispensation for access to the swagger resource from the REST services list. These dispensations enable swagger-ui to access the REST services list without having to provide a JWT. The presence of the token (via the [api-key] field) is still required to invoke the listed services. Examples: <property name="jwtSwaggerURI" value="/ws/swagger.json"/> (Without the token, you can retrieve the swagger.json file, but you cannot access the swagger interface). <property name="jwtSwaggerURI" value="/ws/api-docs;/ws/swagger*"/> (You have full access to the swagger interface without having to provide a JWT). |
Notes:
- The predefined iat , exp , nbf claims are exclusive. The token issuer chooses the claim to handle time validity.
- iat [Issued At]: the token was issued at a specified time.
- exp [ExpiryTime]: the token expires at a specified time.
- nbf [Not Before]: the token is not valid before a specified time.
- The token issuer assigns the name of the authenticated client (user) in the predefined sub claim. Using the Adelia keyword *USER in a REST service program returns this value.
- The roles of the authenticated client (user) are listed in the claim whose name is specified using the jwtUserRoleClaim property. These roles are injected into the application's security context. Using the VaToolBxAwsIsUserInRole function in an Adelia REST service program makes it possible to find out whether the client is in a specific role or not.
Token's digital signature
To validate the token signature, the public encryption key must be accessible via a keystore in JKS called RSJwtSecurity.key.
This keystore must be available either in the application's WEB-INF/conf directory, or externalized in the form of a URL-type jndi resource using the com.hardis.adelia.common.URLFactory factory via the url/adelRSJwtSecurity alias .
Note: a keystore is provided by default in the /WEB-INF/conf directory.