Module jakarta.security.jacc

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

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.