Chapter 2. Authentication Manager

package org.jboss.security;

import java.security.Principal;
import java.util.Map;
import javax.security.auth.Subject;
import javax.security.auth.message.MessageInfo;

/** The AuthenticationManager is responsible for validating credentials
 * associated with principals.
 */
public interface AuthenticationManager
{
   /** Retrieves the security domain that the security manager is from. Every
       security manager belongs to a named domain. The meaning of the security
       domain name depends on the implementation. For example, names may be
       fine-grained and refer to EJB names, or refer to coarse-grained objects such
       as J2EE applications and DNS domain names. @return the security domain
       name. If null, the security manager belongs to the logical default domain.
   */
   String getSecurityDomain();

   /** The isValid method is invoked to check whether a user ID (and associated
   credentials) as known to the operational environment are sufficient and valid
   proof of the user's identity. This is typically implemented as a call to isValid
   with a null subject.

    @see #isValid(Principal, Object, Subject)

    @param principal - the user identity in the operation environment 
    @param credential - the proof of user identity as known in the
    operation environment 
    @return true if the principal, credential pair is valid, false otherwise.
   */
   public boolean isValid(Principal principal, Object credential);

   /** The isValid method is invoked to check whether a user ID (and associated
   credentials) as known to the operational environment are sufficient and valid
   proof of the user's identity. This also extends the AuthenticationManager to
   provide a copy of the resulting authenticated Subject. This allows a caller to 
   authenticate a user and obtain a Subject whose state cannot be modified by
   other threads associated with the same principal.
   @param principal - the user identity in the operation environment
   @param credential - the proof of user identity as it is known in the
    operation environment
    @param activeSubject - the Subject which should be populated with the
      validated Subject contents. A JAAS based implementation would typically
      populate the activeSubject with the LoginContext.login result.
    @return true if the principal, credential pair is valid, false otherwise.
   */
   boolean isValid(Principal principal, Object credential,
      Subject activeSubject);

  /**
    * Authenticate a Subject given the request response JSR-196(JASPI) messages
    * @param requestMessage 
    * @param clientSubject Pre-created or null subject
    * @param layer Message Layer for the JASPI (Optional):  Default: HTTP
    * @return true if client subject is valid, false otherwise
    */
   boolean isValid(MessageInfo requestMessage, Subject clientSubject, String layer);

   /** Retrieve the currently authenticated subject. Previously, implementing the
   AuthenticationManager isValid method could set the active Subject, which
   caused problems in multi-threaded use-cases where the Subject instance was
   shared between multiple threads. This has been deprecated in favour of the
   JACC PolicyContextHandler#getContext(String, Object)

    @return the previously authenticated Subject (if isValid succeeded),
    null if isValid failed or has not been called for the active thread.
    */
   Subject getActiveSubject();
   
   /**
    * Trust-related use-cases may need their principal translated from another domain
    * to the current domain. This interface may need to contact the external trust
    * provider to derive the target principal.
    * @param anotherDomainPrincipal 
    *                   Principal that is applicable in the other domain 
    *                   (Can be null - in which case the contextMap is used
    *                   solely to derive the target principal)
    * @param contextMap
    *                   Any context information (including information on the other domain 
    *                   that may be relevant in deriving the target principal). Any SAML 
    *                   assertions that may be relevant can be passed here.
    * @return principal from a target security domain
    */
   Principal getTargetPrincipal(Principal anotherDomainPrincipal, Map<String,Object> contextMap);
}

package org.jboss.security;

import java.security.Principal;
import java.util.Map;
import javax.security.auth.Subject;
import javax.security.auth.message.MessageInfo;

/** The AuthenticationManager is responsible for validating credentials
 * associated with principals.
 */
public interface AuthenticationManager
{
   /** Retrieves the security domain that the security manager is from. Every
       security manager belongs to a named domain. The meaning of the security
       domain name depends on the implementation. For example, names may be
       fine-grained and refer to EJB names, or refer to coarse-grained objects such
       as J2EE applications and DNS domain names. @return the security domain
       name. If null, the security manager belongs to the logical default domain.
   */
   String getSecurityDomain();

   /** The isValid method is invoked to check whether a user ID (and associated
   credentials) as known to the operational environment are sufficient and valid
   proof of the user's identity. This is typically implemented as a call to isValid
   with a null subject.

    @see #isValid(Principal, Object, Subject)

    @param principal - the user identity in the operation environment 
    @param credential - the proof of user identity as known in the
    operation environment 
    @return true if the principal, credential pair is valid, false otherwise.
   */
   public boolean isValid(Principal principal, Object credential);

   /** The isValid method is invoked to check whether a user ID (and associated
   credentials) as known to the operational environment are sufficient and valid
   proof of the user's identity. This also extends the AuthenticationManager to
   provide a copy of the resulting authenticated Subject. This allows a caller to 
   authenticate a user and obtain a Subject whose state cannot be modified by
   other threads associated with the same principal.
   @param principal - the user identity in the operation environment
   @param credential - the proof of user identity as it is known in the
    operation environment
    @param activeSubject - the Subject which should be populated with the
      validated Subject contents. A JAAS based implementation would typically
      populate the activeSubject with the LoginContext.login result.
    @return true if the principal, credential pair is valid, false otherwise.
   */
   boolean isValid(Principal principal, Object credential,
      Subject activeSubject);

  /**
    * Authenticate a Subject given the request response JSR-196(JASPI) messages
    * @param requestMessage 
    * @param clientSubject Pre-created or null subject
    * @param layer Message Layer for the JASPI (Optional):  Default: HTTP
    * @return true if client subject is valid, false otherwise
    */
   boolean isValid(MessageInfo requestMessage, Subject clientSubject, String layer);

   /** Retrieve the currently authenticated subject. Previously, implementing the
   AuthenticationManager isValid method could set the active Subject, which
   caused problems in multi-threaded use-cases where the Subject instance was
   shared between multiple threads. This has been deprecated in favour of the
   JACC PolicyContextHandler#getContext(String, Object)

    @return the previously authenticated Subject (if isValid succeeded),
    null if isValid failed or has not been called for the active thread.
    */
   Subject getActiveSubject();
   
   /**
    * Trust-related use-cases may need their principal translated from another domain
    * to the current domain. This interface may need to contact the external trust
    * provider to derive the target principal.
    * @param anotherDomainPrincipal 
    *                   Principal that is applicable in the other domain 
    *                   (Can be null - in which case the contextMap is used
    *                   solely to derive the target principal)
    * @param contextMap
    *                   Any context information (including information on the other domain 
    *                   that may be relevant in deriving the target principal). Any SAML 
    *                   assertions that may be relevant can be passed here.
    * @return principal from a target security domain
    */
   Principal getTargetPrincipal(Principal anotherDomainPrincipal, Map<String,Object> contextMap);
}