Application Security (Jakarta Security )
5.0
4.0
3.0
2.0
1.0

This feature enables support for securing the server runtime environment and applications using Jakarta Security 3.0.

If you are updating your application from using the appSecurity-4.0 feature to using the appSecurity-5.0 feature, changes in API behavior might require you to update your application code. For more information, see Differences between Jakarta Security 5.0 and 4.0.

The Application Security 5.0 feature supports the OpenIdAuthenticationMechanismDefinition annotation to configure a built-in OpenID Connect authentication mechanism. This authentication mechanism functions as an OpenID Connect client, or Relying Party (RP), so that you can use an OpenID Connect Provider (OP) as a single sign-on identity provider. For more information, see Enable an OpenID Connect client for an application.

Enabling this feature

To enable the Application Security 5.0 (Jakarta Security 3.0) feature, add the following element declaration into your server.xml file, inside the featureManager element:

Copied to clipboard
<feature>appSecurity-5.0</feature>

Examples

Configure a basic user registry

You can configure Open Liberty to authenticate and authorize users by using a basic user registry. The basic user registry contains user credentials that applications need for security-related tasks. To configure a basic user registry, the Application Security feature must be enabled in the server.xml file. The following example shows the configuration of a basic user registry in the server.xml file:

Copied to clipboard
<basicRegistry id="basic" realm="BasicRealm">
   <user name="Bob" password="bobpwd" />
   <user name="John" password="johnpwd" />
</basicRegistry>

To configure a basic user registry with multiple users, you can create groups for users with unique group names as shown in the following example:

Copied to clipboard
<basicRegistry id="basic" realm="BasicRealm">
  <user name="Bob" password="bobpwd" />
  <user name="John" password="johnpwd" />
  <user name="user1" password="user1pwd"/>
  <user name="user2" password="user2pwd" />

  <group name="myAdmins">
    <member name="Bob" />
    <member name="user1" />
  </group>

  <group name="users">
    <member name="user1" />
    <member name="user2" />
  </group>
</basicRegistry>

User and group names must be unique and cannot contain any trailing or leading spaces. If a user ID or password contains characters other than US-ASCII, make sure that the server.xml file is saved by using UTF-8 character encoding. You can use the securityUtility encode command to encode the password for each user. For more information, see securityUtility encode. You can also specify administrative roles for users and groups to govern access to Open Liberty administrative REST APIs. For more information, see the Admin REST Connector feature.

Configure a basic user registry with QuickStart security

When you want to configure a basic user registry for test purposes, you can use the quickStartSecurity element to automatically configure a registry that grants the administrator role to a user. The administrator role gives the user the authority to manage applications. The following example shows the server.xml file configuration to define the username and password for a user that is granted the administrator role with the quickStartSecurity element:

Copied to clipboard
<quickStartSecurity userName="Bob" userPassword="bobpwd" />

You can use QuickStart security configuration for test purposes. The registry that is configured by this option is not intended for production environments. However, it is useful in test scenarios, particularly for testing secured JMX connections that require administrator access.

Specify LTPA keys

When the Application Security feature is enabled, Lightweight Third-Party Authentication (LTPA) is enabled by default. You can override the default settings for the ltpa element by configuring the ltpa element in the server.xml file. The following example shows how to configure the ltpa element:

Copied to clipboard
<ltpa keysFileName="yourLTPAKeysFileName.keys" keysPassword="keysPassword" expiration="120" />

For more information on LTPA configuration attributes, see the LTPA configuration element.

Configure LTPA authentication for a subset of requests

You can configure an authentication filter to specify whether certain requests for protected resources are authenticated with LTPA. If the request meets the criteria that are specified in the authentication filter, then the request can authenticate with LTPA to access the protected resource. Conversely, if the request does not meet the criteria that are configured in the LTPA authentication filter, then the user is prompted to provide login credentials. For more information, see Authentication filters.

Copied to clipboard
<ltpa keysFileName="yourLTPAKeysFileName.keys" keysPassword="keysPassword" expiration="120" authFilterRef="myAuthFilter"/>

<authFilter id="myAuthFilter">
         <requestUrl id="myRequestUrl" urlPattern="/SimpleServlet" matchType="contains"/>
</authFilter>

In the example, request URLs that contain the /SimpleServlet pattern are authenticated by using LTPA SSO authentication. If the ltpa element does not specify the authFilterRef attribute, all requests that include an LTPA cookie are processed by LTPA SSO authentication.

Disable LTPA cookies for TAI

LTPA cookies contain secure tokens that are used to verify user credentials and enable SSO. When you don’t want to rely on LTPA tokens for SSO, you can use other methods, such as a Trust Association Interceptor (TAI), for authentication. A TAI is used to validate HTTP requests between a third-party security server and an Open Liberty server to complete authentication. The following example shows how to disable LTPA cookies for TAI by specifying the disableLtpaCookie attribute with a value of true in the server.xml file:

Copied to clipboard
<trustAssociation id="sample" disableLtpaCookie="true" />

Rotate LTPA keys without requiring users to reauthenticate

Open Liberty can use either primary keys or validation keys to validate LTPA tokens. You can rotate LTPA keys without requiring reauthentication by using validation keys to validate existing LTPA tokens whenever you generate new primary keys.

Primary Keys are LTPA keys in the specified LTPA keys file, which is ltpa.keys by default but can be configured with the keysFileName attribute. Primary keys are used both for generating new LTPA tokens and for validating LTPA tokens. Only one primary keys file can exist for each Liberty runtime.

Validation keys are LTPA keys in any *.keys files other than the primary keys file. The validation keys are used only for validating LTPA tokens. They are not used for generating new LTPA tokens. All validation keys files must be located in the same directory as the primary keys file.

To rotate LTPA keys without requiring reauthentication, copy the primary keys to a validation keys file and then delete the primary keys file. Open Liberty automatically generates a new primary LTPA keys file to validate any new LTPA tokens while it continues to use validation keys files to validate existing LTPA tokens.

  1. Configure Open Liberty to use validation keys.

    To enable Open Liberty to use both primary keys and validation keys, specify the monitorValidationKeysDir and monitorInterval attributes for the ltpa element in your server.xml file, as shown in the following example:

    Copied to clipboard
    <ltpa monitorValidationKeysDir="true" monitorInterval="5m"/>

    The directory monitor looks for any LTPA keys files with the *.keys extension in the ${server.config.dir}/resources/security/ directory. Open Liberty reads the LTPA keys in these files and uses them to validate LTPA tokens.

    The monitorValidationKeysDir attribute monitors the ${server.config.dir}/resources/security/ directory by default, but can monitor any directory the primary keys file is specified in. Monitoring is enabled only when the updateTrigger attribute is set to polled (the default value) and the monitorInterval attribute is set to a duration greater than 0. The default value of the monitorInterval attribute is 0.

    Alternatively, you can specify the validationKeys subelement to specify a particular validation keys file. You can also remove the validation keys in this file from use at a particular date and time with the optional validUntilDate attribute. In the following example, a validation keys file is specified with an expiration date after which the keys in the file are removed from use automatically:

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

    The fileName and password attributes are required in the validationKeys element, but the validUntilDate attribute is optional.

    When you specify the validationKeys subelement, the monitorValidationKeysDir element is not required. However, you can use both elements in combination so that any *.keys files in the primary keys file directory are used to validate LTPA tokens and not just the file that is specified by the validationKeys fileName attribute.

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

    In this case, any validation keys in files other than the file that is specified by the validationKeys subelement remain in use until you delete the corresponding .keys file or set the monitorValidationKeysDir attribute to false.

  2. Copy the primary keys to a validation keys file.

    If you copy the primary keys to a validation keys file in the same directory, or to a file that is specified by the validationKeys subelement, the runtime can continue to use these keys to validate LTPA tokens when the primary keys file is removed.

  3. Delete the primary keys file.

    Open Liberty automatically generates a new primary keys file to create and validate new LTPA tokens, while it continues to use the validation keys files to validate existing LTPA tokens. In this way, you can rotate the LTPA keys without requiring existing users to reauthenticate.

  4. Optionally, when you no longer need the validation keys, remove them by deleting the validation keys file or by setting the monitorValidationKeysDir attribute to false.

    Removing unused validation keys can improve performance.

Feature configuration elements

Standard API packages provided by this feature

  • jakarta.security.auth.message

  • jakarta.security.auth.message.callback

  • jakarta.security.auth.message.config

  • jakarta.security.auth.message.module

  • jakarta.security.enterprise

  • jakarta.security.enterprise.authentication.mechanism.http

  • jakarta.security.enterprise.authentication.mechanism.http.openid

  • jakarta.security.enterprise.credential

  • jakarta.security.enterprise.identitystore

  • jakarta.security.enterprise.identitystore.openid

Liberty API packages provided by this feature

Features that this feature enables

Supported Java versions

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

  • JavaSE-23.0

Platform Versions

  • jakartaee-10.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

Copied to clipboard
io.openliberty.appSecurity-5.0; type="osgi.subsystem.feature"