Package com.sun.identity.authentication

Class AuthContext

  • All Implemented Interfaces:
    Serializable
    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, String nickName)
      Constructs an instance of AuthContext for a given organization name, or sub organization name and a nick name for the certificate to be used in SSL handshake if client authentication is turn on in the server side.
      AuthContext​(String orgName, String nickName, URL url)
      Constructs an instance of AuthContext for a given organization name, or sub organization name, a nick name for the certificate to be used in SSL handshake if client authentication is enabled on the server side and the OpenAM URL.
      AuthContext​(String orgName, URL url)
      Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenAM server URL.

    • Field Detail

      • authDebug

        protected static Debug authDebug

      • localFlag

        public boolean localFlag
        Variables for checking auth service is running local

      • localAuthServiceID

        public static String localAuthServiceID
        Variables for local AuthService identifier

    • Constructor Detail

      • AuthContext

        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

        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

        public AuthContext​(String orgName,
                   String nickName)
            throws AuthLoginException
        Constructs an instance of AuthContext for a given organization name, or sub organization name and a nick name for the certificate to be used in SSL handshake if client authentication is turn on in the server side. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name. This constructor would be mainly used for the Certificate based authentication. If the certificate database contains multiple matching certificates for SSL, this constructor must be called in order for the desired certificate to be used for the Certificate based authentication. 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
        nickName - nick name for the certificate to be used
        Throws:
        AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

      • AuthContext

        public AuthContext​(String orgName,
                   String nickName,
                   URL url)
            throws AuthLoginException
        Constructs an instance of AuthContext for a given organization name, or sub organization name, a nick name for the certificate to be used in SSL handshake if client authentication is enabled on the server side and the OpenAM URL. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or a 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 This constructor would be mainly used for the Certificate based authentication. If the certificate database contains multiple matching certificates for SSL, this constructor must be called in order for the desired certificate to be used for the Certificate based authentication. 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
        nickName - nick name for the certificate to be used
        url - URL of the OpenAM server to talk to
        Throws:
        AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

      • AuthContext

        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

        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

        public void login​(jakarta.servlet.http.HttpServletRequest request,
                  jakarta.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

        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

        public void login​(AuthContext.IndexType type,
                  String indexName,
                  String locale)
           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. It allows the caller to pass in the desired locale for this request.
        Parameters:
        type - authentication index type
        indexName - authentication index name
        locale - locale setting
        Throws:
        AuthLoginException - if an error occurred during login

      • login

        public SSOToken login​(AuthContext.IndexType type,
                      String indexName,
                      Callback[] userInfo)
               throws AuthLoginException
        Starts the login process for the given AuthContext object identified by the index type and index name and also completes the login process by submitting the given User credentials in the form of Callbacks. 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.

        NOTE : This is a simplified wrapper method to eliminate multi-step calls to 'login' and submit credentials. This method is useful and will work only for those authentication modules which require only one set of callbacks or one page. This method can not be used to authenticate to authentication modules which require user interaction or multiple pages.

        Parameters:
        type - Authentication index type.
        indexName - Authentication index name.
        userInfo - User information/credentials in the form of array of Callback objects. The Callback objects array must be in the same order as defined in the authentication module properties file, otherwise authentication module code will not work.
        Returns:
        single-sign-on token for the valid user after successful authentication.
        Throws:
        AuthLoginException - if an error occurred during login.

      • login

        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

        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

        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.

      • getCookieTable

        public Map getCookieTable()
        Returns a Map object that that contains cookies set by AM server
        Returns:
        a Map of cookie name and Cookie object.

      • hasMoreRequirements

        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

        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

        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

        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

      • getRemoteRequest

        public jakarta.servlet.http.HttpServletRequest getRemoteRequest()
        Fetches the remote request from the context
        Returns:
        The Http Servlet Request

      • getRemoteResponse

        public jakarta.servlet.http.HttpServletResponse getRemoteResponse()
        Fetches the remote response from the context
        Returns:
        The Http Servlet Response

      • submitRequirements

        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.

      • submitRequirements

        public void submitRequirements​(Callback[] info,
                               jakarta.servlet.http.HttpServletRequest request,
                               jakarta.servlet.http.HttpServletResponse response)

      • logout

        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

        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

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

      • getSSOToken

        public SSOToken getSSOToken()
                     throws 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:
        L10NMessageImpl - if the user is not authenticated or an error is encountered in retrieving the user's single sign on token.

      • getStatus

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

      • getAuthIdentifier

        public String getAuthIdentifier()
        Returns the current Auth Identifier of the authentication process as String Session ID.
        Returns:
        Auth Identifier of the authentication process.

      • getSuccessURL

        public String getSuccessURL()
                     throws Exception
        Returns the Successful Login URL for the authenticated user.
        Returns:
        the Successful Login URL for the authenticated user.
        Throws:
        Exception - if it fails to get url for auth success

      • getFailureURL

        public String getFailureURL()
                     throws Exception
        Returns the Failure Login URL for the authenticating user.
        Returns:
        the Failure Login URL for the authenticating user
        Throws:
        Exception - if it fails to get url for auth failure

      • reset

        public void reset()
        Resets this instance of AuthContext object, so that a new login process can be initiated. A new authentication process can started using any one of the login methods.

      • getOrganizationName

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

      • getModuleInstanceNames

        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

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

      • setCertDBPassword

        public static void setCertDBPassword​(String password)
        Sets the password for the certificate database. It is required to call only once to initialize certificate database if the password is not set in the password file (specified as the value for com.iplanet.am.admin.cli.certdb.passfile in AMConfig.properties). If both are set, this method will overwrite the value in certificate password file.
        Parameters:
        password - Password for the certificate database.

      • getErrorTemplate

        public String getErrorTemplate()
        Returns the error template.
        Returns:
        error template.

      • getErrorMessage

        public String getErrorMessage()
        Returns the error message.
        Returns:
        error message.

      • getErrorCode

        public String getErrorCode()
        Returns error code.
        Returns:
        error code with white space trimmed

      • setClientHostName

        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

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

      • setLocale

        public void setLocale​(Locale loc)
        Sets locale based on user locale preferemce.
        Parameters:
        loc - locale preference of user

      • getLocale

        public Locale getLocale()
        Returns locale preference set in AuthConext
        Returns:
        - user prefered locale.

      • checkAndSetLoginStatus

        protected void checkAndSetLoginStatus()

      • sendQueryInformation

        protected void sendQueryInformation​(String reqInfo)

      • getCallbacks

        protected static Callback[] getCallbacks​(Document document,
                                         boolean noFilter)

      • getXMLforSubject

        protected static String getXMLforSubject​(Subject subject)

      • getLockoutMsg

        public String getLockoutMsg()
        Returns the account lockout message. This can be either a dynamic message indicating the number of tries left or the the account deactivated message.
        Returns:
        account lockout message.

      • isLockedOut

        public boolean isLockedOut()
        Returns true if account is lock out.
        Returns:
        true if account is lock out.