Document, Jakarta Authorization 3.0

[jhanders34]

Feature epic details

• Link to development epic: Jakarta EE 11: Support Jakarta Authorization 3.0 open-liberty#25420
• Target GA release: ??

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

Jakarta Authorization 3.0 provides the next evolution of the Jakarta Authorization specification.

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

Add an Authorization 3.0 differences section to the EE 11 and EE 10 differences page:

Differences between Jakarta Authorization 3.0 and 2.1

The Jakarta Authorization 3.0 API introduces the new jakarta.security.jacc.PolicyFactory and jakarta.security.jacc.Policy classes for making authorization decisions. These classes are added to remove the dependency on the java.security.Policy class, which is deprecated in newer versions of Java. With the new PolicyFactory API, you can now have a Policy per policy context instead of having a global policy. This design allows separate policies to be maintained for each application.

Additionally, the 3.0 specification defines a mechanism for specifying PolicyConfigurationFactory and PolicyFactory classes in your application by using a web.xml file. This design allows an application to have a different configuration than the server-scoped one, but still allows it to delegate to a server-scoped factory for any other applications. Authorization modules can do this delegation by using decorator constructors for both PolicyConfigurationFactory and PolicyFactory classes.

To configure your authorization modules in your application’s web.xml file, add specification-defined context parameters:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_1.xsd"
  version="6.1">

  <context-param>
    <param-name>jakarta.security.jacc.PolicyConfigurationFactory.provider</param-name>
    <param-value>com.example.MyPolicyConfigurationFactory</param-value>
  </context-param>

  <context-param>
    <param-name>jakarta.security.jacc.PolicyFactory.provider</param-name>
    <param-value>com.example.MyPolicyFactory</param-value>
  </context-param>

</web-app>

Due to Jakarta Authorization 3.0 no longer using the java.security.Policy class and introducing a new configuration mechanism for authorization modules, the com.ibm.wsspi.security.authorization.jacc.ProviderService Liberty API is no longer available with the appAuthorization-3.0 feature. If a Liberty user feature configures authorization modules, the OSGi service that provided a ProviderService implementation must be updated to use the PolicyConfigurationFactory and PolicyFactory set methods in the OSGi component. Alternatively, you can use a Web Application Bundle (WAB) in your user feature to specify your security modules in a web.xml file. When using an existing user feature that uses the ProviderService API, your user feature will fail to start with an error message that states Unresolved requirement: Import-Package: com.ibm.wsspi.security.authorization.jacc; version="[10.0.0,20.0.0)".

The 3.0 API also adds a new jakarta.security.jacc.PrincipalMapper class that you can obtain from the PolicyContext class when authorization processing is done in your Policy implementation. From this class, you can obtain the roles associated with a specific Subject to be able to determine whether the Subject is in the required role. Liberty's implementation of this class provides the roles specified in the <application-bnd> application configuration in your server.xml or in your application's ibm-application-bnd.xml file. If that configuration is not provided, the implementation falls back to the user registry's group names as role names.

You can use the PrincipalMapper class in your Policy implementation’s impliesByRole (or implies) method, as shown in the following example:

    public boolean impliesByRole(Permission p, Subject subject) {
        Map<String, PermissionCollection> perRolePermissions =
            PolicyConfigurationFactory.get().getPolicyConfiguration(contextID).getPerRolePermissions();
        PrincipalMapper principalMapper = PolicyContext.get(PolicyContext.PRINCIPAL_MAPPER);

        // Check to see if the Permission is in the any authenticated user role (**)
        if (!principalMapper.isAnyAuthenticatedUserRoleMapped() && !subject.getPrincipals().isEmpty()) {
            PermissionCollection rolePermissions = perRolePermissions.get("**");
            if (rolePermissions != null && rolePermissions.implies(p)) {
                return true;
            }
        }

        // Check to see if the roles for the Subject provided imply the permission
        Set<String> mappedRoles = principalMapper.getMappedRoles(subject);
        for (String mappedRole : mappedRoles) {
            PermissionCollection rolePermissions = perRolePermissions.get(mappedRole);
            if (rolePermissions != null && rolePermissions.implies(p)) {
                return true;
            }
        }
        return false;
    }

[jhanders34]

@ramkumar-k-9286 I added this issue for Jakarta EE 11 as well.

[ramkumar-k-9286]

Hi @jhanders34

Differences information has been added for Jakarta Authorization 3.0.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/diff/jakarta-ee11-diff.html#authorization

Please review the same and add comments. if you are satisfied with the updates add the Developer reviewed label.

Regards,
Ramkumar.

[jhanders34]

@ramkumar-k-9286 not sure where you wanted comments added so I am going to add them here. The changes look good. Reading it through though I am thinking to change when authorization processing is done to when doing authorization processing or maybe when performing authorization processing.