io.undertow.security.api

## Interface SecurityContext

All Known Subinterfaces:
  AuthenticationMechanismContext

All Known Implementing Classes:
  AbstractSecurityContext, SecurityContextImpl

    public interface SecurityContext

The security context. This context is attached to the exchange and holds all security related information.

Author:
  Stuart Douglas, Darran Lofthouse
See Also:
  `SecurityContextImpl`

### Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
`void` `addAuthenticationMechanism(AuthenticationMechanism mechanism)` Deprecated. This method is now only applicable to `SecurityContext` implementations that also implement the `AuthenticationMechanismContext` interface.
`boolean` `authenticate()` Performs authentication on the request.
`void` `authenticationComplete(Account account, String mechanismName, boolean cachingRequired)` Called by the `AuthenticationMechanism` to indicate that an account has been successfully authenticated.
`void` `authenticationFailed(String message, String mechanismName)` Called by the `AuthenticationMechanism` to indicate that an authentication attempt has failed.
`Account` `getAuthenticatedAccount()` Obtain the `Account` for the currently authenticated identity.
`List<AuthenticationMechanism>` `getAuthenticationMechanisms()` Deprecated. Obtaining lists of mechanisms is discouraged, however there should not be a need to call this anyway.
`IdentityManager` `getIdentityManager()` Deprecated. Authentication mechanisms that rely on the `IdentityManager` should instead hold their own reference to it.
`String` `getMechanismName()`
`boolean` `isAuthenticated()`
`boolean` `isAuthenticationRequired()` Returns true if authentication is required
`boolean` `login(String username, String password)` Attempts to log the user in using the provided credentials.
`void` `logout()` de-authenticates the current exchange.
`void` `registerNotificationReceiver(NotificationReceiver receiver)` Register a `NotificationReceiver` interested in receiving notifications for security events that happen on this SecurityContext.
`void` `removeNotificationReceiver(NotificationReceiver receiver)` Remove a previously registered `NotificationReceiver` from this SecurityContext.
`void` `setAuthenticationRequired()` Marks this request as requiring authentication.

### Method Detail

#### authenticate

    boolean authenticate()

Performs authentication on the request. If authentication is REQUIRED then setAuthenticationRequired() should be called before calling this method. If the result indicates that a response has been sent to the client then no further attempts should be made to modify the response. The caller of this method is responsible for ending the exchange. If this method returns `true` it can still have committed the response (e.g. form auth redirects back to the original page). Callers should check that the exchange has not been ended before proceeding.

Returns:
  `true` if either the request is successfully authenticated or if there is no failure validating the current request so that the request should continue to be processed, `false` if authentication was not completed and challenge has been prepared for the client.

#### login

    boolean login(String username,
                  String password)

Attempts to log the user in using the provided credentials. This result will be stored in the current `AuthenticatedSessionManager` (if any), so subsequent requests will automatically be authenticated as this user.

This operation may block

Parameters:
  `username` - The username
  `password` - The password
Returns:
  `true` if the login succeeded, false otherwise

#### logout

    void logout()

de-authenticates the current exchange.

#### setAuthenticationRequired

    void setAuthenticationRequired()

Marks this request as requiring authentication. Authentication challenge headers will only be sent if this method has been called. If `authenticate()` is called without first calling this method then the request will continue as normal even if the authentication was not successful.

#### isAuthenticationRequired

    boolean isAuthenticationRequired()

Returns true if authentication is required

Returns:
  `true` If authentication is required

#### addAuthenticationMechanism

    @Deprecated
    void addAuthenticationMechanism(AuthenticationMechanism mechanism)

Deprecated. This method is now only applicable to `SecurityContext` implementations that also implement the `AuthenticationMechanismContext` interface.
Adds an authentication mechanism to this context. When `authenticate()` is called mechanisms will be iterated over in the order they are added, and given a chance to authenticate the user.

Parameters:
  `mechanism` - The mechanism to add

#### getAuthenticationMechanisms

    @Deprecated
    List<AuthenticationMechanism> getAuthenticationMechanisms()

Deprecated. Obtaining lists of mechanisms is discouraged, however there should not be a need to call this anyway.

Returns:
  A list of all authentication mechanisms in this context

#### isAuthenticated

    boolean isAuthenticated()

Returns:
  true if a user has been authenticated for this request, false otherwise.

#### getAuthenticatedAccount

    Account getAuthenticatedAccount()

Obtain the `Account` for the currently authenticated identity.

Returns:
  The `Account` for the currently authenticated identity or `null` if no account is currently authenticated.

#### getMechanismName

    String getMechanismName()

Returns:
  The name of the mechanism that was used to authenticate

#### getIdentityManager

    @Deprecated
    IdentityManager getIdentityManager()

Deprecated. Authentication mechanisms that rely on the `IdentityManager` should instead hold their own reference to it.
Obtain the associated `IdentityManager` to use to make account verification decisions.

Returns:
  The associated `IdentityManager`

#### authenticationComplete

    void authenticationComplete(Account account,
                                String mechanismName,
                                boolean cachingRequired)

Called by the `AuthenticationMechanism` to indicate that an account has been successfully authenticated. Note: A successful verification of an account using the `IdentityManager` is not the same as a successful authentication decision, other factors could be taken into account to make the final decision.

Parameters:
  `account` - - The authenticated `Account`
  `mechanismName` - - The name of the mechanism used to authenticate the account.
  `cachingRequired` - - If this mechanism requires caching

#### authenticationFailed

    void authenticationFailed(String message,
                              String mechanismName)

Called by the `AuthenticationMechanism` to indicate that an authentication attempt has failed. This should only be called where an authentication attempt has truly failed, for authentication mechanisms where an additional round trip with the client is expected this should not be called. Where possible the failure message should contain the name of the identity that authentication was being attempted for, however as this is not always possible to identify in advance a generic message may be all that can be reported.

Parameters:
  `message` - - The message describing the failure.
  `mechanismName` - - The name of the mechanism reporting the failure.

#### registerNotificationReceiver

    void registerNotificationReceiver(NotificationReceiver receiver)

Register a `NotificationReceiver` interested in receiving notifications for security events that happen on this SecurityContext.

Parameters:
  `receiver` - - The `NotificationReceiver` to register.

#### removeNotificationReceiver

    void removeNotificationReceiver(NotificationReceiver receiver)

Remove a previously registered `NotificationReceiver` from this SecurityContext. If the supplied receiver has not been previously registered this method will fail silently.

Parameters:
  `receiver` - - The `NotificationReceiver` to remove.