Package jakarta.security.jacc

Interface PrincipalMapper

public interface PrincipalMapper
A PrincipalMapper is an object that maps from a collection of generic Principals or a Subject to well known entities in Jakarta EE.

The following target entities are supported:

  • The caller principal - a java.security.Principal containing the name of the current authenticated user.
  • The role - a java.lang.String representing the logical application role associated with the caller principal.

A PrincipalMapper is intended to be used by a Policy, but should work outside a Policy (for instance, during request processing in a Servlet container).

NOTE: DRAFT API. SUBJECT TO CHANGE

Author:
Arjan Tijms

  • Method Summary

    Modifier and Type
    Method
    Description
    default Principal
    getCallerPrincipal(Set<Principal> principals)
    Pick from the principals within the passed-in set of principals the platform-specific java.security.Principal that represents the name of the authenticated caller, or null if the current caller is not authenticated.
    Principal
    getCallerPrincipal(Subject subject)
    Pick from the principals within the passed-in Subject the platform-specific java.security.Principal that represents the name of authenticated caller, or null if the current caller is not authenticated.
    default Set<String>
    getMappedRoles(Set<Principal> principals)
    Pick from the principals within the passed-in set of principals all application roles that are associated with the caller principal.
    Set<String>
    getMappedRoles(Subject subject)
    Pick from the principals within the passed-in Subject all application roles that are associated with the caller principal.
    default boolean
    isAnyAuthenticatedUserRoleMapped()
    Jakarta Security defines the "any authenticated caller role" as "**" and allows an application specific mapping for this role to be established.

  • Method Details

    • getCallerPrincipal

      Principal getCallerPrincipal(Subject subject)
      Pick from the principals within the passed-in Subject the platform-specific java.security.Principal that represents the name of authenticated caller, or null if the current caller is not authenticated.
      Parameters:
      subject - the subject from which the caller principal is to be retrieved.
      Returns:
      Principal representing the name of the current authenticated user, or null if not authenticated.

    • getMappedRoles

      Set<String> getMappedRoles(Subject subject)
      Pick from the principals within the passed-in Subject all application roles that are associated with the caller principal.

      The roles returned here are the logical application roles. If the principals in the passed-in Subject represent non-application roles (called "groups"), the implementation must perform the group-to-role mapping. For instance, if a Principal representing the group "adm" is present in the Subject, and the group "adm" is mapped (in a implementation specific way) to "administrator", then "administrator" must be returned here.

      Parameters:
      subject - the subject from which the roles are to be retrieved.
      Returns:
      a set of logical application roles associated with the caller principal.

    • getCallerPrincipal

      default Principal getCallerPrincipal(Set<Principal> principals)
      Pick from the principals within the passed-in set of principals the platform-specific java.security.Principal that represents the name of the authenticated caller, or null if the current caller is not authenticated.
      Parameters:
      principals - the set of principals from which the caller principal is to be retrieved.
      Returns:
      Principal representing the name of the current authenticated user, or null if not authenticated.

    • getMappedRoles

      default Set<String> getMappedRoles(Set<Principal> principals)
      Pick from the principals within the passed-in set of principals all application roles that are associated with the caller principal.

      The roles returned here are the logical application roles. If the principals in the passed-in Subject represent non-application roles (called "groups"), the implementation must perform the group-to-role mapping. For instance, if a Principal representing the group "adm" is present in the Subject, and the group "adm" is mapped (in a implementation specific way) to "administrator", then "administrator" must be returned here.

      Parameters:
      principals - the set of principals from which the roles are to be retrieved.
      Returns:
      a set of logical application roles associated with the caller principal.

    • isAnyAuthenticatedUserRoleMapped

      default boolean isAnyAuthenticatedUserRoleMapped()
      Jakarta Security defines the "any authenticated caller role" as "**" and allows an application specific mapping for this role to be established. E.g. "**" could be mapped to the logical application role "admin".

      This method is used to discover if such a mapping has indeed been done. If it has been done, "**" is a regular role name and we can no longer check for "any authenticated caller" using "**".

      Returns:
      true if the special "**" role has been mapped to something else, false otherwise.