JWT single sign-on config examples

[dmuelle]

per discussion around #3801 , convert steps 4 and 5 in the KC jwtSso topic to new config examples on the jwtSso-1.0 feature page. Review the KC page to ensure that no additional information needs to be transferred to OL doc

[ManasiGandhi]

@teddyjtorres I made updates to the jwtSso config example to include steps 4 and 5 in the KC jwtSso topic.

https://docs-draft-openlibertyio.mybluemix.net/docs/21.0.0.4/reference/feature/jwtSso-1.0.html

[teddyjtorres]

Thank you Manasi for the changes. They look good. There are a few things to update.

1. There seems to be a problem rendering the subtitle, there should be a space between these two,

"JWT SSO authentication. === Change JWT validation criteria"

2. Please move

<mpJwt id="myMpJwt" jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk" />

after the sentences

In the example, the JWk endpoint specifies the JWT builder with the ID myBuilder. To use the JWK endpoint for consuming JWTs, add the jwksUri attribute to the mpJwt configuration element.

3. In the sentence, please change JWk to JWK.

4. Thank you very much for bringing this content over to openliberty.io.

[ManasiGandhi]

@teddyjtorres Thanks for your review Teddy. I worked on your review comments. You can see the updates here https://draft-openlibertyio.mybluemix.net/docs/21.0.0.4/reference/feature/jwtSso-1.0.html

• There seems to be a problem rendering the subtitle, there should be a space between these two,

"JWT SSO authentication. === Change JWT validation criteria"

• Please move

<mpJwt id="myMpJwt" jwksUri="https://localhost:19443/jwt/ibm/api/myBuilder/jwk" />

after the sentences

In the example, the JWk endpoint specifies the JWT builder with the ID myBuilder. To use the JWK endpoint for consuming JWTs, add the jwksUri attribute to the mpJwt configuration element.

• In the sentence, please change JWk to JWK.

[teddyjtorres]

Thank you. They look good.

[dmuelle]

Content review

• throughout this page, replace the code name (jwtSso) with the text name (JSON Web Token Single Sign-On) of the feature, per ID guidelines.
  With the jwtSso feature you can use a JSON Web Token (JWT) as a Single-Sign-On (SSO).
  What is "a Single Sign On" ? maybe:
  "With the JSON Web Token Single Sign-On feature, you can configure JSON Web Tokens (JWT) as an authentication mechanism for single-sign-on (SSO) authentication."

The KC topic says "The JWT SSO cookie is configured by enabling the jwtSso-1.0 feature. When a user is authenticated, Liberty creates a signed JWT as an SSO cookie and returns it to the browser. The browser can then include the JWT cookie in subsequent requests to the Liberty server." --> this information, edited for OL, would be good to include after the introductory statement.

Change the token expiration time

• You can customize how the JWT is built with the jwtSso feature. The following example shows how you can configure the jwtSso feature to change the token expiration time:
  --->
  To customize the expiration time of a JWT, configure the jwtBuilder element, as shown in the following example:

• The jwtBuilderRef attribute refers to the jwtBuilder element myBuilder.
  -->
  The jwtBuilderRef attribute refers to the jwtBuilder element with the myBuilder ID.

Change JWT validation criteria

The jwtSso feature automatically uses the mpJwt element.
-->
You can specify the mpJwt element to configure how incoming JWTs are validated and consumed by the server.

The following example uses a jwtBuilder element reference to customize the creation of the tokens and an mpJwt element to customize validation and consumption of the tokens.
--->
In the following example, the jwtBuilder element specifies the issuer claim for JWTs that the server creates. The mpJwt element specifies the issuer claim and key alias for incoming JWTs that the server receives:

Use the JSON Web Key (JWK) endpoint to validate JWTs

Need to recheck this example against the KC source (step 5). It's missing info and the examples aren't ordered correctly

[ManasiGandhi]

@dmuelle I worked on your content review.

Content review

• throughout this page, replace the code name (jwtSso) with the text name (JSON Web Token Single Sign-On) of the feature, per ID guidelines. - I kept the code name as is for this sentence, If the jwtSso feature is enabled but jwtSso element does not include the authFilterRef attribute, all requests to access the protected resources that have a JWT cookie are used for the JWT SSO authentication.

• With the jwtSso feature you can use a JSON Web Token (JWT) as a Single-Sign-On (SSO).

What is "a Single Sign On" ? maybe:
"With the JSON Web Token Single Sign-On feature, you can configure JSON Web Tokens (JWT) as an authentication mechanism for single-sign-on (SSO) authentication."

• The KC topic says "The JWT SSO cookie is configured by enabling the jwtSso-1.0 feature. When a user is authenticated, Liberty creates a signed JWT as an SSO cookie and returns it to the browser. The browser can then include the JWT cookie in subsequent requests to the Liberty server." --> this information, edited for OL, would be good to include after the introductory statement.

Change the token expiration time

• You can customize how the JWT is built with the jwtSso feature. The following example shows how you can configure the jwtSso feature to change the token expiration time:

--->
To customize the expiration time of a JWT, configure the jwtBuilder element, as shown in the following example:

• The jwtBuilderRef attribute refers to the jwtBuilder element myBuilder.

-->
The jwtBuilderRef attribute refers to the jwtBuilder element with the myBuilder ID.

Change JWT validation criteria

• The jwtSso feature automatically uses the mpJwt element.

-->
You can specify the mpJwt element to configure how incoming JWTs are validated and consumed by the server.

• The following example uses a jwtBuilder element reference to customize the creation of the tokens and an mpJwt element to customize validation and consumption of the tokens.

--->
In the following example, the jwtBuilder element specifies the issuer claim for JWTs that the server creates. The mpJwt element specifies the issuer claim and key alias for incoming JWTs that the server receives:

Use the JSON Web Key (JWK) endpoint to validate JWTs

• Need to recheck this example against the KC source (step 5). It's missing info and the examples aren't ordered correctly

[dmuelle]

Hi Manasi
The updated title looks good, but the description still needs to be more specific than "consuming JWTs"
in the JWK example:

"To use the JWK endpoint for consuming JWTs, add the jwksUri attribute to the mpJwt configuration element that exists in the server.xml file."

Maybe:

"To retrieve the JWT issuer public key from a JWK endpoint, specify the endpoint in the jwksUri attribute for the mpJwt element in your sever.xml file:"

Then in the last description, the reference to "different builder" should be more specific:

"If you specified a different builder, its JWK endpoint is http(s)://<host>:<port>/jwt/ibm/api/(builderId)/jwk. For example, in the following example the jwtSso element has a JWK endpoint of http(s)://:/jwt/ibm/api/myBuilder/jwk."

--->

If you specify a non-default JWT builder, the JWK endpoint is http(s)://:/jwt/ibm/api/(builderId)/jwk, where (builderId) is the value of the id attribute for thejwtBuilderelement. In the following example, the configured jwtSso element results in a JWK endpoint of http(s)://<host>:<port>/jwt/ibm/api/myBuilder/jwk."