com.holonplatform.auth

## Interface AuthContext

- All Superinterfaces:
    Authentication.AuthenticationNotifier, AuthenticationInspector

      public interface AuthContext
      extends AuthenticationInspector, Authentication.AuthenticationNotifier

  Represents the current authentication/authorization context.

  As an `AuthenticationInspector`, provides methods to check if an authentication is currently available and obtain the `Authentication` reference.

  Additionally, provides methods to perform authentication operations using an `AuthenticationToken`. As an `Authentication.AuthenticationNotifier`, supports `Authentication.AuthenticationListener` registration to be notified when an authentication request is successful, providing the `Authentication` reference.

  An AuthContext is tipically bound to a `Realm`, to which authentication operations and permission control strategies are delegated. In such situation, the authentication and authorization semantics are the same as those implemented by the `Realm` through the registered `Authenticator`s and `Authorizer`s. The `create(Realm)` static methods can be used to create a default `AuthContext` instance using a `Realm`. The `AuthContext.AuthenticationHolder` interface can be used to customize how the `Authentication` reference is managed by the AuthContext.

  Since:
    3.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `AuthContext.AuthenticationHolder` Auth context `Authentication` holder, which handles the current `Authentication` reference on behalf of the Auth context.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONTEXT_KEY` Default `Context` resource reference

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `Authentication` | `authenticate(AuthenticationToken authenticationToken)` Attempts to authenticate a user using given `AuthenticationToken`.
    `Authentication` | `authenticate(Message<?,?> message, String... schemes)` Attempts to authenticate using given `message` with the same contract as `authenticate(AuthenticationToken)`, using `Realm` registered `AuthenticationToken.AuthenticationTokenResolver`s for given message type, if any.
    `static AuthContext` | `create(Realm realm)` Create a default `AuthContext` using given `realm`.
    `static AuthContext` | `create(Realm realm, AuthContext.AuthenticationHolder authenticationHolder)` Create a default `AuthContext` using given `realm` and a custom `AuthContext.AuthenticationHolder` to handle the current `Authentication` reference.
    `static Optional<AuthContext>` | `getCurrent()` Convenience method to obtain the current `AuthContext` made available as `Context` resource, using default `ClassLoader`.
    `static AuthContext` | `require()` Requires the current `AuthContext`.
    `Optional<Authentication>` | `unauthenticate()` Unbound current `Authentication` from this AuthContext, if any

    - ### Methods inherited from interface com.holonplatform.auth.AuthenticationInspector

      `getAuthentication, isAuthenticated, isPermitted, isPermitted, isPermitted, isPermittedAny, isPermittedAny, isPermittedAny, requireAuthentication`

    - ### Methods inherited from interface com.holonplatform.auth.Authentication.AuthenticationNotifier

      `addAuthenticationListener, removeAuthenticationListener`

- - ### Field Detail

    - #### CONTEXT_KEY

          static final String CONTEXT_KEY

      Default `Context` resource reference

  - ### Method Detail

    - #### authenticate

          Authentication authenticate(AuthenticationToken authenticationToken)
                               throws AuthenticationException

      Attempts to authenticate a user using given `AuthenticationToken`.

      If the authentication is successful, an `Authentication` instance is stored in this AuthContext and can be retrieved using `AuthenticationInspector.getAuthentication()`. That Authentication instance is also returned by this method.

      If authentication is not successful, a suitable exception is thrown.

      Parameters:
        `authenticationToken` - the authentication request token
      Returns:
        The `Authentication` instance result of authentication process
      Throws:
        `AuthenticationException` - Authentication failed

    - #### authenticate

          Authentication authenticate(Message<?,?> message,
                                      String... schemes)
                               throws AuthenticationException

      Attempts to authenticate using given `message` with the same contract as `authenticate(AuthenticationToken)`, using `Realm` registered `AuthenticationToken.AuthenticationTokenResolver`s for given message type, if any.

      If the authentication is successful, an `Authentication` instance is stored in this AuthContext and can be retrieved using `AuthenticationInspector.getAuthentication()`. That Authentication instance is also returned by this method.

      If authentication is not successful, a suitable exception is thrown.

      Parameters:
        `message` - Authentication request message
        `schemes` - Optional authentication schemes to use. If not null or empty, only `AuthenticationToken.AuthenticationTokenResolver`s bound to given scheme names will be used
      Returns:
        he `Authentication` instance result of authentication process
      Throws:
        `AuthenticationException` - Authentication failed

    - #### unauthenticate

          Optional<Authentication> unauthenticate()

      Unbound current `Authentication` from this AuthContext, if any
      Returns:
        Previous Authentication bound to this context, if any. An empty Optional otherwise.

    - #### getCurrent

          static Optional<AuthContext> getCurrent()

      Convenience method to obtain the current `AuthContext` made available as `Context` resource, using default `ClassLoader`.

      See `Context.resource(String, Class)` for details about context resources availability conditions.

      Returns:
        Optional AuthContext, empty if not available as context resource

    - #### require

          static AuthContext require()

      Requires the current `AuthContext`. If not available using `getCurrent()`, an `IllegalStateException` is thrown.
      Returns:
        Current AuthContext
      Throws:
        `IllegalStateException` - AuthContext is not available as a `Context` resource

    - #### create

          static AuthContext create(Realm realm)

      Create a default `AuthContext` using given `realm`.
      Parameters:
        `realm` - The `Realm` which acts as `Authenticator` and `Authorizer` (not null)
      Returns:
        A new `AuthContext` instance

    - #### create

          static AuthContext create(Realm realm,
                                    AuthContext.AuthenticationHolder authenticationHolder)

      Create a default `AuthContext` using given `realm` and a custom `AuthContext.AuthenticationHolder` to handle the current `Authentication` reference.
      Parameters:
        `realm` - The `Realm` Realm which acts as `Authenticator` and `Authorizer` (not null)
        `authenticationHolder` - The `AuthContext.AuthenticationHolder` to which the current `Authentication` handling is delegated (not null)
      Returns:
        A new `AuthContext` instance

Copyright © 2019 The Holon Platform. All rights reserved.