Add section for Private Key JWT client authentication in OIDC client docs

[ayoho]

Epic: OpenLiberty/open-liberty#21826

Relevant docs page: https://openliberty.io/docs/latest/reference/feature/openidConnectClient-1.0.html

New section proposal

Title: Use Private Key JWT for client authentication

Location: After the Support Multiple OpenID Connect Providers section.

Content:
OpenID Connect clients in Open Liberty support the private_key_jwt client authentication method with OpenID Connect token endpoints. OpenID Connect clients are required to provide authentication data to the OpenID Connect provider when invoking the provider's token endpoint. Clients can authenticate using several different methods, but most of those methods require a client secret. The private_key_jwt authentication method allows clients to make use of asymmetric keys to create signed JSON Web Tokens (JWTs) to authenticate instead of client secrets. OpenID Connect clients in Open Liberty using this authentication method are no longer required to have a client secret.

Server administrators can enable this functionality using the private_key_jwt option for the tokenEndpointAuthMethod attribute, as well as the new tokenEndpointAuthSigningAlgorithm and keyAliasName attributes in the <openidConnectClient> element:

<openidConnectClient tokenEndpointAuthMethod="private_key_jwt" tokenEndpointAuthSigningAlgorithm="E512" keyAliasName="privatekeyaliasES512" ... />

The tokenEndpointAuthSigningAlgorithm attribute specifies the signing algorithm to use to sign the JWT used for client authentication. The keyAliasName attribute points to the private key to use to sign the JWT. The private key must exist in the keystore that is referenced by the sslRef attribute in the OpenID Connect client configuration. OpenID Connect providers that support Private Key JWT client authentication typically provide an interface for administrators to upload their corresponding public key.

More information about private_key_jwt client authentication can be found in the OpenID Connect core specification and RFC 7523.

Other updates

Relevant docs page: https://openliberty.io/docs/latest/reference/feature/socialLogin-1.0.html

New section proposal

Title: Use Private Key JWT for client authentication

Location: After the Provide other social media logins as options to the user section.

Content:
OpenID Connect clients that are configured using the <oidcLogin> element in the Social Media Login feature support the private_key_jwt client authentication method with OpenID Connect token endpoints. The process for enabling this support is identical to the OpenID Connect Client 1.0 feature. An example is shown here.

<oidcLogin tokenEndpointAuthMethod="private_key_jwt" tokenEndpointAuthSigningAlgorithm="E512" keyAliasName="privatekeyaliasES512" ... />

[ramkumar-k-9286]

@ayoho

Hi Adam,

The suggested changes have been made.

Draft Document links:

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

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

Please check and add the Technical Reviewed label, if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[ayoho]

@ramkumar-k-9286

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#privatekey

OpenID Connect clients in Open Liberty by using this authentication method are no longer need to have a client secret.

The change to this sentence makes it clunky and now has an error. I prefer one of the following revisions:

OpenID Connect clients in Open Liberty that use this authentication method do not need to have a client secret.

Or a revision based on your change:

By using this authentication method, OpenID Connect clients in Open Liberty no longer need to have a client secret.

The formatting of the XML in this section is a bit off. We could add some newlines to make it more readable:

<openidConnectClient id="myOidcClientUsingPrivateKeyJwt"
    tokenEndpointAuthMethod="private_key_jwt"
    tokenEndpointAuthSigningAlgorithm="E512"
    keyAliasName="privatekeyaliasES512"
    ...
/>

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

OpenID Connect clients that are configured by using the element in the Social Media Login feature supports the private_key_jwt client authentication

Need to change "supports" to "support" to agree with "clients", which is the subject of the sentence.

Same XML formatting suggestion.

[ramkumar-k-9286]

@ayoho

Hi Adam,

The suggested corrections have been made.

Draft Document links:

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

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

Please review the same and add the Technical Reviewed label, if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

Quick question:
The section added to socialLogin-1.0.html file - The code block - is it missing an id=" ....." . Please Confirm

[ayoho]

Changes look good. The XML snippet in https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#_use_private_key_jwt_for_client_authentication still needs to have its indentation fixed, though.

<oidcLogin id="myOidcClientUsingPrivateKeyJwt"
    tokenEndpointAuthMethod="private_key_jwt"
    tokenEndpointAuthSigningAlgorithm="E512"
    keyAliasName="privatekeyaliasES512"
    ...
/>

(If you're already going back to fix the indentation, I'd suggest adding an id that I forgot originally. I put that in the example above.)

[ramkumar-k-9286]

@ayoho

Hi Adam,

The suggested corrections have been made to the code block in both documents.

Draft Document links:

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

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

Please review the same and add the Technical Reviewed label, if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[ayoho]

LGTM 👍

[dmuelle]

Peer review

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

• <oidcLogin> element ---> oidcLogin element
• OpenID Connect Client 1.0 feature. Link is pointing to this issue instead of the feature page :D Instead, it should point directly to the relevant example on the OIDC-client feature page.
• The process for enabling this support is identical to the OpenID Connect Client 1.0 feature.
  --->
  The process for enabling this support in the Social Media Login feature is identical to enabling it for the OpenID Connect Client 1.0 feature. For more information, see [OpenID Connect Client 1.0: Use Private Key JWT for client authentication] (link) Move this sentence to be after the example.
• I think we should add an anchor list for the examples on this page, similar to what we have on the OIDC page

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

The tokenEndpointAuthSigningAlgorithm attribute specifies the signing algorithm to use to sign the JWT used for client authentication.
--->
The tokenEndpointAuthSigningAlgorithm attribute specifies the signing algorithm to sign the JWT that is used for client authentication.

sslRef attribute in the OpenID Connect client configuration ---> sslRef attribute in the config:openidConnectClient[display=OpenID Connect client configuration].

[ramkumar-k-9286]

@dmuelle

Hi David

Made suggested corrections to the page.

Draft Document links:

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

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

Please review the same. Please let me know if I need to make more corrections.

Regards,
Ramkumar

[dmuelle]

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#privatekeyjwt

Looks good except the link to OpenID Connect Client 1.0 feature should point directly to the Use Private Key JWT for client authentication example on the OIDC page. I think you will have to construct a relative link instead of using the macro to get it to recognize the anchor.

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

use asymmetric keys to create signed JSON Web Tokens (JWTs) to authenticate instead of

JWT is already defined on the page so you can just use the abbreviation here.

for client authentication.The keyAliasName attribute points to

missing space after period

[ramkumar-k-9286]

@dmuelle

Hi David

Made suggested corrections to the page.

Draft Document links:

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

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

Regards,
Ramkumar

[dmuelle]

LGTM, thanks, adding peer review label

[ramkumar-k-9286]

@dmuelle

Hi David

Staging site links:

https://docs-staging-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#privatekeyjwt

https://docs-staging-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#privatekey

Regards,
Ramkumar

[dmuelle]

content is on vNExt and will publish with 23.0.0.6

[dmuelle]

reopening issue as the epic fell out of 23.0.0.6 and is now expected for 23.0.0.8. Backporting changes to remove published docs form 23.0.0.6 and 7.

[ramkumar-k-9286]

@dmuelle

Hi David

Draft site links:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#privatekeyjwt

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#privatekey

Regards,
Ramkumar

[dmuelle]

LGTM, send to staging when you have a chance

[ramkumar-k-9286]

@dmuelle

Hi David

Staging site links:

https://docs-staging-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/socialLogin-1.0.html#privatekeyjwt

https://docs-staging-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/openidConnectClient-1.0.html#privatekey

Regards,
Ramkumar

[dmuelle]

LGTM, thanks

[dmuelle]

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