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

  • 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

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

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

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

    • checkProxyRestrictions

      private boolean checkProxyRestrictions(@Nullable @NonnullElements 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