http://www.jboss.org/undertow-parent/undertow-core: Undertow (JBoss by Red Hat) 
/*
 * JBoss, Home of Professional Open Source.
 * Copyright 2014 Red Hat, Inc., and individual contributors
 * as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package io.undertow.security.api;

import io.undertow.security.idm.Account;
import io.undertow.security.idm.IdentityManager;

import java.util.List;


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

Author:Stuart Douglas, Darran Lofthouse
See Also:
/**
 * The security context.
 *
 * This context is attached to the exchange and holds all security related information.
 *
 * @author Stuart Douglas
 * @author <a href="mailto:darran.lofthouse@jboss.com">Darran Lofthouse</a>
 * @see io.undertow.security.impl.SecurityContextImpl
 */
public interface SecurityContext {

    /*
     * Methods Used To Run Authentication Process
     */

    
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.
/**
     * 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 <code>true</code> 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.
     *
     * @return <code>true</code> 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, <code>false</code> if authentication was not
     *         completed and challenge has been prepared for the client.
     */
    boolean authenticate();

    /*
     * API for Direct Control of Authentication
     */

    
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

Params:
  • username – The username
  • password – The password
Returns:true if the login succeeded, false otherwise
/**
     * Attempts to log the user in using the provided credentials. This result will be stored in the current
     * {@link AuthenticatedSessionManager} (if any), so subsequent requests will automatically be authenticated
     * as this user.
     * <p>
     * This operation may block
     *
     * @param username The username
     * @param password The password
     * @return <code>true</code> if the login succeeded, false otherwise
     */
    boolean login(String username, String password);

    
de-authenticates the current exchange.

/**
     * de-authenticates the current exchange.
     *
     */
    void logout();

    /*
     * Methods Used To Control/Configure The Authentication Process.
     */

    
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. 
/**
     * Marks this request as requiring authentication. Authentication challenge headers will only be sent if this
     * method has been called. If {@link #authenticate()}
     * is called without first calling this method then the request will continue as normal even if the authentication
     * was not successful.
     */
    void setAuthenticationRequired();

    
Returns true if authentication is required

Returns:true If authentication is required
/**
     * Returns true if authentication is required
     *
     * @return <code>true</code> If authentication is required
     */
    boolean isAuthenticationRequired();

    
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. 
Params:
  • mechanism – The mechanism to add
Deprecated:This method is now only applicable to SecurityContext implementations that also implement the AuthenticationMechanismContext interface.
/**
     * Adds an authentication mechanism to this context. When {@link #authenticate()} is
     * called mechanisms will be iterated over in the order they are added, and given a chance to authenticate the user.
     *
     * @param mechanism The mechanism to add
     * @deprecated This method is now only applicable to {@code SecurityContext} implementations that also implement the {@link AuthenticationMechanismContext} interface.
     */
    @Deprecated
    void addAuthenticationMechanism(AuthenticationMechanism mechanism);

    
Returns:A list of all authentication mechanisms in this context
Deprecated:Obtaining lists of mechanisms is discouraged, however there should not be a need to call this anyway.
/**
     *
     * @return A list of all authentication mechanisms in this context
     * @deprecated Obtaining lists of mechanisms is discouraged, however there should not be a need to call this anyway.
     */
    @Deprecated
    List<AuthenticationMechanism> getAuthenticationMechanisms();

    /*
     * Methods to access information about the current authentication status.
     */

    
Returns:true if a user has been authenticated for this request, false otherwise.
/**
     *
     * @return true if a user has been authenticated for this request, false otherwise.
     */
    boolean isAuthenticated();



    
Obtain the Account for the currently authenticated identity. 
Returns:The Account for the currently authenticated identity or null if no account is currently authenticated.
/**
     * Obtain the {@link Account} for the currently authenticated identity.
     *
     * @return The {@link Account} for the currently authenticated identity or <code>null</code> if no account is currently authenticated.
     */
    Account getAuthenticatedAccount();

    
Returns:The name of the mechanism that was used to authenticate
/**
     *
     * @return The name of the mechanism that was used to authenticate
     */
    String getMechanismName();

    /*
     * Methods Used by AuthenticationMechanism implementations.
     */

    
Obtain the associated IdentityManager to use to make account verification decisions. 
Returns:The associated IdentityManager
Deprecated:Authentication mechanisms that rely on the IdentityManager should instead hold their own reference to it.
/**
     * Obtain the associated {@link IdentityManager} to use to make account verification decisions.
     *
     * @return The associated {@link IdentityManager}
     * @deprecated Authentication mechanisms that rely on the {@link IdentityManager} should instead hold their own reference to it.
     */
    @Deprecated
    IdentityManager getIdentityManager();

    
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. 
Params:
  • account – - The authenticated Account
  • mechanismName – - The name of the mechanism used to authenticate the account.
  • cachingRequired – - If this mechanism requires caching
/**
     * Called by the {@link AuthenticationMechanism} to indicate that an account has been successfully authenticated.
     *
     * Note: A successful verification of an account using the {@link IdentityManager} is not the same as a successful
     * authentication decision, other factors could be taken into account to make the final decision.
     *
     * @param account - The authenticated {@link Account}
     * @param mechanismName - The name of the mechanism used to authenticate the account.
     * @param cachingRequired - If this mechanism requires caching
     */
    void authenticationComplete(final Account account, final String mechanismName, final boolean cachingRequired);

    
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. 
Params:
  • message – - The message describing the failure.
  • mechanismName – - The name of the mechanism reporting the failure.
/**
     * Called by the {@link 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.
     *
     * @param message - The message describing the failure.
     * @param mechanismName - The name of the mechanism reporting the failure.
     */
    void authenticationFailed(final String message, final String mechanismName);

    /*
     * Methods for the management of NotificationHandler registrations.
     */

    
Register a NotificationReceiver interested in receiving notifications for security events that happen on this SecurityContext. 
Params:
/**
     * Register a {@link NotificationReceiver} interested in receiving notifications for security events that happen on this SecurityContext.
     *
     * @param receiver - The {@link NotificationReceiver} to register.
     */
    void registerNotificationReceiver(final NotificationReceiver receiver);

    
Remove a previously registered NotificationReceiver from this SecurityContext. If the supplied receiver has not been previously registered this method will fail silently. 
Params:
/**
     * Remove a previously registered {@link NotificationReceiver} from this SecurityContext.
     *
     * If the supplied receiver has not been previously registered this method will fail silently.
     *
     * @param receiver - The {@link NotificationReceiver} to remove.
     */
    void removeNotificationReceiver(final NotificationReceiver receiver);
}