Example config for JWT SSO feature

[Charlotte-Holt]

Determine whether there are any commonly used config examples that should go in the JWT SSO feature generated doc. Include the example from #1880. Also see #636 and #571 for related feature examples.

[ManasiGandhi]

link to the draft https://draft-openlibertyio.mybluemix.net/docs/20.0.0.10/reference/feature/jwtSso-1.0.html

[teddyjtorres]

Thank you Manasi. The changes look good. If there is time for more changes:

In the disabling JWT section, "You can disable JWT SSO to avoid a default authentication with the JWT cookie." needs to be clarified since Tthe JWT cookie is still accepted, but will not be generated.

It could be rephrased as "You can enable JWT SSO to accept authentication with an existing JWT cookie without generating it. The following example shows how to disable creating JWT cookies."

Also, the sentence "The disableJwtCookie attribute is set to true for the id attribute sample." could be removed.

[ManasiGandhi]

@teddyjtorres I updated the draft with your suggestions. You can view it here https://draft-openlibertyio.mybluemix.net/docs/20.0.0.10/reference/feature/jwtSso-1.0.html

[teddyjtorres]

Thank you for the updates. They look good.

[lauracowen]

Thanks Manasi. Nice job. I just have a couple of questions to clarify some slight ambiguities in the wording that could be interpreted in slightly different ways. But otherwise a neat job.

• Can you end the lead-in sentence to the example with a colon.
• myBuilder (under first example) should be in monospace.
• "... is used to identify the JWT builder." - I think this would be clearer as "is the name of the jwtBuilder." or even "...is the name of the token."? Can you check with Teddy that that's an accurate interpretation? If not, can you make it clearer where this value of id comes from?
• Could you change the wording of the last sentence under the first example slightly to "indicates that the token expiration time is changed to 1800 seconds" - according to the intro of the first example, the point of setting the number of seconds is to change the expiration time of the existing token, rather than to set the expiration time of a new token. I think (can you check with Teddy)?

[ManasiGandhi]

@lauracowen I worked on your suggestions. Couldn't talk to Teddy as he is on a vaction until 14th. Will update the changes once I confirm them with him.

[teddyjtorres]

Hi,

"... is used to identify the JWT builder." is accurate. This is consistent with the description for "id" in https://www.ibm.com/support/knowledgecenter/en/SSAW57_liberty/com.ibm.websphere.liberty.autogen.nd.doc/ae/rwlp_config_jwtBuilder.html.

When the expiresInSeconds is set, it applies to any new token that is created after the modification. Old tokens will not be modified. Therefore, please reword this sentence,

"The expiresInSeconds attribute indicates the token expiration time is changed to 1800 seconds."

to something like,

"The expiresInSeconds attribute indicates the token expiration time is set to 1800 seconds for a newly generated token."

Thank you for the updates.

[lauracowen]

@teddyjtorres Thanks for your answers. About the id value, my question was more about whether the value of the id was being set/defined for the token here or was a reference to an id set elsewhere - I think I found that I could read the sentence either way and wanted to be clear where the id value comes from in the first place. I think it's the former (ie the token is being defined here)?

[teddyjtorres]

Hi Laura. No problem. The id refers to the builder itself and it is not used for the tokens.

Hi Manasi. Thank you for the changes.

[ManasiGandhi]

Updated draft link https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/reference/feature/jwtSso-1.0.html

[lauracowen]

Great, thank you. Signing off.

[dmuelle]

published at https://openliberty.io/docs/20.0.0.11/reference/feature/jwtSso-1.0.html

[chirp1]

Hi Manasi, I don't seem to see an peerl review for the topic. Also, I don't see references to at least instances where you looked up what you are doing in the IBM quality guide. Also, do a another look up in the quality guide for clarity and concreteness. Post that you looked those things up to this issue.

[Charlotte-Holt]

@ManasiGandhi Looking good. Peer review feedback:

• In "The following example shows how you can configure the JWT SSO to change the token expiration time:", I'd remove "the" before "JWT SSO"
• Suggested update for the first example explanation:

The id attribute of the jwtBuilder element identifies the JWT builder, which is myBuilder in this example. The jwtBuilderRef attribute refers to the myBuilder JWT builder. The expiresInSeconds attribute indicates that the token expiration time is set to 1,800 seconds for a newly generated token.

• I'd change "Disabling JWT cookies" to just "Disable JWT cookies"
• I think I'd look at the similar example in the SPNEGO feature and try to make it more parallel to this one for consistency (Karen's reviewed the SPNEGO feature). Here's the blog post: https://openliberty.io/blog/2020/07/02/disable-default-cookies-20007.html#JWT-cookie. Something like
• Think about changing "Configuring JWT SSO to change the token expiration time" to just "Change the token expiration time"

By default, when a client is authenticated with Open Liberty through the JWT SSO feature, a JWT cookie is created and sent to the HTTP servlet. The following example disables JWT cookies by specifying the disableJwtCookie attribute with a value of true in the server.xml file:
In this example configuration, JWT cookies are disabled, so a mechanism other than JWT cookies can be used for authentication.

It might need to go back to technical review really quick to make sure that this info is accurate.

[ManasiGandhi]

@Charlotte-Holt Thanks for reviewing. I worked on your peer review:

• In "The following example shows how you can configure the JWT SSO to change the token expiration time:", I'd remove "the" before "JWT SSO"

• Suggested update for the first example explanation:

  The id attribute of the jwtBuilder element identifies the JWT builder, which is myBuilder in this example. The jwtBuilderRef attribute refers to the myBuilder JWT builder. The expiresInSeconds attribute indicates that the token expiration time is set to 1,800 seconds for a newly generated token.

• I'd change "Disabling JWT cookies" to just "Disable JWT cookies"

• I think I'd look at the similar example in the SPNEGO feature and try to make it more parallel to this one for consistency (Karen's reviewed the SPNEGO feature). Here's the blog post: https://openliberty.io/blog/2020/07/02/disable-default-cookies-20007.html#JWT-cookie. Something like

• Think about changing "Configuring JWT SSO to change the token expiration time" to just "Change the token expiration time"

  By default, when a client is authenticated with Open Liberty through the JWT SSO feature, a JWT cookie is created and sent to the HTTP servlet. The following example disables JWT cookies by specifying the disableJwtCookie attribute with a value of true in the server.xml file:
  In this example configuration, JWT cookies are disabled, so a mechanism other than JWT cookies can be used for authentication.

[dmuelle]

https://openliberty.io/docs/latest/reference/feature/jwtSso-1.0.html

[dmuelle]

Edited content is on vNext and will publish with 23.0.0.9. Closing as completed.