com.holonplatform.auth

## Interface AuthContext

- All Superinterfaces:
    Authentication.AuthenticationNotifier

      public interface AuthContext
      extends Authentication.AuthenticationNotifier

  Represents current authentication/authorization context, typically bound to an application session or a service request.

  The AuthContext stores an `Authentication` obtained through an `Authenticator` using an AuthenticationToken. The `authenticate(AuthenticationToken)` method is provided to perform an authentication operation. As opposite, the `unauthenticate()` method removes any authentication informations from the AuthContext.

  The `getAuthentication()` method can be used to check whether an Authentication is currently bound to AuthContext and obtain it.

  A list of authorization control methods are provided to perform access control decisions using current context Authentication.

  Extends `Authentication.AuthenticationNotifier` to allow `Authentication.AuthenticationListener` registration.

  Since:
    3.0.0

- - ### 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`.
    `Optional<Authentication>` | `getAuthentication()` Get current Authentication in this context.
    `static Optional<AuthContext>` | `getCurrent()` Convenience method to obtain the current `AuthContext` made available as `Context` resource, using default `ClassLoader`.
    `default boolean` | `isAuthenticated()` Gets whether this `AuthContext` is authenticated, i.e. an `Authentication` is available.
    `boolean` | `isPermitted(Collection<Permission> permissions)` Check if current Authentication has all specified permission/s using a Collection If no Authentication in bound to this context, always returns `false`.
    `boolean` | `isPermitted(Permission... permissions)` Check if current Authentication has all specified permission/s.
    `boolean` | `isPermitted(String... permissions)` Check if current Authentication has all specified permission/s using String permission form.
    `boolean` | `isPermittedAny(Collection<Permission> permissions)` Check if current Authentication has any of specified permission/s using a Collection If no Authentication in bound to this context, always returns `false`.
    `boolean` | `isPermittedAny(Permission... permissions)` Check if current Authentication has any of specified permission/s If no Authentication in bound to this context, always returns `false`.
    `boolean` | `isPermittedAny(String... permissions)` Check if current Authentication has any of specified permission/s using String permission form.
    `Optional<Authentication>` | `unauthenticate()` Unbound current `Authentication` from this AuthContext, if any

    - ### 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

    - #### getAuthentication

          Optional<Authentication> getAuthentication()

      Get current Authentication in this context.

      Principals are authenticated using `authenticate(AuthenticationToken)`. When authentication process is successful, an `Authentication` is bound to this AuthContext and can be obtained using this method.

      Returns:
        Optional Authentication, an empty Optional is returned if no `Authentication` is bound to this AuthContext

    - #### isAuthenticated

          default boolean isAuthenticated()

      Gets whether this `AuthContext` is authenticated, i.e. an `Authentication` is available.
      Returns:
        `true` if this `AuthContext` is authenticated, `false` otherwise

    - #### 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 `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 `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.

    - #### isPermitted

          boolean isPermitted(Permission... permissions)

      Check if current Authentication has all specified permission/s.

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has all specified permission

    - #### isPermitted

          boolean isPermitted(String... permissions)

      Check if current Authentication has all specified permission/s using String permission form.

      String permission match against Authentication `Permission`s will be performed using `Permission.getPermission()` method.

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has all specified permission

    - #### isPermittedAny

          boolean isPermittedAny(Permission... permissions)

      Check if current Authentication has any of specified permission/s

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has any of specified permission

    - #### isPermittedAny

          boolean isPermittedAny(String... permissions)

      Check if current Authentication has any of specified permission/s using String permission form.

      String permission match against Authentication `Permission`s will be performed using `Permission.getPermission()` method.

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has any of specified permission

    - #### isPermitted

          boolean isPermitted(Collection<Permission> permissions)

      Check if current Authentication has all specified permission/s using a Collection

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has all specified permission

    - #### isPermittedAny

          boolean isPermittedAny(Collection<Permission> permissions)

      Check if current Authentication has any of specified permission/s using a Collection

      If no Authentication in bound to this context, always returns `false`.

      Parameters:
        `permissions` - Permissions to check
      Returns:
        `true` if current Authentication has any of specified permission

    - #### 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

    - #### create

          static AuthContext create(Realm realm)

      Create a default `AuthContext` using given `realm`.
      Parameters:
        `realm` - Realm which acts as `Authenticator` and `Authorizer`
      Returns:
        New `AuthContext` instance

Copyright © 2017 The Holon Platform. All rights reserved.