Package net.shibboleth.idp.authn.context

Class AuthenticationContext

    • Field Detail

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

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

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

      • AuthenticationContext

        public AuthenticationContext()
        Constructor.

    • Method Detail

      • 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

      • 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

      • 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