Documentation for MicroProfile JWT 2.1

[teddyjtorres]

Documentation for MicroProfile JWT 2.1 Epic https://github.com/OpenLiberty/open-liberty/issues/20081.

For the https://openliberty.io/docs/latest/microprofile-config-properties.html#jwt table, please add the following properties (Please sort accordingly):

Name	Description	When the runtime reads the property	Example
mp.jwt.verify.token.age	Specifies the number of seconds since the JWT token was issued. The "iat" claim must be present in the JWT and the configured number of seconds since "iat" must not have elapsed. If it has elapsed, then the request is rejected with an Unauthorized (401) response. This property is available in MicroProfile JSON Web Token 2.1 and later.	On each request to a protected resource.	mp.jwt.verify.token.age=3600
mp.jwt.verify.clock.skew	Specifies the clock skew in seconds used during the token expiry and age verification. The default value is 0 seconds. In order to use this new property, please set a negative value for the clockSkew attribute of the mpJwt element since the mpJwt element already has a default value of 5 minutes for the clockSkew attribute. This property is available in MicroProfile JSON Web Token 2.1 and later.	On each request to a protected resource.	mp.jwt.verify.clock.skew=60
mp.jwt.decrypt.key.algorithm	Specifies the Key Management Algorithm for decrypting the Content Encryption Key (CEK) when receiving JWE tokens. There is no default value. The "alg" header parameter must be present in the JWE and must be the same value as the mp.jwt.decrypt.key.algorithm property. If it is not the same value, then the request is rejected with an Unauthorized (401) response. This property is available in MicroProfile JSON Web Token 2.1 and later.	On each request to a protected resource.	mp.jwt.decrypt.key.algorithm=RSA-OAEP

[ramkumar-k-9286]

Hi Teddy @teddyjtorres

The properties have been added to the MicroProfile JWT table.

The Draft file with the changes: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/microprofile-config-properties.html#jwt

If you are happy with the changes, please add the Developer Reviewed label to this issue.

if any changes are needed, please add a comment to the issue.

Regards, Ramkumar

CC @dmuelle

[dmuelle]

Peer review

Hi Ram- please run Acrolinx on the new description fields and fix any relevant flags

[ramkumar-k-9286]

Hi David @dmuelle

Ran Acrolinx on the newly added properties in the MicroProfile JWT table. Made a couple of changes based on Acrolinx suggestions.

The Draft file: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/microprofile-config-properties.html#jwt

Regards, Ramkumar

[dmuelle]

@ramkumar-k-9286 - changes look good to me. However, I think the description for mp.jwt.verify.clock.skew needs clarification

Specifies the clock skew in seconds used during the token expiry and age verification. The default value is 0 seconds. The mpJwt element already has a default value of 5 minutes for the clockSkew attribute. To use this new property, set a negative value for the clockSkew attribute of the mpJwt element....

This is confusing- what is the relationship between the clockSkew config attribute and this property? It says to set a negative value for the attribute, which has a default of 5 min- does that mean you need to set <mpJwt clockSkew= -5m../> in order to get an accurate value for this property? We should make this more clear for users, especially since it is Liberty-specific config needed to enable an MP property. Check with @teddyjtorres to clarify

[ramkumar-k-9286]

Slack Response

Teddy Torres 7:36 PM Hi Ramkumar. The clockSkew is an existing attribute of the mpJwt element and it has a default value of 5 minutes. The clockSkew now also overrides the new mp.jwt.verify.clock.skew property being introduced in 2.1. Since clockSkew already has a default value, it becomes impossible to use mp.jwt.verify.clock.skew if it cannot be disabled. Therefore, it was decided that to disable clockSkew, one can specify any negative value.

[ramkumar-k-9286]

Hi David @dmuelle

Made the suggested corrections.

The Draft file: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/microprofile-config-properties.html#jwt

Regards, Ramkumar

[dmuelle]

looks good- we shouldn't say "new" property because it wont be new for long. Also should make clear what to set where

Specifies the clock skew in seconds used during the token expiry and age verification. The default value is 0 seconds. The mpJwt element already has a default value of 5 minutes for the clockSkew attribute. To use this new property, set any negative value for the clockSkew attribute of the mpJwt element, for example . This property is available in MicroProfile JSON Web Token 2.1 and later. --->

Specifies the clock skew in seconds that is used during the token expiry and age verification. The default value is 0 seconds. The clockSkew attribute of the mpJwt element has a default value of 5 minutes, which you must disable or it overrides the value of the mp.jwt.verify.clock.skew property. To disable the default and use the property instead, set any negative value for the clockSkew attribute in your server.xml file, for example . This property is available in MicroProfile JSON Web Token 2.1 and later.

[ramkumar-k-9286]

Hi David @dmuelle

Made the suggested corrections for mp.jwt.verify.clock.skew property.

The Draft file: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/microprofile-config-properties.html#jwt

Regards, Ramkumar

[dmuelle]

looks good- 1 very minor change. I think we should remove the XML brackets from the mpJwt example as we normally don't include these in code excerpts in text.

\

--->

mpJwt clockSkew= -1

[ramkumar-k-9286]

Hi David @dmuelle

Made the suggested corrections for clockSkew attribute example <>.

The Draft file: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/microprofile-config-properties.html#jwt

Regards, Ramkumar

[dmuelle]

LGTM, thanks