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, attribute.context.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

Field Summary

Fields

Modifier and Type	Field and Description
private 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 AuthenticationResult	authenticationResult A successful authentication result (the output of the attempted flow, if any).
private Map<String,AuthenticationFlowDescriptor>	availableFlows Flows that are known to the system.
private long	completionInstant Time, in milliseconds since the epoch, when authentication process completed.
private PrincipalEvalPredicateFactoryRegistry	evalRegistry Instance of registry used for auto-creation of RequestedPrincipalContext.
private com.google.common.base.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 AuthenticationResult	initialAuthenticationResult A successful "initial" authentication result from the current request's initial-authn phase.
private long	initiationInstant Time, in milliseconds since the epoch, when the authentication process started.
private Map<String,AuthenticationFlowDescriptor>	intermediateFlows Previously attempted flows (could be failures or intermediate results).
private boolean	isPassive Whether authentication must not involve subject interaction.
private long	maxAge Allowed time in ms since an AuthenticationResult was created that it can be reused for this request.
private Map<String,AuthenticationFlowDescriptor>	potentialFlows Flows that could potentially be used to authenticate the user.
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 Map<String,Object>	stateMap Storage map for interflow communication.

Constructor Summary

Constructors

Constructor and Description
AuthenticationContext() Constructor.

Method Summary

Methods

Modifier and Type	Method and Description
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.
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, 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, 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.
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.
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.
long	getCompletionInstant() Get the time, in milliseconds since the epoch, when the authentication process ended.
com.google.common.base.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.
AuthenticationResult	getInitialAuthenticationResult() Get the "initial" authentication result produced during this request's initial-authn phase.
long	getInitiationInstant() Get the time, in milliseconds since the epoch, 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.
long	getMaxAge() Get duration in milliseconds 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.
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	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(com.google.common.base.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	setInitialAuthenticationResult(AuthenticationResult result) Set the "initial" authentication result produced during this request's initial-authn phase.
AuthenticationContext	setIsPassive(boolean passive) Set whether subject interaction is allowed.
AuthenticationContext	setMaxAge(long age) Set duration in milliseconds 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.
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, getParent, getSubcontext, getSubcontext, getSubcontext, getSubcontext, isAutoCreateSubcontexts, iterator, removeSubcontext, removeSubcontext, setAutoCreateSubcontexts, setParent

Methods inherited from class java.lang.Object

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

Field Detail

initiationInstant

@Positive
private final long initiationInstant

Time, in milliseconds since the epoch, 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.

hintedName

@Nullable
private String hintedName

A non-normative hint some protocols support to indicate who the subject might be.

maxAge

@NonNegative
@Duration
private long maxAge

Allowed time in ms since an AuthenticationResult was created that it can be reused for this request.

fixedEventLookupStrategy

@Nullable
private com.google.common.base.Function<ProfileRequestContext,String> fixedEventLookupStrategy

Lookup strategy for a fixed event to return from validators for testing.

availableFlows

@Nonnull
@NonnullElements
private final Map<String,AuthenticationFlowDescriptor> availableFlows

Flows that are known to the system.

potentialFlows

@Nonnull
@NonnullElements
private final Map<String,AuthenticationFlowDescriptor> potentialFlows

Flows that could potentially be used to authenticate the user.

activeResults

@Nonnull
@NonnullElements
private final Map<String,AuthenticationResult> activeResults

Authentication results associated with an active session and available for (re)use.

intermediateFlows

@Nonnull
@NonnullElements
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.

initialAuthenticationResult

@Nullable
private AuthenticationResult initialAuthenticationResult

A successful "initial" authentication result from the current request's initial-authn phase.

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

@NonNegative
private long completionInstant

Time, in milliseconds since the epoch, when authentication process completed.

Constructor Detail

AuthenticationContext

public AuthenticationContext()

Constructor.

Method Detail

getInitiationInstant

@Positive
public long getInitiationInstant()

Get the time, in milliseconds since the epoch, when the authentication process started.

Returns:

time when the authentication process started

getActiveResults

@Nonnull
@NonnullElements
@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@NonnullElements
                                             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
@NonnullElements
@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
@NonnullElements
@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
@NonnullElements
@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

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.

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

@NonNegative
@Duration
public long getMaxAge()

Get duration in milliseconds since an AuthenticationResult was created that allows it to be reused for this request.

If zero, no constraint is applied.

Returns:

duration in milliseconds, or zero

Since:

3.4.0

setMaxAge

@Nonnull
public AuthenticationContext setMaxAge(@NonNegative@Duration
                                      long age)

Set duration in milliseconds since an AuthenticationResult was created that allows it to be reused for this request.

Set to zero to apply no constraint.

Parameters:

age - duration in milliseconds, or zero

Returns:

this context

Since:

3.4.0

getFixedEventLookupStrategy

@Nullable
public com.google.common.base.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
                                                        com.google.common.base.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
@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

getInitialAuthenticationResult

@Nullable
public AuthenticationResult getInitialAuthenticationResult()

Get the "initial" authentication result produced during this request's initial-authn phase.

This is used to make a previous result available for SSO even if the "forced authentication" feature is being used, since the result was produced as part of the same request.

Returns:

"initial" authentication result, if any

setInitialAuthenticationResult

@Nonnull
public AuthenticationContext setInitialAuthenticationResult(@Nullable
                                                           AuthenticationResult result)

Set the "initial" authentication result produced during this request's initial-authn phase.

Parameters:

result - "initial" authentication result, if any

Returns:

this authentication context

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

@NonNegative
public long getCompletionInstant()

Get the time, in milliseconds since the epoch, when the authentication process ended. A value of 0 indicates that authentication has not yet completed.

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@NonnullElements
                   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@NonnullElements
                                   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