org.apache.jackrabbit.oak.spi.security.principal

Interface PrincipalProvider

All Known Implementing Classes:

CompositePrincipalProvider, EmptyPrincipalProvider

@ProviderType
public interface PrincipalProvider

The PrincipalProvider defines methods to provide access to sources of Principals. This allows the security framework share any external sources for authorization and authentication, as may be used by a custom LoginModule for example. A single PrincipalProvider implementation is expected to exposed principals from one single source. In contrast to the PrincipalManager which will expose all known and accessible principals from possibly different sources. See also CompositePrincipalProvider for a mechanism to combine principals of different providers.

Method Summary

Modifier and Type	Method and Description
@NotNull java.util.Iterator<? extends java.security.Principal>	findPrincipals(int searchType) Find all principals that match the search type.
default @NotNull java.util.Iterator<? extends java.security.Principal>	findPrincipals(@Nullable java.lang.String nameHint, boolean fullText, int searchType, long offset, long limit) Find the principals that match the specified nameHint and search type.
@NotNull java.util.Iterator<? extends java.security.Principal>	findPrincipals(@Nullable java.lang.String nameHint, int searchType) Find the principals that match the specified nameHint and search type.
default @NotNull java.util.Set<java.security.acl.Group>	getGroupMembership(@NotNull java.security.Principal principal) Deprecated. use getMembershipPrincipals(Principal)
default @Nullable ItemBasedPrincipal	getItemBasedPrincipal(@NotNull java.lang.String principalOakPath) Returns the ItemBasedPrincipal with the specified principalOakPath or null if no principal with that path exists.
default @NotNull java.util.Set<java.security.Principal>	getMembershipPrincipals(@NotNull java.security.Principal principal) Returns an iterator over all group principals for which the given principal is either direct or indirect member of.
@Nullable java.security.Principal	getPrincipal(@NotNull java.lang.String principalName) Returns the principal with the specified name or null if the principal does not exist.
@NotNull java.util.Set<? extends java.security.Principal>	getPrincipals(@NotNull java.lang.String userID) Tries to resolve the specified userID to a valid principal and it's group membership.

Method Detail

getPrincipal

@Nullable
@Nullable java.security.Principal getPrincipal(@NotNull
                                                         @NotNull java.lang.String principalName)

Returns the principal with the specified name or null if the principal does not exist.

Parameters:

principalName - the name of the principal to retrieve

Returns:

return the requested principal or null

getItemBasedPrincipal

@Nullable
default @Nullable ItemBasedPrincipal getItemBasedPrincipal(@NotNull
                                                                     @NotNull java.lang.String principalOakPath)

Returns the ItemBasedPrincipal with the specified principalOakPath or null if no principal with that path exists.

Parameters:

principalOakPath - the Oak path of the ItemBasedPrincipal to retrieve

Returns:

return the requested principal or null

getGroupMembership

@NotNull
default @NotNull java.util.Set<java.security.acl.Group> getGroupMembership(@NotNull
                                                                                    @NotNull java.security.Principal principal)

Deprecated. use getMembershipPrincipals(Principal)

Returns an iterator over all group principals for which the given principal is either direct or indirect member of. Thus for any principal returned in the iterator Group.isMember(Principal) must return true.

Example:
If Principal is member of Group A, and Group A is member of Group B, this method will return Group A and Group B.

Parameters:

principal - the principal to return it's membership from.

Returns:

an iterator returning all groups the given principal is member of.

See Also:

Group.isMember(java.security.Principal)

getMembershipPrincipals

@NotNull
default @NotNull java.util.Set<java.security.Principal> getMembershipPrincipals(@NotNull
                                                                                         @NotNull java.security.Principal principal)

Returns an iterator over all group principals for which the given principal is either direct or indirect member of. Thus for any principal returned in the iterator GroupPrincipal.isMember(Principal) must return true.

Example:
If Principal is member of Group A, and Group A is member of Group B, this method will return Group A and Group B.

Parameters:

principal - the principal to return it's membership from.

Returns:

an iterator returning all groups the given principal is member of.

See Also:

GroupPrincipal.isMember(java.security.Principal)

getPrincipals

@NotNull
@NotNull java.util.Set<? extends java.security.Principal> getPrincipals(@NotNull
                                                                                 @NotNull java.lang.String userID)

Tries to resolve the specified userID to a valid principal and it's group membership. This method returns an empty set if the specified ID cannot be resolved.

Parameters:

userID - A userID.

Returns:

The set of principals associated with the specified userID or an empty set if it cannot be resolved.

findPrincipals

@NotNull
@NotNull java.util.Iterator<? extends java.security.Principal> findPrincipals(@Nullable
                                                                                       @Nullable java.lang.String nameHint,
                                                                                       int searchType)

Find the principals that match the specified nameHint and search type.

Parameters:

nameHint - A name hint to use for non-exact matching.

searchType - Limit the search to certain types of principals. Valid values are any of

• PrincipalManager.SEARCH_TYPE_ALL

• PrincipalManager.SEARCH_TYPE_NOT_GROUP

• PrincipalManager.SEARCH_TYPE_GROUP

Returns:

An iterator of principals.

findPrincipals

@NotNull
default @NotNull java.util.Iterator<? extends java.security.Principal> findPrincipals(@Nullable
                                                                                               @Nullable java.lang.String nameHint,
                                                                                               boolean fullText,
                                                                                               int searchType,
                                                                                               long offset,
                                                                                               long limit)

Find the principals that match the specified nameHint and search type.

Parameters:

nameHint - A name hint to use for non-exact matching.

fullText - hint to use a full text query for search

searchType - Limit the search to certain types of principals. Valid values are any of

• PrincipalManager.SEARCH_TYPE_ALL

• PrincipalManager.SEARCH_TYPE_NOT_GROUP

• PrincipalManager.SEARCH_TYPE_GROUP

offset - Offset from where to start returning results. 0 for no offset.

limit - Maximal number of results to return. -1 for no limit.

Returns:

An iterator of principals.

Throws:

java.lang.IllegalArgumentException - if offset is negative

findPrincipals

@NotNull
@NotNull java.util.Iterator<? extends java.security.Principal> findPrincipals(int searchType)

Find all principals that match the search type.

Parameters:

searchType - Limit the search to certain types of principals. Valid values are any of

• PrincipalManager.SEARCH_TYPE_ALL

• PrincipalManager.SEARCH_TYPE_NOT_GROUP

• PrincipalManager.SEARCH_TYPE_GROUP

Returns:

An iterator of principals.