Package com.sun.identity.authentication

Class 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:
    Serialized Form

    • 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

      All Methods Instance Methods Concrete Methods 
      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.

    • Constructor Detail

      • 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 Detail

      • 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.

      • 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