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).

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default java.security.Principal getCallerPrincipal​(java.util.Set<java.security.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.
      java.security.Principal getCallerPrincipal​(javax.security.auth.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 java.util.Set<java.lang.String> getMappedRoles​(java.util.Set<java.security.Principal> principals)
      Pick from the principals within the passed-in set of principals all application roles that are associated with the caller principal.
      java.util.Set<java.lang.String> getMappedRoles​(javax.security.auth.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 Detail

      • getCallerPrincipal

        java.security.Principal getCallerPrincipal​(javax.security.auth.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

        java.util.Set<java.lang.String> getMappedRoles​(javax.security.auth.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 java.security.Principal getCallerPrincipal​(java.util.Set<java.security.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 java.util.Set<java.lang.String> getMappedRoles​(java.util.Set<java.security.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.