Package org.jivesoftware.openfire.sasl.task

Interface Sasl2TaskContext

public interface Sasl2TaskContext
A view on one SASL2 negotiation, as seen by one Sasl2TaskProvider (and by the Sasl2Task instances that it creates). An instance is scoped to a single SASL2 negotiation attempt on a single session. When a peer restarts the negotiation by sending a new <authenticate/> element, all state represented by this context is discarded and a new context is created.

Attribute storage

The attribute methods provide scratch space that survives for the duration of the negotiation. Attributes are scoped to the provider that the context was created for: two providers that use the same attribute name will not see each other's values. This is the intended place to record, for example, that the peer opted in to a task in its <authenticate/> element, so that the decision can be acted on later, when Sasl2TaskProvider.getOfferedTasks(Sasl2TaskContext) is invoked.

Phases

A context is created when the peer's <authenticate/> element is processed, which is before SASL authentication has completed. During that phase isAuthenticated() returns false and getAuthorizationIdentity() returns null. Every other callback in this API is invoked only after SASL authentication has succeeded, at which point the authenticated identity is available.

Threading

Instances are not thread-safe. They are intended to be used only from the callbacks that receive them. The manager guarantees that no two callbacks for the same negotiation run concurrently.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    List<org.dom4j.Element>
    getAdvertisedFeatureElements()
    The stream feature elements that this provider contributed to the SASL2 <authentication/> stream feature for this session, as recorded when those features were advertised.
    Object
    getAttribute(String name)
    Returns a previously stored attribute value.
    <T> Optional<T>
    getAttribute(String name, Class<T> type)
    Returns a previously stored attribute value, if it is of the expected type.
    String
    getAuthorizationIdentity()
    The authorization identity (typically the username, without domain-part) that the peer authenticated as.
    String
    getChannelBindingType()
    The channel binding type that was negotiated, if the selected mechanism uses channel binding.
    List<String>
    getCompletedTaskNames()
    The names of the tasks that have already completed successfully during this negotiation, in the order in which they completed.
    Set<String>
    getOfferedTaskNames()
    The names of the tasks that were offered to the peer in the most recent <continue/> element.
    int
    getRound()
    The number of <continue/> elements that have been sent to the peer during this negotiation, including the one currently being assembled.
    String
    getSaslMechanismName()
    The name of the SASL mechanism that the peer selected, in upper case (for example SCRAM-SHA-256-PLUS).
    LocalSession
    getSession()
    The session that is performing the SASL2 negotiation.
    UserAgentInfo
    getUserAgentInfo()
    The user agent information (XEP-0388 § 2.2) that the peer supplied in its <authenticate/> element.
    boolean
    isAuthenticated()
    Indicates whether the SASL exchange itself has completed successfully.
    void
    setAttribute(String name, Object value)
    Stores an attribute value for the duration of this negotiation.

  • Method Details

    • getSession

      @Nonnull LocalSession getSession()
      The session that is performing the SASL2 negotiation. Note that this session is not (yet) authenticated: it does not have an authentication token, and its address is not yet the address of the authenticating user, even after isAuthenticated() starts returning true. Use getAuthorizationIdentity() to identify the user.
      Returns:
      the session that is negotiating (never null).

    • isAuthenticated

      boolean isAuthenticated()
      Indicates whether the SASL exchange itself has completed successfully. This returns false only during Sasl2TaskProvider.onAuthenticateReceived(Sasl2TaskContext, Element).
      Returns:
      true if SASL authentication has succeeded, otherwise false.

    • getAuthorizationIdentity

      @Nullable String getAuthorizationIdentity()
      The authorization identity (typically the username, without domain-part) that the peer authenticated as. Returns null when authentication has not yet completed, and also when the peer authenticated anonymously. Implementations that cannot operate on an anonymous session must check for null.
      Returns:
      the authenticated username, or null.

    • getSaslMechanismName

      @Nonnull String getSaslMechanismName()
      The name of the SASL mechanism that the peer selected, in upper case (for example SCRAM-SHA-256-PLUS). This is relevant to eligibility decisions: a task that requires the peer to know the account password must not be offered after a token-based authentication such as XEP-0484 FAST.

      Caveat: while isAuthenticated() is still false (e.g. when read from Sasl2TaskProvider.onAuthenticateReceived(Sasl2TaskContext, Element)) this is the mechanism name the peer claimed in its <authenticate/> element, not yet verified in any way. It is overwritten with the SASL layer's confirmed value only once authentication succeeds. Do not base an authorization or eligibility decision on this value before isAuthenticated() returns true; it is safe to use for anything read-only at that stage, such as logging or picking which opt-in parameters to parse.

      Returns:
      the SASL mechanism name (never null).

    • getChannelBindingType

      @Nullable String getChannelBindingType()
      The channel binding type that was negotiated, if the selected mechanism uses channel binding.
      Returns:
      a channel binding type (such as tls-exporter), or null if none was negotiated.

    • getUserAgentInfo

      @Nullable UserAgentInfo getUserAgentInfo()
      The user agent information (XEP-0388 § 2.2) that the peer supplied in its <authenticate/> element. This can be used to make a task conditional on a particular client, or to identify the device that a credential is being provisioned for. Note that user agent information is client-provided, and should not be trusted.
      Returns:
      user agent information, or null if the peer did not supply any.

    • getCompletedTaskNames

      @Nonnull List<String> getCompletedTaskNames()
      The names of the tasks that have already completed successfully during this negotiation, in the order in which they completed. A provider is expected to consult this when deciding what to offer: the manager will refuse to offer a task name that has already completed, but a provider that offers several alternatives (such as two second-factor methods) is responsible for withdrawing the alternatives once one of them has been performed.
      Returns:
      an immutable list of completed task names (never null, possibly empty).

    • getOfferedTaskNames

      @Nonnull Set<String> getOfferedTaskNames()
      The names of the tasks that were offered to the peer in the most recent <continue/> element.
      Returns:
      an immutable set of task names (never null, possibly empty).

    • getRound

      int getRound()
      The number of <continue/> elements that have been sent to the peer during this negotiation, including the one currently being assembled. The first invocation of Sasl2TaskProvider.getOfferedTasks(Sasl2TaskContext) in a negotiation sees a value of 1.
      Returns:
      the current round number.

    • getAdvertisedFeatureElements

      @Nonnull List<org.dom4j.Element> getAdvertisedFeatureElements()
      The stream feature elements that this provider contributed to the SASL2 <authentication/> stream feature for this session, as recorded when those features were advertised. This exists so that a provider can verify that a task the peer asks for was in fact offered to it, which prevents a peer from driving a negotiation that was never advertised. It mirrors the check that Openfire performs on SASL mechanism names (see OF-3273).
      Returns:
      detached copies of the elements this provider advertised (never null, possibly empty).

    • getAttribute

      @Nullable Object getAttribute(@Nonnull String name)
      Returns a previously stored attribute value.
      Parameters:
      name - the name of the attribute (cannot be null).
      Returns:
      the stored value, or null if no value is stored under this name.

    • getAttribute

      @Nonnull <T> Optional<T> getAttribute(@Nonnull String name, @Nonnull Class<T> type)
      Returns a previously stored attribute value, if it is of the expected type.
      Type Parameters:
      T - the expected type of the value.
      Parameters:
      name - the name of the attribute (cannot be null).
      type - the expected type of the value (cannot be null).
      Returns:
      the stored value, or an empty optional if absent or of another type.

    • setAttribute

      void setAttribute(@Nonnull String name, @Nullable Object value)
      Stores an attribute value for the duration of this negotiation.
      Parameters:
      name - the name of the attribute (cannot be null).
      value - the value to store. A null value removes any previously stored value.