BETA BLOG - Support LTPA keys rotation without requiring planned outage

[Zech-Hein]

The information you provide here will be included in the Open Liberty beta blog post (example), which will be published on openliberty.io/blog/, and potentially elsewhere, to promote this beta feature/function of Open Liberty. For this post to be included in the beta issue please make sure that this is completed by the end of Friday following the GM (Tuesday). The beta and release blogs are created using automation and rely on you following the template's structure. DO NOT REMOVE/ALTER THE <GHA> TAGS THROUGHOUT THIS TEMPLATE.

Please provide the following information:
​

1. Which Liberty feature(s) does your update relate to?

   Human-readable name (eg WebSockets feature):
   Application Security

   Short feature name (eg websockets-1.0):
   appSecurity-*

2. Who is the target persona? Who do you expect to use the update? eg application developer, operations.
   Administrator

3. Provide a summary of the update, including the following points:

   • A sentence or two that introduces the update to someone new to the general technology/concept.

   • What was the problem before and how does your update make their life better? (Why should they care?)

   • Briefly explain how to make your update work. Include screenshots, diagrams, and/or code snippets, and provide a server.xml snippet.

   • Where can they find out more about this specific update (eg Open Liberty docs, Javadoc) and/or the wider technology?

Definitions

• Primary Keys - LTPA keys in the specified keys default ltpa.keys` file.
  • The primary keys are used both for generating new LTPA tokens and for validating LTPA tokens. There can only be one primary keys file per Liberty Server.
• Validation Keys - LTPA keys in any other .keys files other than the primary keys file.
  • The validation keys are only used for validating LTPA tokens. They are not used for generating new LTPA tokens. All validation keys must be located in the same directory as the primary keys file

With the added support of rotating LTPA keys without requiring a planned outage, administrators will be able to keep applications running without any disruption to application access. Before this added support, Administrators who wanted to update their Liberty server LTPA keys could not do so without disrupting the user experience. Users would be required to login to their applications again after the Liberty server LTPA keys had been rotated.

There are 2 ways to enable this new functionality

1. Use the Liberty Server's new capability to monitor the directory of the primary keys file for any new validation keys files.

   • This is done by enabling the monitorDirectory and monitorInterval attributes
   • Example server.xml configurations:

    <ltpa monitorDirectory="true" monitorInterval="5m"/>
   

   • The monitorDirectory attribute monitors the ${server.config.dir}/resources/security/ directory by default, but will monitor any directory the primary keys file is specified in. The directory monitor will look for any LTPA keys files with the .keys extension. The Open Liberty server will read these LTPA keys and use them as Validation Keys.

   • If the monitorInterval is set to 0, the default value, the directory will stop being monitored.

   • The ltpa.keys file can be renamed, for example, validation1.keys and then the Liberty server will automatically regenerate a new ltpa.keys file with new primary keys that will be used for all new LTPA tokens created. The keys in validation1.keys will continue to be used for validating existing LTPA tokens.

   • Once the validation1.keys are no longer needed, remove them from usage by deleting the file, or by setting monitorDirectory to false. It is recommended to remove validation keys as it can improve performance.

2. Specify the validation keys file and optionally specify a date-time to stop using the validation keys.

   • Copy the primary keys file (ltpa.keys) to a validation keys file, for example validation1.keys.
   • Modify the server configuration to use the validation keys file by specifying a <validationKeys> server configuration element inside the <ltpa> element.
   • Example server.xml:

   <ltpa>
       <validationKeys fileName="validation1.keys" password="{xor}Lz4sLCgwLTs=" notUseAfterDate="2024-01-02T12:30:00Z"/>
   <ltpa/>  
   

   • The validation1.keys file can be removed from usage at a specified date-time in the future with the optional attribute, notUseAfterDate. It is recommended to use notUseAfterDate to remove validation keys after a given period as it can improve performance.
   • The fileName and password attributes are required in the validationKeys element, but notUseAfterDate is optional.
   • After the validation keys file is loaded from the server configuration update, then the original primary keys file (ltpa.keys) can be deleted, which will trigger new primary keys to be created while continuing to use validation1.keys for validation.

• Specifying validation keys this way can also be combined with using monitor directory to ready more validation keys that are specified in server.xml configuration.

  • Example server.xml:

  <ltpa monitorDirectory="true" monitorInterval="5m">
     <validationKeys fileName="validation1.keys" password="{xor}Lz4sLCgwLTs=" notUseAfterDate="2024-01-02T12:30:00Z"/>
  <ltpa/>
  

• To see all of the Liberty <ltpa> server configuration options see: https://openliberty.io/docs/latest/reference/config/ltpa.html

One-Way Single Sign-On (SSO)

This feature also provides the new capability to perform one-way Single Sign-On (SSO) for LTPA tokens which was not previously possible. Before this feature, SSO for LTPA tokens could only be bi-directional, not one-way, and required using the same ltpa.keys file on every applicable Liberty server. The new "one-way" SSO means a user will be able to use SSO from Liberty server1 to server2, but not from server2 to server1.

• If you have two (or more) Liberty servers, for example server1 and server2, each with a different LTPA primary keys file - Adding the primary keys file from server1, as a validation keys file to server2 will allow one-way single sign-on capability from server1 to server2.

• A user who authenticated to server1 first will be able to access server2 with SSO. However, a user who authenticates to server2 first will need to re-authenticate again before accessing server1 because server1 does not have the primary keys file from server2.

What happens next?

• Add the label for the beta you're targeting: target:YY00X-beta.
• Make sure this blog post is linked back to the Epic for this feature/function.
• Your paragraph will be included in the beta blog post. It might be edited for style and consistency.
• You will be asked to review a draft before publication.
  • Once you've approved the code review, close this issue.
• If you would also like to write a standalone blog post about your update (highly recommended), raise an issue on the Open Liberty blogs repo. State in the issue that the blog post relates to a specific release so that we can ensure it is published on an appropriate date (it won't be the same day as the beta blog post).

[Zech-Hein]

published in: https://openliberty.io/blog/2023/09/26/23.0.0.10-beta.html#ltpa