Package com.sun.identity.authentication

Class AuthContext

java.lang.Object
com.sun.identity.authentication.AuthContext
All Implemented Interfaces:
Serializable
@Supported public class AuthContext extends Object implements Serializable
The AuthContext provides the implementation for authenticating users.

A typical caller instantiates this class and starts the login process. The caller then obtains an array of Callback objects, which contains the information required by the authentication plug-in module. The caller requests information from the user. On receiving the information from the user, the caller submits the same to this class. While more information is required, the above process continues until all the information required by the plug-ins/authentication modules, has been supplied. The caller then checks if the user has successfully been authenticated. If successfully authenticated, the caller can then get the Subject and SSOToken for the user; if not successfully authenticated, the caller obtains the AuthLoginException.

The implementation supports authenticating users either locally i.e., in process with all authentication modules configured or remotely to an authentication service/framework. (See documentation to configure in either of the modes).

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    AuthContext.IndexType
    The class IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed.
    static class 
    AuthContext.Status
    The class Status defines the possible authentication states during the login process.

  • Constructor Summary

    Constructors
    Constructor
    Description
    AuthContext(SSOToken ssoToken)
    Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token.
    AuthContext(SSOToken ssoToken, boolean forceAuth)
    Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token.
    AuthContext(String orgName)
    Constructs an instance of AuthContext for a given organization name or sub organization name.
    AuthContext(String orgName, URL url)
    Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenAM server URL.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abort()
    Terminates an ongoing login call that has not yet completed.
    String
    getClientHostName()
    Returns the client's hostname or IP address as set by setClientHostName
    AuthLoginException
    getLoginException()
    Returns login exception, if any, during the authentication process.
    Set
    getModuleInstanceNames()
    Returns authentication module/s instances (or plugins) configured for a organization, or sub-organization name that was set during the AuthContext constructor.
    String
    getOrganizationName()
    Returns the the organization name that was set during the AuthContext constructor.
    Callback[]
    getRequirements()
    Returns an array of Callback objects that must be populated by the user and returned back.
    Callback[]
    getRequirements(boolean noFilter)
    Returns an array of Callback objects that must be populated by the user and returned back.
    SSOToken
    getSSOToken()
    Returns the Single-Sign-On (SSO) Token for the authenticated user.
    AuthContext.Status
    getStatus()
    Returns the current status of the authentication process as AuthContext.Status.
    Subject
    getSubject()
    Returns the set of Principals or Subject the user has been authenticated as.
    boolean
    hasMoreRequirements()
    Returns true if the login process requires more information from the user to complete the authentication.
    boolean
    hasMoreRequirements(boolean noFilter)
    Returns true if the login process requires more information from the user to complete the authentication.
    void
    login()
    Starts the login process for the given AuthContext object.
    void
    login(AuthContext.IndexType type, String indexName)
    Starts the login process for the given AuthContext object identified by the index type and index name.
    void
    login(AuthContext.IndexType indexType, String indexName, String[] params)
    Starts the login process for the given AuthContext object identified by the index type and index name with default parameters.
    void
    login(AuthContext.IndexType indexType, String indexName, String[] params, Map envMap)
    Starts the login process for the given AuthContext object identified by the index type and index name with certain parameters and environment map.
    void
    login(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
    Starts the login process for the given AuthContext object.
    void
    logout()
    Logs out the user and also invalidates the single sign on token associated with this AuthContext.
    void
    logoutUsingTokenID()
    Logs out the user and also invalidates the single sign on token associated with this AuthContext.
    void
    setClientHostName(String hostname)
    Sets the client's hostname or IP address.This could be used by the policy component to restrict access to resources.
    void
    submitRequirements(Callback[] info)
    Submits the populated Callback objects to the authentication plug-in modules.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AuthContext

      @Supported public AuthContext(String orgName) throws AuthLoginException
      Constructs an instance of AuthContext for a given organization name or sub organization name. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name.

      Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

      Parameters:
      orgName - Name of the user's organization.
      Throws:
      AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

    • AuthContext

      @Supported public AuthContext(String orgName, URL url) throws AuthLoginException
      Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenAM server URL. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name. And the url should specify the OpenAM server's protocol, host name, and port number, for example : http://daye.red.iplanet.com:58080 Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.
      Parameters:
      orgName - name of the user's organization
      url - URL of the OpenAm instance to talk to
      Throws:
      AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

    • AuthContext

      @Supported public AuthContext(SSOToken ssoToken) throws AuthLoginException
      Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token. This constructor should be called for re-authentication of an authenticated user. single sign on token is the authenticated resource's Single-Sign-On Token. If the session properties based on the login method used matches those in the user's new authenticated session then session upgrade will be done. A new session containing properties from both old single sign on token and new session shall be returned and old session will be destroyed if authentication passes. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.
      Parameters:
      ssoToken - single sign on token representing the resource's previous authenticated session.
      Throws:
      AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

    • AuthContext

      @Supported public AuthContext(SSOToken ssoToken, boolean forceAuth) throws AuthLoginException
      Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token. This constructor should be called for re-authentication of an authenticated user. single sign on token is the authenticated resource's Single-Sign-On Token. If the session properties based on the login method used matches those in the user's new authenticated session then session upgrade will be done. If forceAuth flag is true then the existing session is used and no new session is created otherwise this constructor behaves same as the constructor with no forceAuth flag. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.
      Parameters:
      ssoToken - single sign on token representing the resource's previous authenticated session.
      forceAuth - indicates that authentication preocess has to be restarted and given single sign on token will be used and new session will not be created.
      Throws:
      AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

  • Method Details

    • login

      @Supported public void login() throws AuthLoginException
      Starts the login process for the given AuthContext object.
      Throws:
      AuthLoginException - if an error occurred during login.

    • login

      @Supported public void login(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws AuthLoginException
      Starts the login process for the given AuthContext object.
      Parameters:
      request - The HttpServletRequest that was sent to start the authentication process.
      response - The corresponding HttpServletResponse for the HttpServletRequest.
      Throws:
      AuthLoginException - If an error occurred during login.

    • login

      @Supported public void login(AuthContext.IndexType type, String indexName) throws AuthLoginException
      Starts the login process for the given AuthContext object identified by the index type and index name. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism/authentication modules.
      Parameters:
      type - Authentication index type.
      indexName - Authentication index name.
      Throws:
      AuthLoginException - if an error occurred during login.

    • login

      @Supported public void login(AuthContext.IndexType indexType, String indexName, String[] params) throws AuthLoginException
      Starts the login process for the given AuthContext object identified by the index type and index name with default parameters. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism/authentication modules.
      Parameters:
      indexType - authentication index type.
      indexName - authentication index name.
      params - contains the default values for the callbacks. The order of this array matches the callbacks order for this login process. value for the PasswordCallback is also in String format, it will be converted to char[] when it is set to the callback. Internal processing for this string array uses | as separator. Hence | should not be used in these default values. Currently only NameCallback and PasswordCallback are supported.
      Throws:
      AuthLoginException - if an error occurred during login.

    • login

      @Supported public void login(AuthContext.IndexType indexType, String indexName, String[] params, Map envMap) throws AuthLoginException
      Starts the login process for the given AuthContext object identified by the index type and index name with certain parameters and environment map. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, modules and resources.
      Parameters:
      indexType - authentication index type.
      indexName - authentication index name.
      params - contains the default values for the callbacks. The order of this array matches the callbacks order for this login process. value for the PasswordCallback is also in String format, it will be converted to char[] when it is set to the callback. Internal processing for this string array uses | as separator. Hence | should not be used in these default values. Currently only NameCallback and PasswordCallback are supported.
      envMap - contains the environment key/value pairs. Key is a String object indicating the property name, value is a Set of String values for the property. Currenty this parameter only applicable when the indexTye is AuthContext.IndexType.RESOURCE.
      Throws:
      AuthLoginException - if an error occurred during login.

    • getSubject

      @Supported public Subject getSubject()
      Returns the set of Principals or Subject the user has been authenticated as. This should be invoked only after successful authentication.
      Returns:
      Subject for the authenticated User. If the authentication fails or the authentication is in process, this will return null.

    • hasMoreRequirements

      @Supported public boolean hasMoreRequirements()
      Returns true if the login process requires more information from the user to complete the authentication.

      NOTE: This method has to be called as a condition of a while loop in order to complete the authentication process and get the correct Status after submitting the requirements.

      Returns:
      true if more credentials are required from the user.

    • hasMoreRequirements

      @Supported public boolean hasMoreRequirements(boolean noFilter)
      Returns true if the login process requires more information from the user to complete the authentication. NOTE: This method has to be called as a condition of a while loop in order to complete the authentication process and get the correct Status after submitting the requirements.
      Parameters:
      noFilter - flag indicates whether to filter PagePropertiesCallback or not. Value true will not filter PagePropertiesCallback.
      Returns:
      true if more credentials are required from the user.

    • getRequirements

      @Supported public Callback[] getRequirements()
      Returns an array of Callback objects that must be populated by the user and returned back. These objects are requested by the authentication plug-ins, and these are usually displayed to the user. The user then provides the requested information for it to be authenticated.
      Returns:
      an array of Callback objects requesting credentials from user

    • getRequirements

      @Supported public Callback[] getRequirements(boolean noFilter)
      Returns an array of Callback objects that must be populated by the user and returned back. These objects are requested by the authentication plug-ins, and these are usually displayed to the user. The user then provides the requested information for it to be authenticated.
      Parameters:
      noFilter - boolean flag indicating whether to filter PagePropertiesCallback or not. Value true will not filter PagePropertiesCallback.
      Returns:
      an array of Callback objects requesting credentials from user

    • submitRequirements

      @Supported public void submitRequirements(Callback[] info)
      Submits the populated Callback objects to the authentication plug-in modules. Called after getRequirements method and obtaining user's response to these requests.
      Parameters:
      info - Array of Callback objects.

    • logout

      @Supported public void logout() throws AuthLoginException
      Logs out the user and also invalidates the single sign on token associated with this AuthContext.
      Throws:
      AuthLoginException - if an error occurred during logout.

    • logoutUsingTokenID

      @Supported public void logoutUsingTokenID() throws AuthLoginException
      Logs out the user and also invalidates the single sign on token associated with this AuthContext. This method causes the logout to happen on the server and the correct SPI hooks to be called.
      Throws:
      AuthLoginException - if an error occurred during logout.

    • getLoginException

      @Supported public AuthLoginException getLoginException()
      Returns login exception, if any, during the authentication process. Typically set when the login fails.
      Returns:
      login exception.

    • getSSOToken

      @Supported public SSOToken getSSOToken() throws com.sun.identity.shared.locale.L10NMessageImpl
      Returns the Single-Sign-On (SSO) Token for the authenticated user. If the user has not successfully authenticated Exception will be thrown.

      Single sign token can be used as the authenticated token.

      Returns:
      Single-Sign-On token for the valid user after successful authentication.
      Throws:
      com.sun.identity.shared.locale.L10NMessageImpl - if the user is not authenticated or an error is encountered in retrieving the user's single sign on token.

    • getStatus

      @Supported public AuthContext.Status getStatus()
      Returns the current status of the authentication process as AuthContext.Status.
      Returns:
      Status of the authentication process.

    • getOrganizationName

      @Supported public String getOrganizationName()
      Returns the the organization name that was set during the AuthContext constructor.
      Returns:
      Organization name in the AuthContext.

    • getModuleInstanceNames

      @Supported public Set getModuleInstanceNames()
      Returns authentication module/s instances (or plugins) configured for a organization, or sub-organization name that was set during the AuthContext constructor.
      Returns:
      Set of Module instance names.

    • abort

      @Supported public void abort() throws AuthLoginException
      Terminates an ongoing login call that has not yet completed.
      Throws:
      AuthLoginException - if an error occurred during abort.

    • setClientHostName

      @Supported public void setClientHostName(String hostname)
      Sets the client's hostname or IP address.This could be used by the policy component to restrict access to resources. This method is ineffective if the "Remote Auth Security" option under the global configuration of Core Authentication Service is not enabled. This method must be called before calling login method. If it is called after calling login then it is ineffective.
      Parameters:
      hostname - hostname or ip address

    • getClientHostName

      @Supported public String getClientHostName()
      Returns the client's hostname or IP address as set by setClientHostName
      Returns:
      hostname/IP address