Package net.shibboleth.idp.authn.context

# Class RequestedPrincipalContext

java.lang.Object
org.opensaml.messaging.context.BaseContext
net.shibboleth.idp.authn.context.RequestedPrincipalContext

All Implemented Interfaces:
  `Iterable<BaseContext>`

public final class RequestedPrincipalContext extends BaseContext
A context that holds information about an authentication request's requirement for a specific custom `Principal`.

Authentication protocols with features for requesting specific forms of authentication will populate this context type with an expression of those requirements in the form of a protocol-specific operator string and an ordered list of custom `Principal` objects.

During the authentication process, interactions with `PrincipalSupportingComponent`-supporting objects will depend on them satisfying context requirements, via the use of registered `PrincipalEvalPredicateFactory` objects.

Upon successful authentication the most appropriate "matching" `Principal` will be saved back to this context for use in generating a protocol response.

Parent:
  `AuthenticationContext`
Added:
  Before the authentication process begins

## Nested Class Summary

## Nested classes/interfaces inherited from class org.opensaml.messaging.context.BaseContext

`BaseContext.ContextSetNoRemoveIteratorDecorator, BaseContext.DeprecatedContextClassNameLookAside`

## Field Summary

Fields
Modifier and Type
Field
Description
`private PrincipalEvalPredicateFactoryRegistry`
`evalRegistry`
The registry of predicate factories for custom principal evaluation.
`private boolean`
`imposedLocally`
Whether the requirement was applied due to local policy?
`private Principal`
`matchingPrincipal`
The principal that satisfied the request, if any.
`private String`
`operatorString`
Comparison operator specific to request protocol.
`private List<Principal>`
`requestedPrincipals`
The principals reflecting the request requirements.

## Constructor Summary

Constructors
Constructor
Description
`RequestedPrincipalContext()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`Principal`
`getMatchingPrincipal()`
Get the principal that matched the request's requirements, if any.
`String`
`getOperator()`
Get the comparison operator for matching requested principals.
`PrincipalEvalPredicate`
`getPredicate(Principal principal)`
Get a predicate to apply based on a principal type and the content of this context.
`PrincipalEvalPredicateFactoryRegistry`
`getPrincipalEvalPredicateFactoryRegistry()`
Get the registry of predicate factories for custom principal evaluation.
`List<Principal>`
`getRequestedPrincipals()`
Get an immutable list of principals reflecting the request requirements.
`boolean`
`isAcceptable(Collection<Principal> principals)`
Helper method that evaluates `Principal` objects against this context to determine if the input is compatible with it.
`boolean`
`isAcceptable(PrincipalSupportingComponent component)`
Helper method that evaluates a `PrincipalSupportingComponent` against this context to determine if the input is compatible with it.
`<T extends Principal>
boolean`
`isAcceptable(T principal)`
Helper method that evaluates a `Principal` object against this context to determine if the input is compatible with it.
`boolean`
`isImposedLocally()`
Get whether the context was populated in response to a requirement applied by IdP policy.
`RequestedPrincipalContext`
`setImposedLocally(boolean flag)`
Set whether the context was populated in response to a requirement applied by IdP policy.
`RequestedPrincipalContext`
`setMatchingPrincipal(Principal principal)`
Set the principal that matched the request's requirements, if any.
`RequestedPrincipalContext`
`setOperator(String operator)`
Set the comparison operator for matching requested principals.
`RequestedPrincipalContext`
`setPrincipalEvalPredicateFactoryRegistry(PrincipalEvalPredicateFactoryRegistry registry)`
Set the registry of predicate factories for custom principal evaluation.
`RequestedPrincipalContext`
`setRequestedPrincipals(List<Principal> principals)`
Set list of principals reflecting the request requirements.

### Methods inherited from class org.opensaml.messaging.context.BaseContext

`addSubcontext, addSubcontext, clearSubcontexts, containsSubcontext, createSubcontext, ensureSubcontext, ensureSubcontext, getParent, getSubcontext, getSubcontext, getSubcontext, getSubcontext, iterator, removeFromParent, removeSubcontext, removeSubcontext, setParent`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Field Details

### evalRegistry

@Nonnull private PrincipalEvalPredicateFactoryRegistry evalRegistry
The registry of predicate factories for custom principal evaluation.

### operatorString

@Nullable private String operatorString
Comparison operator specific to request protocol.

### requestedPrincipals

@Nonnull private List<Principal> requestedPrincipals
The principals reflecting the request requirements.

### imposedLocally

private boolean imposedLocally
Whether the requirement was applied due to local policy?

### matchingPrincipal

@Nullable private Principal matchingPrincipal
The principal that satisfied the request, if any.

## Constructor Details

### RequestedPrincipalContext

public RequestedPrincipalContext()
Constructor.

## Method Details

### getPrincipalEvalPredicateFactoryRegistry

@Nonnull public PrincipalEvalPredicateFactoryRegistry getPrincipalEvalPredicateFactoryRegistry()
Get the registry of predicate factories for custom principal evaluation.

Returns:
  predicate factory registry
Since:
  3.3.0

### setPrincipalEvalPredicateFactoryRegistry

@Nonnull public RequestedPrincipalContext setPrincipalEvalPredicateFactoryRegistry(@Nonnull PrincipalEvalPredicateFactoryRegistry registry)
Set the registry of predicate factories for custom principal evaluation.

Parameters:
  `registry` - predicate factory registry
Returns:
  this context
Since:
  3.3.0

### getOperator

@Nullable @NotEmpty public String getOperator()
Get the comparison operator for matching requested principals.

Returns:
  comparison operator

### setOperator

@Nonnull public RequestedPrincipalContext setOperator(@Nullable @NotEmpty String operator)
Set the comparison operator for matching requested principals.

Parameters:
  `operator` - comparison operator
Returns:
  this context

### getRequestedPrincipals

@Nonnull @Unmodifiable @NotLive public List<Principal> getRequestedPrincipals()
Get an immutable list of principals reflecting the request requirements.

Returns:
  immutable list of principals

### setRequestedPrincipals

@Nonnull public RequestedPrincipalContext setRequestedPrincipals(@Nonnull List<Principal> principals)
Set list of principals reflecting the request requirements.

Parameters:
  `principals` - list of principals
Returns:
  this context

### isImposedLocally

public boolean isImposedLocally()
Get whether the context was populated in response to a requirement applied by IdP policy.

A false value implies that an RP/SP's requirement resulted in the creation of this context.

Returns:
  true iff the context was populated due to local requirements applied by the IdP
Since:
  5.2.0

### setImposedLocally

@Nonnull public RequestedPrincipalContext setImposedLocally(boolean flag)
Set whether the context was populated in response to a requirement applied by IdP policy.

Parameters:
  `flag` - flag to set
Returns:
  this context
Since:
  5.2.0

### getMatchingPrincipal

@Nullable public Principal getMatchingPrincipal()
Get the principal that matched the request's requirements, if any.

Returns:
  a matching principal, or null

### setMatchingPrincipal

@Nonnull public RequestedPrincipalContext setMatchingPrincipal(@Nullable Principal principal)
Set the principal that matched the request's requirements, if any.

Parameters:
  `principal` - a matching principal, or null
Returns:
  this context

### getPredicate

@Nullable public PrincipalEvalPredicate getPredicate(@Nonnull Principal principal)
Get a predicate to apply based on a principal type and the content of this context.

Parameters:
  `principal` - principal to obtain predicate for
Returns:
  predicate or null

### isAcceptable

public boolean isAcceptable(@Nonnull PrincipalSupportingComponent component)
Helper method that evaluates a `PrincipalSupportingComponent` against this context to determine if the input is compatible with it.

Parameters:
  `component` - component to evaluate
Returns:
  true iff the input is compatible with the requested authentication requirements
Since:
  3.3.0

### isAcceptable

public boolean isAcceptable(@Nonnull Collection<Principal> principals)
Helper method that evaluates `Principal` objects against this context to determine if the input is compatible with it.

Parameters:
  `principals` - principal(s) to evaluate
Returns:
  true iff the input is compatible with the requested authentication requirements
Since:
  3.3.0

### isAcceptable

public <T extends Principal> boolean isAcceptable(@Nonnull T principal)
Helper method that evaluates a `Principal` object against this context to determine if the input is compatible with it.

Type Parameters:
  `T` - type of principal
Parameters:
  `principal` - principal to evaluate
Returns:
  true iff the input is compatible with the requested authentication requirements