Package net.shibboleth.idp.authn.context

# Class AuthenticationContext

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

All Implemented Interfaces:
  `Iterable<BaseContext>`

public final class AuthenticationContext extends BaseContext
A context representing the state of an authentication attempt, this is the primary input/output context for the action flow responsible for authentication, and within that flow, the individual flows that carry out a specific kind of authentication.

Parent:
  `ProfileRequestContext`
Child:
  `RequestedPrincipalContext`, `AttributeContext`, `UsernameContext`, `UsernamePasswordContext`, `UserAgentContext`, `CertificateContext`, `ExternalAuthenticationContext`, `KerberosTicketContext`, `LDAPResponseContext`, `AuthenticationErrorContext`, `AuthenticationWarningContext`
Added:
  Before authentication flow runs

## 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 final Map<String,AuthenticationResult>`
`activeResults`
Authentication results associated with an active session and available for (re)use.
`private AuthenticationFlowDescriptor`
`attemptedFlow`
Authentication flow being attempted to authenticate the user.
`private String`
`authenticatingAuthority`
Name of a proxied authentication source to use.
`private AuthenticationResult`
`authenticationResult`
A successful authentication result (the output of the attempted flow, if any).
`private final Map<String,AuthenticationFlowDescriptor>`
`availableFlows`
Flows that are known to the system.
`private Instant`
`completionInstant`
Time when authentication process completed.
`private PrincipalEvalPredicateFactoryRegistry`
`evalRegistry`
Instance of registry used for auto-creation of `RequestedPrincipalContext`.
`private Function<ProfileRequestContext,String>`
`fixedEventLookupStrategy`
Lookup strategy for a fixed event to return from validators for testing.
`private boolean`
`forceAuthn`
Whether to require fresh subject interaction to succeed.
`private String`
`hintedName`
A non-normative hint some protocols support to indicate who the subject might be.
`private final Instant`
`initiationInstant`
Time when the authentication process started.
`private final Map<String,AuthenticationFlowDescriptor>`
`intermediateFlows`
Previously attempted flows (could be failures or intermediate results).
`private boolean`
`isPassive`
Whether authentication must not involve subject interaction.
`private Duration`
`maxAge`
Allowed time since an `AuthenticationResult` was created that it can be reused for this request.
`private final Map<String,AuthenticationFlowDescriptor>`
`potentialFlows`
Flows that could potentially be used to authenticate the user.
`private Set<String>`
`proxiableAuthorities`
Allowable proxied sources of authority.
`private Integer`
`proxyCount`
Allowable proxy count upstream.
`private String`
`requiredName`
A normative hint some protocols support to indicate who the subject MUST be.
`private boolean`
`resultCacheable`
Result may be cached for reuse in the normal way.
`private String`
`signaledFlowId`
Signals authentication flow to run next, to influence selection logic.
`private final Map<String,Object>`
`stateMap`
Storage map for interflow communication.

## Constructor Summary

Constructors
Constructor
Description
`AuthenticationContext()`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`addRequestedPrincipalContext(String operator, String className, String principal, boolean replace)`
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.
`boolean`
`addRequestedPrincipalContext(String operator, String className, Collection<String> principals, boolean replace)`
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.
`boolean`
`addRequestedPrincipalContext(String operator, Principal principal, boolean replace)`
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.
`boolean`
`addRequestedPrincipalContext(String operator, List<Principal> principals, boolean replace)`
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.
`private boolean`
`checkProxyRestrictions(Collection<ProxyAuthenticationPrincipal> principals)`
Check for proxy restrictions and evaluate them against the associated `RelyingPartyContext`.
`Map<String,AuthenticationResult>`
`getActiveResults()`
Get previous authentication results currently active for the subject.
`AuthenticationFlowDescriptor`
`getAttemptedFlow()`
Get the authentication flow that was attempted in order to authenticate the user.
`String`
`getAuthenticatingAuthority()`
Gets the identifier or location, depending on protocol, of an authentication system to use as a proxied source of authentication.
`AuthenticationResult`
`getAuthenticationResult()`
Get the authentication result produced by the attempted flow, or reused for SSO.
`Map<String,Object>`
`getAuthenticationStateMap()`
Get the map of intermediate state that flows can use to pass information amongst themselves.
`Map<String,AuthenticationFlowDescriptor>`
`getAvailableFlows()`
Get the set of flows known to the system overall.
`Instant`
`getCompletionInstant()`
Get the time when the authentication process ended.
`Function<ProfileRequestContext,String>`
`getFixedEventLookupStrategy()`
Get optional lookup strategy to return a fixed event to return from credential validation to exercise error and warning logic.
`String`
`getHintedName()`
Get a non-normative hint provided by the request about the user's identity.
`Instant`
`getInitiationInstant()`
Get the time when the authentication process started.
`Map<String,AuthenticationFlowDescriptor>`
`getIntermediateFlows()`
Get the set of flows that have been executed, successfully or otherwise, without producing a completed result.
`Duration`
`getMaxAge()`
Get duration since an `AuthenticationResult` was created that allows it to be reused for this request.
`Map<String,AuthenticationFlowDescriptor>`
`getPotentialFlows()`
Get the set of flows that could potentially be used for authentication.
`PrincipalEvalPredicateFactoryRegistry`
`getPrincipalEvalPredicateFactoryRegistry()`
Get the registry of predicate factories for custom principal evaluation.
`Set<String>`
`getProxiableAuthorities()`
Get a live set of the authorities to which proxying is suggested.
`Integer`
`getProxyCount()`
Get the allowable number of hops upstream to permit for proxied authentication.
`String`
`getRequiredName()`
Get a normative hint provided by the request about the user's identity.
`String`
`getSignaledFlowId()`
Get the flow ID signaled as the next selection.
`boolean`
`isAcceptable(Collection<Principal> principals)`
Helper method that evaluates `Principal` objects against a `RequestedPrincipalContext` child of this context, if present, to determine if the input is compatible with them.
`boolean`
`isAcceptable(PrincipalSupportingComponent component)`
Helper method that evaluates a `PrincipalSupportingComponent` against a `RequestedPrincipalContext` child of this context, if present, to determine if the input is compatible with it.
`<T extends Principal>
boolean`
`isAcceptable(T principal)`
Helper method that evaluates a `Principal` object against a `RequestedPrincipalContext` child of this context, if present, to determine if the input is compatible with it.
`boolean`
`isForceAuthn()`
Get whether to require fresh subject interaction to succeed.
`boolean`
`isPassive()`
Get whether subject interaction is allowed.
`boolean`
`isResultCacheable()`
Get whether the result is suitable for caching (such as in a session) for reuse.
`AuthenticationContext`
`setActiveResults(Iterable<AuthenticationResult> results)`
Set the authentication results currently active for the subject.
`AuthenticationContext`
`setAttemptedFlow(AuthenticationFlowDescriptor flow)`
Set the authentication flow that was attempted in order to authenticate the user.
`AuthenticationContext`
`setAuthenticatingAuthority(String authority)`
Sets the identifier or location, depending on protocol, of an authentication system to use as a proxied source of authentication.
`AuthenticationContext`
`setAuthenticationResult(AuthenticationResult result)`
Set the authentication result produced by the attempted flow, or reused for SSO.
`AuthenticationContext`
`setCompletionInstant()`
Set the completion time of the authentication attempt to the current time.
`AuthenticationContext`
`setFixedEventLookupStrategy(Function<ProfileRequestContext,String> strategy)`
Set optional lookup strategy to return a fixed event to return from credential validation to exercise error and warning logic.
`AuthenticationContext`
`setForceAuthn(boolean force)`
Set whether to require fresh subject interaction to succeed.
`AuthenticationContext`
`setHintedName(String hint)`
Set a non-normative hint provided by the request about the user's identity.
`AuthenticationContext`
`setIsPassive(boolean passive)`
Set whether subject interaction is allowed.
`AuthenticationContext`
`setMaxAge(Duration age)`
Set duration since an `AuthenticationResult` was created that allows it to be reused for this request.
`AuthenticationContext`
`setPrincipalEvalPredicateFactoryRegistry(PrincipalEvalPredicateFactoryRegistry registry)`
Set the registry of predicate factories for custom principal evaluation to inject into instances of `RequestedPrincipalContext` created via the `addRequestedPrincipalContext(String, List, boolean)` helper method.
`AuthenticationContext`
`setProxyCount(Integer count)`
Set the allowable number of hops upstream to permit for proxied authentication.
`AuthenticationContext`
`setRequiredName(String name)`
Set a normative hint provided by the request about the user's identity.
`void`
`setResultCacheable(boolean flag)`
Set whether the result is suitable for caching (such as in a session) for reuse.
`AuthenticationContext`
`setSignaledFlowId(String id)`
Set the flow ID signaled as the next selection.
`String`
`toString()`

### 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, wait, wait, wait`

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

`forEach, spliterator`

## Field Details

### initiationInstant

@Nonnull private final Instant initiationInstant
Time when the authentication process started.

### forceAuthn

private boolean forceAuthn
Whether to require fresh subject interaction to succeed.

### isPassive

private boolean isPassive
Whether authentication must not involve subject interaction.

### requiredName

@Nullable private String requiredName
A normative hint some protocols support to indicate who the subject MUST be.

### hintedName

@Nullable private String hintedName
A non-normative hint some protocols support to indicate who the subject might be.

### maxAge

@Nullable private Duration maxAge
Allowed time since an `AuthenticationResult` was created that it can be reused for this request.

### authenticatingAuthority

@Nullable private String authenticatingAuthority
Name of a proxied authentication source to use.

### proxyCount

@Nullable @NonNegative private Integer proxyCount
Allowable proxy count upstream.

### proxiableAuthorities

@Nonnull private Set<String> proxiableAuthorities
Allowable proxied sources of authority.

### fixedEventLookupStrategy

@Nullable private Function<ProfileRequestContext,String> fixedEventLookupStrategy
Lookup strategy for a fixed event to return from validators for testing.

### availableFlows

@Nonnull private final Map<String,AuthenticationFlowDescriptor> availableFlows
Flows that are known to the system.

### potentialFlows

@Nonnull private final Map<String,AuthenticationFlowDescriptor> potentialFlows
Flows that could potentially be used to authenticate the user.

### activeResults

@Nonnull private final Map<String,AuthenticationResult> activeResults
Authentication results associated with an active session and available for (re)use.

### intermediateFlows

@Nonnull private final Map<String,AuthenticationFlowDescriptor> intermediateFlows
Previously attempted flows (could be failures or intermediate results).

### evalRegistry

@Nullable private PrincipalEvalPredicateFactoryRegistry evalRegistry
Instance of registry used for auto-creation of `RequestedPrincipalContext`.

### attemptedFlow

@Nullable private AuthenticationFlowDescriptor attemptedFlow
Authentication flow being attempted to authenticate the user.

### signaledFlowId

@Nullable private String signaledFlowId
Signals authentication flow to run next, to influence selection logic.

### stateMap

@Nonnull private final Map<String,Object> stateMap
Storage map for interflow communication.

### authenticationResult

@Nullable private AuthenticationResult authenticationResult
A successful authentication result (the output of the attempted flow, if any).

### resultCacheable

private boolean resultCacheable
Result may be cached for reuse in the normal way.

### completionInstant

@Nullable private Instant completionInstant
Time when authentication process completed.

## Constructor Details

### AuthenticationContext

public AuthenticationContext()
Constructor.

## Method Details

### getInitiationInstant

@Nonnull public Instant getInitiationInstant()
Get the time when the authentication process started.

Returns:
  time when the authentication process started

### getActiveResults

@Nonnull @Live public Map<String,AuthenticationResult> getActiveResults()
Get previous authentication results currently active for the subject.

These should be used to identify SSO opportunities. Results produced during a particular authentication run should not be included in this collection.

Returns:
  authentication results currently active for the subject

### setActiveResults

@Nonnull public AuthenticationContext setActiveResults(@Nonnull Iterable<AuthenticationResult> results)
Set the authentication results currently active for the subject.

Parameters:
  `results` - authentication results currently active for the subject
Returns:
  this authentication context

### getAvailableFlows

@Nonnull @Live public Map<String,AuthenticationFlowDescriptor> getAvailableFlows()
Get the set of flows known to the system overall.

Authentication flows supplied by the configuration and gradually filtered down to a collection that can be used to authenticate the subject.

Returns:
  the available flows, independent of their potential for use at a given time
Since:
  3.3.0

### getPotentialFlows

@Nonnull @Live public Map<String,AuthenticationFlowDescriptor> getPotentialFlows()
Get the set of flows that could potentially be used for authentication.

Initially the same as `getAvailableFlows()`, it may be filtered down to a smaller set.

Returns:
  the potential flows

### getIntermediateFlows

@Nonnull @Live public Map<String,AuthenticationFlowDescriptor> getIntermediateFlows()
Get the set of flows that have been executed, successfully or otherwise, without producing a completed result.

This tracks flows that have already been run to avoid unintentional repeated attempts to run the same flow.

Returns:
  the intermediately executed flows

### getPrincipalEvalPredicateFactoryRegistry

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

This object is only needed when evaluating a `RequestedPrincipalContext`, so the presence of it at this level of the tree is solely for use by the `addRequestedPrincipalContext(String, List, boolean)` helper method.

Returns:
  predicate factory registry

### setPrincipalEvalPredicateFactoryRegistry

@Nonnull public AuthenticationContext setPrincipalEvalPredicateFactoryRegistry(@Nullable PrincipalEvalPredicateFactoryRegistry registry)
Set the registry of predicate factories for custom principal evaluation to inject into instances of `RequestedPrincipalContext` created via the `addRequestedPrincipalContext(String, List, boolean)` helper method.

It also propagates this object into any existing `RequestedPrincipalContext` subcontext.

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

### isPassive

public boolean isPassive()
Get whether subject interaction is allowed.

Flows that support this feature MUST be implemented with awareness of this value. If a flow doesn't examine this property, it should be marked as non-supporting or would have to be universally lacking in subject interaction.

Returns:
  whether subject interaction may occur

### setIsPassive

@Nonnull public AuthenticationContext setIsPassive(boolean passive)
Set whether subject interaction is allowed.

Parameters:
  `passive` - whether subject interaction may occur
Returns:
  this authentication context

### isForceAuthn

public boolean isForceAuthn()
Get whether to require fresh subject interaction to succeed.

Flows may not explicitly be aware of this property, but if they include any internal orchestration of other flows, then they MUST be aware of it to avoid reuse of previous results.

Returns:
  whether subject interaction must occur

### setForceAuthn

@Nonnull public AuthenticationContext setForceAuthn(boolean force)
Set whether to require fresh subject interaction to succeed.

Parameters:
  `force` - whether subject interaction must occur
Returns:
  this authentication context

### getRequiredName

@Nullable @NotEmpty public String getRequiredName()
Get a normative hint provided by the request about the user's identity.

This MUST BE a trustworthy value, and can only be set through some normative protocol machinery or with the understanding that it is subsequently a governing constraint on the canonical result of every flow.

Returns:
  the mandatory username
Since:
  4.1.0

### setRequiredName

@Nonnull public AuthenticationContext setRequiredName(@Nullable String name)
Set a normative hint provided by the request about the user's identity.

This MUST BE a trustworthy value, and can only be set through some normative protocol machinery or with the understanding that it is subsequently a governing constraint on the canonical result of every flow.

Parameters:
  `name` - the required username
Returns:
  this authentication context
Since:
  4.1.0

### getHintedName

@Nullable @NotEmpty public String getHintedName()
Get a non-normative hint provided by the request about the user's identity.

This is NOT a trustworthy value, but may be used to optimize the user experience. There should be no assumptions about the safety or format of this value, so care should be taken in using it.

Returns:
  the username hint

### setHintedName

@Nonnull public AuthenticationContext setHintedName(@Nullable String hint)
Set a non-normative hint provided by the request about the user's identity.

Parameters:
  `hint` - the username hint
Returns:
  this authentication context

### getMaxAge

@Nullable public Duration getMaxAge()
Get duration since an `AuthenticationResult` was created that allows it to be reused for this request.

If null, no constraint is applied.

Returns:
  duration
Since:
  3.4.0

### setMaxAge

@Nonnull public AuthenticationContext setMaxAge(@Nullable Duration age)
Set duration since an `AuthenticationResult` was created that allows it to be reused for this request.

Set to null to apply no constraint.

Parameters:
  `age` - duration
Returns:
  this context
Since:
  3.4.0

### getAuthenticatingAuthority

@Nullable public String getAuthenticatingAuthority()
Gets the identifier or location, depending on protocol, of an authentication system to use as a proxied source of authentication.

Returns:
  identifier/location of proxy authentication source
Since:
  4.0.0

### setAuthenticatingAuthority

@Nonnull public AuthenticationContext setAuthenticatingAuthority(@Nullable String authority)
Sets the identifier or location, depending on protocol, of an authentication system to use as a proxied source of authentication.

Used to track the result of a hardcoded or discovery-driven determination of a third party authentication source.

Parameters:
  `authority` - identifier/location of proxy authentication source
Returns:
  this context
Since:
  4.0.0

### getProxyCount

@Nullable @NonNegative public Integer getProxyCount()
Get the allowable number of hops upstream to permit for proxied authentication.

This follows SAML semantics, but is not strictly specific to it.

Returns:
  proxy count, null for no limit, zero for no proxying
Since:
  4.0.0

### setProxyCount

@Nonnull public AuthenticationContext setProxyCount(@Nullable @NonNegative Integer count)
Set the allowable number of hops upstream to permit for proxied authentication.

Parameters:
  `count` - proxy count, null for no limit, zero for no proxying
Returns:
  this context
Since:
  4.0.0

### getProxiableAuthorities

@Nonnull @Live public Set<String> getProxiableAuthorities()
Get a live set of the authorities to which proxying is suggested.

This follows SAML semantics and is non-critical, but is not strictly specific to it.

Returns:
  advisory set of authorities
Since:
  4.0.0

### getFixedEventLookupStrategy

@Nullable public Function<ProfileRequestContext,String> getFixedEventLookupStrategy()
Get optional lookup strategy to return a fixed event to return from credential validation to exercise error and warning logic.

Returns:
  lookup strategy, or null
Since:
  3.4.0

### setFixedEventLookupStrategy

@Nonnull public AuthenticationContext setFixedEventLookupStrategy(@Nullable Function<ProfileRequestContext,String> strategy)
Set optional lookup strategy to return a fixed event to return from credential validation to exercise error and warning logic.

Parameters:
  `strategy` - lookup strategy
Returns:
  this context
Since:
  3.4.0

### getAttemptedFlow

@Nullable public AuthenticationFlowDescriptor getAttemptedFlow()
Get the authentication flow that was attempted in order to authenticate the user.

This field will hold the flow being run while it is executing, and will continue to contain that value until/unless another flow is run. It is not set if an existing result was reused by the IdP's own machinery for SSO, and subsequent to authentication will inform as to the fact that SSO was or was not done, and which flow was used.

Returns:
  authentication flow that was attempted in order to authenticate the user

### setAttemptedFlow

@Nonnull public AuthenticationContext setAttemptedFlow(@Nullable AuthenticationFlowDescriptor flow)
Set the authentication flow that was attempted in order to authenticate the user.

Do not set if an existing result was reused for SSO.

Parameters:
  `flow` - authentication flow that was attempted in order to authenticate the user
Returns:
  this authentication context

### getSignaledFlowId

@Nullable @NotEmpty public String getSignaledFlowId()
Get the flow ID signaled as the next selection.

A login flow may set this value to signal the authentication flow to transfer control immediately to another login flow instead of proceeding in ordered fashion picking flows to attempt. Generally it is more effective to actually call a login flow from within another flow and subsume it than to rely on this signaling mechanism.

Returns:
  ID of flow to run next

### setSignaledFlowId

@Nonnull public AuthenticationContext setSignaledFlowId(@Nullable String id)
Set the flow ID signaled as the next selection.

Parameters:
  `id` - ID of flow to run next
Returns:
  this authentication context

### getAuthenticationStateMap

@Nonnull @NullableElements @Live public Map<String,Object> getAuthenticationStateMap()
Get the map of intermediate state that flows can use to pass information amongst themselves.

This is a simple string-based map of attributes that can be used to carry information between login flows or for subsequent use, without relying on native Spring WebFlow mechanisms.

Returns:
  the state map

### getAuthenticationResult

@Nullable public AuthenticationResult getAuthenticationResult()
Get the authentication result produced by the attempted flow, or reused for SSO.

The last flow to complete successfully should have its results stored here. Composite flows should be aware that they may need to preserve intermediate results, and the only get to produce one single result at the end.

Returns:
  authentication result, if any

### setAuthenticationResult

@Nonnull public AuthenticationContext setAuthenticationResult(@Nullable AuthenticationResult result)
Set the authentication result produced by the attempted flow, or reused for SSO.

Parameters:
  `result` - authentication result, if any
Returns:
  this authentication context

### isResultCacheable

public boolean isResultCacheable()
Get whether the result is suitable for caching (such as in a session) for reuse.

Allows flows to indicate at runtime if their results should be cached for future use, or thrown away after a single use.

Returns:
  true iff the result may be cached/reused, subject to other policy

### setResultCacheable

public void setResultCacheable(boolean flag)
Set whether the result is suitable for caching (such as in a session) for reuse.

Parameters:
  `flag` - flag to set

### getCompletionInstant

@Nullable public Instant getCompletionInstant()
Get the time when the authentication process ended.

Returns:
  time when the authentication process ended

### setCompletionInstant

@Nonnull public AuthenticationContext setCompletionInstant()
Set the completion time of the authentication attempt to the current time.

Returns:
  this authentication context

### isAcceptable

public boolean isAcceptable(@Nonnull PrincipalSupportingComponent component)
Helper method that evaluates a `PrincipalSupportingComponent` against a `RequestedPrincipalContext` child of this context, if present, 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 or if no such requirements have been imposed

### isAcceptable

public boolean isAcceptable(@Nonnull Collection<Principal> principals)
Helper method that evaluates `Principal` objects against a `RequestedPrincipalContext` child of this context, if present, to determine if the input is compatible with them.

Parameters:
  `principals` - principal(s) to evaluate
Returns:
  true iff the input is compatible with the requested authentication requirements or if no such requirements have been imposed

### isAcceptable

public <T extends Principal> boolean isAcceptable(@Nonnull T principal)
Helper method that evaluates a `Principal` object against a `RequestedPrincipalContext` child of this context, if present, 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 or if no such requirements have been imposed

### addRequestedPrincipalContext

public boolean addRequestedPrincipalContext(@Nonnull @NotEmpty String operator, @Nonnull @NotEmpty String className, @Nonnull @NotEmpty String principal, boolean replace) throws Exception
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.

Parameters:
  `operator` - matching operator
  `className` - name of class to wrap principal names
  `principal` - name of principal to request
  `replace` - whether to replace an existing context or simply return false
Returns:
  true iff a new context was created
Throws:
  `Exception` - if the principal class can't be loaded or instantiated as required

### addRequestedPrincipalContext

public boolean addRequestedPrincipalContext(@Nonnull @NotEmpty String operator, @Nonnull @NotEmpty String className, @Nonnull Collection<String> principals, boolean replace) throws Exception
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.

Parameters:
  `operator` - matching operator
  `className` - name of class to wrap principal names
  `principals` - names of principals to request
  `replace` - whether to replace an existing context or simply return false
Returns:
  true iff a new context was created
Throws:
  `Exception` - if the principal class can't be loaded or instantiated as required

### addRequestedPrincipalContext

public boolean addRequestedPrincipalContext(@Nonnull @NotEmpty String operator, @Nonnull Principal principal, boolean replace)
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.

Parameters:
  `operator` - matching operator
  `principal` - principal to request
  `replace` - whether to replace an existing context or simply return false
Returns:
  true iff a new context was created

### addRequestedPrincipalContext

public boolean addRequestedPrincipalContext(@Nonnull @NotEmpty String operator, @Nonnull List<Principal> principals, boolean replace)
Add (or replace) a `RequestedPrincipalContext` as a child of this context using the supplied parameters and the previously established `PrincipalEvalPredicateFactoryRegistry` for comparison handling.

Parameters:
  `operator` - matching operator
  `principals` - principals to request
  `replace` - whether to replace an existing context or simply return false
Returns:
  true iff a new context was created

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### checkProxyRestrictions

private boolean checkProxyRestrictions(@Nullable Collection<ProxyAuthenticationPrincipal> principals)
Check for proxy restrictions and evaluate them against the associated `RelyingPartyContext`.

Parameters:
  `principals` - the proxy restrictions
Returns:
  true iff proxying is permissible or inapplicable