Example config for JWT feature (MSSEC02)

[lauracowen]

Include examples of how to obtain JWT tokens from the generation endpoint (find good examples that demonstrate what's described in this KC topic: https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_sec_obtain_jwt.html and from here https://github.com/OpenLiberty/guide-microprofile-jwt/blob/master/finish/frontendUI/src/main/liberty/config/server.xml).

See also #571 (might be there needs to be some duplication of this config also in the MP JWT feature? not sure how to handle this yet)

[lauracowen]

Sorry, I've just put a bunch of feedback in this issue but it actually applies to #571 feature. Now moved across to the other feature.

I don't see any examples in this particular page on the draft website so I don't think this should be in the SME Review column?

I wonder whether the example should be about using jwtBuilder in this topic (eg https://openliberty.io/blog/2019/08/29/securing-microservices-social-login-jwt.html)? Have a chat with Bruce about whether that makes sense and whether there's anything else commonly used in the JWT feature (as opposed to the MP JWT feature). Bear in mind that, strategically, we want to encourage users to use the MP JWT feature primarily (which auto pulls in the JWT feature).

[ManasiGandhi]

Bruce's edit suggestions from the Slack conversation
"You might say “this feature allows the runtime to create and consume JWT tokens.”
It would be worth mentioning, maybe as an additional last bullet, that “JWT builders and consumers can also be constructed programatically. Within a liberty installation, the api documentation can be found at /dev/api/ibm/javadoc/com.ibm.websphere.appserver.api.jwt_1.1-javadoc.zip”."

[brutif]

latest rev looks good to me

[ManasiGandhi]

@lauracowen Can you review the draft for JWT https://draft-openlibertyio.mybluemix.net/docs/ref/feature/#jwt-1.0.html ?

[lauracowen]

This topic needs to actually present an example configuration, not just tell someone how to do it. See this guidance on writing these kind of topics.

I think there's probably only a single example needed here, so start by taking the jwtBuilder line from the example server.xml in this blog post (see the server.xml config for "The oidc_client server configuration" and the keyStore line and present them as a code snippet in the Examples section.

Take some a few minutes to read that blog post to get a bit of background about the point of this before trying to explain the example (you don't need this info in this topic but I just want to try to give you some background about what you're describing). The post talks about how you can have two services. The user authenticates in the first service using, say, Google login. That service also creates a JSON Web Token (JWT) with the authentication details. The reason for this is that the user requests information from that first service (eg in a web browser) but the info is held by the second service. The first service therefore has to send a request to the second service for that info. However, the second service is secured and can't just give out its information willy-nilly to anyone that asks for it. Therefore, the first service passes a JWT to the second service that contains data to reassure the second service that the user who made the original request is authenticated and has permission to see the information that will be returned by the second service. Basically, the JWT is a way of authenticating access to the second service on the user's behalf. There's a bit of back-and-forth technically but, as long as the user has the right permissions, the second service will then return the information requested to the first service, who displays it to the user. And everyone's happy.

So, this feature (jwt), is used by the first service to create (or 'build') the JSON Web Token with the user's authentication details in it that will be passed to the second service with the information request. That's what the jwtBuilder line in the server config does.

So you need some of the info that's currently in the topic but in a different order:

• Remove the "The jwt-1.0 feature..." sentence completely. It's unnecessary because there's a similar (possibly more accurate sentence) generated at the top of the page.
• Then provide a lead-in to the example like "The following example shows how to configure the server to construct a JWT token for the application:"
• Then after the example, briefly explain what the attribute values are showing in the jwtBuilder element (I don't think you need to explain the keyStore ones here - I only suggested including that line in the example as well because the jwtBuilder element seems to refer to the default keystore).
• Then in a new paragraph (not as bullet points), explain the point about the configId thing - I assume it's meant to show how to use this configuration in the your application's Java code? If so, can you get an example of actual code to present instead of just an explanation? If it's not, make clear why and when you would go to that URL. Talk to @brutif about this as it doesn't make much sense at the moment.
• Then have a final paragraph for the info in the final bullet: "JWT builders and consumers....". But fix up the capitalisation of Liberty. This just acknowledges that you don't need to configure the JWT builder in the server.xml at all(? check this assertion with Bruce) but can just build the token programmatically.

@dmuelle has written some authentication/authorization topics so can you discuss this with him if my explanation above isn't totally clear? (JWT is complicated. It is worth having a basic understanding though to be able to write about it. But if it's still clear as mud, it's worth discussing how to approach it with David.)

Also, please can you briefly record in this issue answers from Bruce to the questions above so we can refer back to them easily if we need to.

Thanks

[chirp1]

Hi Manasi, I don't seem to see a comment from Laura that she is OK with your updates. Has she reviewed your latest changes? Would you have Laura OK your work before you put it in my column? I also don't seem to see a peer edit. Would you have one of the other OL writers peer edit your topic and have them post their comments in this issue? Incorporate their edits. Also, run Axrolinx. You have at least one item to fix. If you haven't gone through the cheat sheet, go through it and fix any issues that you find. After you complete those items, then put this issue back in my column. Thanks!

[ManasiGandhi]

@dmuelle Can you peer review this draft https://draft-openlibertyio.mybluemix.net/docs/ref/feature/#jwt-1.0.html?

[dmuelle]

Peer review

It might be helpful to explain, in a sentence or two, that the JWT builder is the config element that specifies the configuration details of JWT before you introduce the example.

This ID element is used to identify the JWT builder. The issuer element is a case-sensitive URL using the HTTP or HTTPS scheme, and the expiry element indicates the token expiration time in hours.

• Specify that "this ID element" refers to jwtBuilder. There is also an ID on the keystore in the example.
• I think these are "attributes" rather than "elements". I think jwtBuilder is the element and the others are attributes on that element. But confirm this as I'm not 100% certain.
• change using the HTTP to that uses the HTTP to avoid ambiguous "using"
• The description refers to the expiry element which specifies in hours, but the example uses expiresInSeconds, which is fundamentally the same thing but in seconds. Either change the description or the example so they match.

To obtain JWT from the JWT generation endpoint in the jwt-1.0 feature,

• should it be To obtain a JWT or To obtain JWTs ?
• Might be helpful to explain that this is how users/services obtain a JWT after you configure the jwtBuilder. You've switched gears here from talking about how to build JWT to how to obtain them so a brief transitional phrase might be helpful

Use the <configId> ID to refer to a corresponding JWTBuilder entry in the server.xml file. Specify token attributes, such as issuer and expiration time, in the JWTBuilder entry.

• I found this a little confusing since it's not in shown in an example. Where does one use <configId> ? Who is using it? Is this to obtain JWTs from the builder? The second sentence seems to repeat what you've already covered in the example description.

For JWT builder configuration attributes, see JWT Builder.

I think this should go directly after the example description, as it has more to do with building than obtaining JWT. I think the whole example would be clearer if the info about building and the info about obtaining were more clearly delineated.

Configure the JWTBuilder in the server.xml file if another feature is using it.

It's not clear what using it refers to here. I think "using it" means- something like "if an application or feature needs to obtain JWTs" but I'm not sure. What does "another feature" mean in this context? Does it mean a feature that relies on jwt-1.0 to provide JWT?

[ManasiGandhi]

@dmuelle I addressed your edit suggestions

This ID element is used to identify the JWT builder. The issuer element is a case-sensitive URL using the HTTP or HTTPS scheme, and the expiry element indicates the token expiration time in hours.

• [x ] Specify that "this ID element" refers to jwtBuilder. There is also an ID on the keystore in the example.

• [ x] I think these are "attributes" rather than "elements". I think jwtBuilder is the element and the others are attributes on that element. But confirm this as I'm not 100% certain.

• [ x] change using the HTTP to that uses the HTTP to avoid ambiguous "using"

• [ x] The description refers to the expiry element which specifies in hours, but the example uses expiresInSeconds, which is fundamentally the same thing but in seconds. Either change the description or the example so they match.

To obtain JWT from the JWT generation endpoint in the jwt-1.0 feature,

• [ x] should it be To obtain a JWT or To obtain JWTs ?

• Might be helpful to explain that this is how users/services obtain a JWT after you configure the jwtBuilder. You've switched gears here from talking about how to build JWT to how to obtain them so a brief transitional phrase might be helpful

• Use the ID to refer to a corresponding JWTBuilder entry in the server.xml file. Specify token attributes, such as issuer and expiration time, in the JWTBuilder entry.

• [ x] I found this a little confusing since it's not in shown in an example. Where does one use ? Who is using it? Is this to obtain JWTs from the builder? The second sentence seems to repeat what you've already covered in the example description.

For JWT builder configuration attributes, see JWT Builder.

• I think this should go directly after the example description, as it has more to do with building than obtaining JWT. I think the whole example would be clearer if the info about building and the info about obtaining were more clearly delineated.

• Configure the JWTBuilder in the server.xml file if another feature is using it.

• [ x] It's not clear what using it refers to here. I think "using it" means- something like "if an application or feature needs to obtain JWTs" but I'm not sure. What does "another feature" mean in this context? Does it mean a feature that relies on jwt-1.0 to provide JWT?

[ManasiGandhi]

@lauracowen can you review this draft https://draft-openlibertyio.mybluemix.net/docs/ref/feature/#jwt-1.0.html ?

[lauracowen]

• Thanks for adding the explanation of the example. Can you tweak the sentences slightly so that the text describes the actual example's values rather than just abstractly providing reference information? For example, "The issuer attribute shows the URL that xxxxx (what is the URL referring to here?)." (the exact details about what a valid value are isn't relevant here - that info can be found by clicking the jwtBuilder link in the list in the Feature configuration elements section later in the topic). You're not trying to instruct on how to do the config here; you're simply providing good, useful examples and describing them so that the reader can understand what they show (and then decide whether they're useful to them or not). Similarly "The ID attribute for the jwtBuilder element is used to identify the JWT builder." could be more informative: what does the element in this particular example identify about the JWT builder? eg that it expires in 600 seconds so that it can't be spoofed (I'm guessing at that explanation, you'll need to check it!) and it uses the default key alias to xxxx.
• Every instance that refers to the jwtBuilder element by name (not the first instance in the Examples section which I think is instead referring to the concept, so that's fine) needs to be spelt and capitalised exactly the way it's shown in the example and in the list in the Feature configuration elements section.
• The last paragraph says "JWTBuilder can be used programmatically." - I may be wrong but I think that's the primary way it would be used. Can you get a piece of Java code to provide as an example here of generating a JWT using jwtBuilder? The blog post by Bruce might be some help if you can find someone to help identify the relevant bit of code: https://openliberty.io/blog/2019/08/29/securing-microservices-social-login-jwt.html This Examples section needs to contain examples of the things being described instead of just describing them or instructing the reader. The reader needs to be able to grab a copy of the config/code and then adjust it for their own use; not have to construct it from scratch.
• Don't link to the API doc in a zip file. We're currently looking at how we can get the API doc hosted properly in the OL docs so it can have a proper link then.

[ManasiGandhi]

@lauracowen I made changes per your suggestions and also discussed with Bruce.

• Thanks for adding the explanation of the example. Can you tweak the sentences slightly so that the text describes the actual example's values rather than just abstractly providing reference information? For example, "The issuer attribute shows the URL that xxxxx (what is the URL referring to here?)." (the exact details about what a valid value are isn't relevant here - that info can be found by clicking the jwtBuilder link in the list in the Feature configuration elements section later in the topic). You're not trying to instruct on how to do the config here; you're simply providing good, useful examples and describing them so that the reader can understand what they show (and then decide whether they're useful to them or not). Similarly "The ID attribute for the jwtBuilder element is used to identify the JWT builder." could be more informative: what does the element in this particular example identify about the JWT builder? eg that it expires in 600 seconds so that it can't be spoofed (I'm guessing at that explanation, you'll need to check it!) and it uses the default key alias to xxxx.

• Every instance that refers to the jwtBuilder element by name (not the first instance in the Examples section which I think is instead referring to the concept, so that's fine) needs to be spelt and capitalised exactly the way it's shown in the example and in the list in the Feature configuration elements section.

• The last paragraph says "JWTBuilder can be used programmatically." - I may be wrong but I think that's the primary way it would be used. Can you get a piece of Java code to provide as an example here of generating a JWT using jwtBuilder? The blog post by Bruce might be some help if you can find someone to help identify the relevant bit of code: https://openliberty.io/blog/2019/08/29/securing-microservices-social-login-jwt.html This Examples section needs to contain examples of the things being described instead of just describing them or instructing the reader. The reader needs to be able to grab a copy of the config/code and then adjust it for their own use; not have to construct it from scratch.

• Don't link to the API doc in a zip file. We're currently looking at how we can get the API doc hosted properly in the OL docs so it can have a proper link then.

[lauracowen]

Thanks, looks lots better.

Last thing now...

• The description beneath the example shouldn't be providing generic "reference doc" about what the elements are (you can get that from clicking the links in the sections lower down the page). Instead, describe more directly what's happening in the example. eg "The jwtBuilder, named myBuilder, uses the default key alias to locate the private key...etc. The JWT is issued by http://example.com and the token expires after 600 seconds."

[ManasiGandhi]

@lauracowen I made those edits. I'm not sure why they are not showing. Will check.

[lauracowen]

Okay, thanks. I'm going to sign it off because it contains the info it needs.

However, can you take a look at the paragraph before sending for editorial review with @chirp1:

• The "issuer" sentence is missing some words so it doesn't quite read grammatically.
• The last sentence repeats the same information as the first sentence. Maybe discuss with Karen which is best to use. I personally prefer it if we don't list off every attribute by name as it makes it a bit unwieldy to read (as in the first sentence), but it might need to be a little more explicit than the last sentence (just make sure it's readable and not really dry (which listing off every attribute by name can be).

[ManasiGandhi]

@chirp1 updated draft link https://draft-openlibertyio.mybluemix.net/docs/20.0.0.9/reference/feature/jwt-1.0.html

[ManasiGandhi]

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

[ManasiGandhi]

@chirp1 New edits and updates

• Removed the sentence "The JWT builder is used for the creation of JWTs." as it didn't provide any context.

• Changed the sentence "The ID attribute for the jwtBuilder element named myBuilder is used to identify the JWT builder, and uses the default keyAlias attribute to locate the private key." to, "The ID attribute for the jwtBuilder element named myBuilder identifies the JWT builder, and uses the default keyAlias attribute to locate the private key." for conciseness.

"A concise, powerful verb more clearly conveys your intended meaning and promotes a more active style. "
https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch06.html

• Changed "The issuer attribute in the example is the URL http://example.com, which identifies who issued the JWT.", to, "The issuer attribute in the example is the URL http://example.com that identifies who issued the JSON Web Token."
  Chapter 6 Clarity
  "That and which

Relative pronouns introduce relative clauses, which can be restrictive or nonrestrictive. Nonrestrictive clauses, or nonessential clauses, can be dropped from a sentence without changing the meaning. However, restrictive clauses, or essential clauses, can’t be dropped from the sentence because they add information that’s necessary for users to understand the intended meaning.

Use that with restrictive clauses and which (plus commas) with nonrestrictive clauses."
https://learning.oreilly.com/library/view/developing-quality-technical/9780133119046/ch06.html

[ManasiGandhi]

@chirp1 Updated link to the draft https://draft-openlibertyio.mybluemix.net/docs/20.0.0.11/reference/feature/jwt-1.0.html.

[ManasiGandhi]

@chirp1 20.12 updated link https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/reference/feature/jwt-1.0.html.

[chirp1]

Note: My editorial comments and Manasi's fixes to them are in this issue: #571 as Manasi inadvertanly the link to the JWT feature in the 571 issue instead of giving the link to the MP JWT feature.

[chirp1]

Hi Manasi,

• I think you have a tagging issue. The text from "The id attribute for the jwtBuilder element named... is in a gray box. This gray box seems to contain the updated text that you want to keep. And the text immediately above the gray box is the text that you want to remove.

[ManasiGandhi]

@chirp1 I fixed the the tagging and moved the issue back to the editorial review. https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/reference/feature/jwt-1.0.html

[chirp1]

Hi Manasi, the updates look good. I'm moving this issue to Ready to Publish.

[dmuelle]

Topic is published: https://www.openliberty.io/docs/latest/reference/feature/jwt-1.0.html

Closing this issue