Migrate Consuming JSON Web Tokens in Liberty to Open Liberty

[dmuelle]

migrate the topic Consuming JSON Web Tokens in Liberty to jwt feature page.

Include the updates specified in https://github.ibm.com/websphere/liberty-docs/issues/3200

[dmuelle]

Updates are available at:
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/jwt-1.0.html

[dmuelle]

Initial peer review

Construct JWT for an application

In the description for this example, the code attribute is listed as ID, but the attribute in the example is id. This is likely because acrolinx recommended using ID. In this case, that's not an accurate recommendation.

CHANGE

The ID attribute for the jwtBuilder element named myBuilder...
--->
The id attribute for the jwtBuilder element that is named myBuilder...

Configure the JWT consumer

The 1st example here is misleading, no element will exist unless the user adds one, but the default will apply regardless. Instead of showing an example that has no function, we can just describe the default behavior. Remove the example and make the following change.

CHANGE

When you add the jwt-1.0 feature and save your changes, Open Liberty adds the following default jwtConsumer element.
For information about jwtConsumer attributes that you can configure, see JWT consumer.

In this default configuration, the following values are assumed.

(bulleted list)

--->

When the JSON Web Token feature is enabled, Open Liberty creates a default configuration with the following values.

• The alg header of the consumed JWT is RS256. You can configure this value with the signatureAlgorithm attribute.

• A JWT is considered to be valid within 5 minutes of the exp, nbf, and iat claims it contains. You can configure this value with the clockSkew attribute.

You can reconfigure these defaults by specifying a jwtConsumer element with an id value of defaultJWTConsumer and configuring attribute values. You can also create one or more other jwtConsumer elements. Each jwtConsumer element must have a unique, URL-safe string specified as the id attribute value. If the id value is missing, the jwtConsumer is not processed. For more information about the available configuration attributes, see JWT consumer.

---

before the next example, need to fix bulleted list by adding a blank line preceding. Also, make this into an ordered list since these are two sequential steps. Text here looks good otherwise.

Verify and parse JWT tokens in your application

CHANGE

The following example shows how to programmatically verify and parse...
--->
The following examples show how to programmatically verify and parse...

[hiltoncv]

Thanks David! Comments have been incorporated.

[dmuelle]

Hi Hilton, this looks good. Just a few more suggestions

• avoid the gerund form of verbs when possible
  CHANGE

The following example shows how to configure the server for constructing a JSON Web Token (JWT) for an application.
--->
The following example shows how to configure the server to construct a JSON Web Token (JWT) for an application.

Configure the JWT consumer

Please compare your current draft with my previous suggestion. The first two sentences still need work. The feature should use the text name rather than the code name with version so that the content remains current when a new version is released. Also, the link to the config element is redundant at the top as you have added it in the following paragraph.

CHANGE

When you add the jwt-1.0 feature and save your changes, Open Liberty adds the jwtConsumer element.

For information about jwtConsumer attributes that you can configure, see JWT consumer.

--->

When the JSON Web Token feature is enabled, Open Liberty creates a default configuration with the following values.

[dmuelle]

Hi Hilton- one more change- the list of default settings is introduced twice, please remove the second redundant introduction.

When the JSON Web Token feature is enabled, Open Liberty creates a default configuration with the following values.

In this default configuration, the following values are assumed.

[hiltoncv]

Incorporated comments.

[dmuelle]

Hi @teddyjtorres , can you review the doc for this issue, which migrates information about using the jwt-1.0 feature from WebSphere Liberty docs to Open Liberty docs. We have not made any substantial changes to this information, we just want to make sure it is still current and accurate. Thanks!

Open Liberty docs draft: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/jwt-1.0.html

WebSphere Liberty doc source for this information: Consuming JSON Web Tokens in Liberty

[teddyjtorres]

Thank you for this documentation. There are 2 minors changes suggested.

Please change,

<jwtBuilder expiresInSeconds="600" id="myBuilder" issuer="https://example.com" keyAlias="default"/>
--->
<jwtBuilder id="myBuilder" keyAlias="default" issuer="https://example.com" expiresInSeconds="600"/>

so that the attributes match the order in which they are explained in the paragraph.

Please change,

The expiry attribute indicates the token expiration time, which is 600 seconds.
--->
The expiresInSeconds attribute indicates the token expiration time, which is 600 seconds.

[hiltoncv]

@teddyjtorres Thanks for the review. I have incorporated your comments.