Update and clarify JWT docs #6963
Conversation
Update 2_feature-issue-template.md
Update 2_feature-issue-template.md
|
|
||
| JWT builders will dynamically generate JWKs to use when the `jwkEnabled` attribute for the `jwtBuilder` element is set to `true`. A new key is generated when the JWT builder creates its first token, or when the JWK endpoint for the builder is invoked, whichever happens first. After creation, the key is rotated automatically every 12 hours. | ||
|
|
||
| Dynamically generated JWKs are useful for server administrators that do not want to be concerned with setting up a keystore and signing key for the JWT builder. Server admins need only set the `jwkEnabled` attribute to `true`, and Liberty will handle creation and maintenance of the key. Note that when `jwkEnabled` is set to `true`, the `keyStoreRef` and `keyAlias` attributes will be ignored. |
There was a problem hiding this comment.
| Dynamically generated JWKs are useful for server administrators that do not want to be concerned with setting up a keystore and signing key for the JWT builder. Server admins need only set the `jwkEnabled` attribute to `true`, and Liberty will handle creation and maintenance of the key. Note that when `jwkEnabled` is set to `true`, the `keyStoreRef` and `keyAlias` attributes will be ignored. | |
| Dynamically generated JWKs are useful for server administrators that do not want to be concerned with setting up a keystore and signing key for the JWT builder. Server administrators only need to set the `jwkEnabled` attribute to `true`, and Liberty will handle creation and maintenance of the key. Note that when `jwkEnabled` is set to `true`, the `keyStoreRef` and `keyAlias` attributes will be ignored. |
|
|
||
| JWT consumers can retrieve JSON Web Key Set (JWKS) documents to reconstruct public keys to use for verifying token signatures. JWKS documents are particularly useful for JWT consumers that receive tokens from issuers that frequently rotate their signing keys, and for server administrators who do not want to manually maintain a keystore. | ||
|
|
||
| The `jwkEnabled` attribute in the `jwtConsumer` element must be set to `true`, and the `jwkEndpointUrl` attribute must be set to a URI that provides the JWKS document containing the public keys to use to verify the signatures of tokens received by this JWT consumer. |
There was a problem hiding this comment.
| The `jwkEnabled` attribute in the `jwtConsumer` element must be set to `true`, and the `jwkEndpointUrl` attribute must be set to a URI that provides the JWKS document containing the public keys to use to verify the signatures of tokens received by this JWT consumer. | |
| The `jwkEnabled` attribute in the `jwtConsumer` element must be set to `true`, and the `jwkEndpointUrl` attribute must be set to a URI that provides the JWKS document containing the public keys to use to verify the signatures of the tokens received by this JWT consumer. |
|
opened #6964 to track on docs side |
There was a problem hiding this comment.
Ho @ayoho - thanks for opening this. Some general comments before I review/edit
The Examples sections on the feature pages are intended to be for concise configuration examples that demonstrate common tasks. The info in this PR seems more like conceptual information to support JWT Builder. Is it possible to revise this information to be focused on config examples that demonstrate the main ideas? It might also make the sections more concise if we show rather than tell the config details, and just provide context in the example descriptions.
Also, the OL website does not really recognize h4 or h5 headings. But if the info was broken up into examples, we could just use h3 for each example.
I'm happy to help revise the info you have here. If the information is better presented as conceptual topic, we can create a new topic and link it form this page. Let me know what you think. Thanks!
|
Hi, @dmuelle. I'd agree that the content is primarily conceptual. Perhaps revamping the https://openliberty.io/docs/latest/single-sign-on.html#_json_web_token_jwt section and maybe even having a standalone page under the Security section for JSON Web Tokens would be a better place to have this information. I can create a new |
|
that's all you need to do- BUT - when you update the nav, make that change in the |
|
@dmuelle I moved all my new content into a separate json-web-token.adoc page. I'll open a separate PR for the nav changes. |
|
I'm merging this to draft and will review further and make edits for IBM style etc in a new PR |
Add some sections on JWK usage in the JWT builder and consumer doc.
For OpenLiberty/open-liberty#26453