OpenAM Project 13.5.2 Documentation
com.sun.identity.authentication.spi

Class AMLoginModule

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void clearInfoText(int state)
      Clears the info text for a given callback state
      void destroyModuleState()
      This method should be overridden by each login module to destroy dispensable state fields.
      String getAttribute(int state, int index)
      Returns the attribute name for the specified callback in the specified login state.
      int getAuthLevel()
      Returns authentication level that has been set for the module
      Callback[] getCallback(int index)
      Returns a Callback array for a specific state.
      Callback[] getCallback(int index, boolean fetchOrig)
      Return a Callback array for a specific state.
      int getCurrentState()
      Returns the current state in the authentication process.
      int getFailCount(AMIdentity amIdUser)
      Get the number of failed login attempts for a user when account locking is enabled.
      javax.servlet.http.HttpServletRequest getHttpServletRequest()
      Returns the HttpServletRequest object that initiated the call to this module.
      javax.servlet.http.HttpServletResponse getHttpServletResponse()
      Returns the HttpServletResponse object for the servlet request that initiated the call to this module.
      String getInfoText(int state, int index)
      Returns the info text associated with a specific callback
      String getLocale()
      Returns the locale for this authentication session.
      int getMaximumFailCount()
      Get the maximum number failed login attempts permitted for a user before when their account is locked out.
      Set getNewUserIDs(Map attributes, int num)
      Returns a set of user IDs generated from the class defined in the Core Authentication Service.
      int getNumberOfStates()
      Returns the number of authentication states for this login module.
      Map getOrgProfile(String orgDN)
      Returns the organization attributes for specified organization.
      Map getOrgServiceTemplate(String orgDN, String serviceName)
      Returns service template attributes defined for the specified organization.
      abstract Principal getPrincipal()
      Abstract method must be implemeted by each login module to get the user Principal
      String getRequestOrg()
      Returns the organization DN for this authentication session.
      Map getServiceConfig(String name)
      Returns service configuration attributes.
      String getSessionId()
      Returns a unique key for this authentication session.
      SSOToken getSSOSession()
      Returns an administration SSOToken for use the OpenAM APIs.
      AMUser getUserProfile(String userDN)
      Deprecated. 
      This method has been deprecated. Please use the IdRepo API's to get the AMIdentity object for the user. More information on how to use the Identity Repository APIs is available in the "Customizing Identity Data Storage" chapter of the OpenAM Developer's Guide.
      String getUserSessionProperty(String name)
      Returns the property from the user session.
      Set<SSOToken> getUserSessions(String userName)
      Returns the set of SSOTokens for a specified user
      void incrementFailCount(String userName)
      Increments the fail count for the given user.
      abstract void init(Subject subject, Map sharedState, Map options)
      Initialize this LoginModule.
      boolean isAccountLocked(String userName)
      Returns true if the named account is locked out, false otherwise.
      boolean isRequired(int state, int index)
      Checks if a Callback is required to have input.
      boolean isSessionQuotaReached(String userName)
      Returns true if the user identified by the supplied username has reached their session quota.
      NBThe existing session count is exclusive of any session created as part of the running authentication process
      abstract int process(Callback[] callbacks, int state)
      Abstract method must be implemented by each login module to control the flow of the login process.
      void replaceCallback(int state, int index, Callback callback)
      Replace Callback object for a specific state.
      void resetCallback(int state, int index)
      Reset a Callback instance to the original Callback for the specified state and the specified index.
      boolean setAuthLevel(int auth_level)
      Sets the AuthLevel for this session.
      void setFailureID(String userID)
      Sets the userID of user who failed authentication.
      void setLoginFailureURL(String url)
      Sets the the login failure URL for the user.
      void setLoginSuccessURL(String url)
      Sets the the login successful URL for the user.
      void setUserAttributes(Map attributeValuePairs)
      Sets a Map of attribute value pairs to be used when the authentication service is configured to dynamically create a user.
      void setUserSessionProperty(String name, String value)
      Sets a property in the user session.
      void substituteHeader(int state, String header)
      Use this method to replace the header text from the XML file with new text.
      void substituteInfoText(int state, int callback, String infoText)
      Allows you to set the info text for a specific callback.
      void validatePassword(String userPassword)
      Validate password for the distinguished user, this will use validation plugin if exists to validate password
      void validateUserName(String userName, String regEx)
      Validates the given user name by using validation plugin if exists else it checks invalid characters in the source string.
    • Method Detail

      • getSSOSession

        public SSOToken getSSOSession()
                               throws AuthLoginException
        Returns an administration SSOToken for use the OpenAM APIs. NB:This is not the SSOToken that represents the user, if you wish to set/get user session properties use the setUserSessionProperty and getUserSessionProperty method respectively.
        Returns:
        An administrative SSOToken.
        Throws:
        AuthLoginException - if the authentication SSO session is null.
      • getCallback

        public Callback[] getCallback(int index)
                               throws AuthLoginException
        Returns a Callback array for a specific state.

        This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.

        Parameters:
        index - order of state
        Returns:
        Callback array for this state, return 0-length Callback array if there is no Callback defined for this state
        Throws:
        AuthLoginException - if unable to read the callbacks
      • getCallback

        public Callback[] getCallback(int index,
                             boolean fetchOrig)
                               throws AuthLoginException
        Return a Callback array for a specific state.

        This method can be used to retrieve Callback[] for any state. All previous submitted Callback[] information are kept until the login process is completed.

        Parameters:
        index - order of state
        fetchOrig - boolean indicating even if the callbacks for this state have been previously retrieved, get the original callbacks from AMModuleProperties, if set to "true".
        Returns:
        Callback array for this state, return 0-length Callback array if there is no Callback defined for this state
        Throws:
        AuthLoginException - if unable to read the callbacks
      • replaceCallback

        public void replaceCallback(int state,
                           int index,
                           Callback callback)
                             throws AuthLoginException
        Replace Callback object for a specific state.
        Parameters:
        state - Order of login state
        index - Index of Callback in the Callback array to be replaced for the specified state. Here index starts with 0, i.e. 0 means the first Callback in the Callback[], 1 means the second callback.
        callback - Callback instance to be replaced
        Throws:
        AuthLoginException - if state or index is out of bound, or callback instance is null.
      • substituteInfoText

        public void substituteInfoText(int state,
                              int callback,
                              String infoText)
                                throws AuthLoginException
        Allows you to set the info text for a specific callback. Info Text is shown under the element in the Login page. It is used in the membership module to implement in-line feedback.
        Parameters:
        state - state in which the Callback[] to be reset
        callback - the callback to associate the info text
        infoText - the infotext for the callback
        Throws:
        AuthLoginException - if state/callback is out of bounds
      • substituteHeader

        public void substituteHeader(int state,
                            String header)
                              throws AuthLoginException
        Use this method to replace the header text from the XML file with new text. This method can be used multiple times on the same state replacing text with new text each time. Useful for modules that control their own error handling.
        Parameters:
        state - state state in which the Callback[] to be reset
        header - The text of the header to be replaced
        Throws:
        AuthLoginException - if state is out of bounds
      • resetCallback

        public void resetCallback(int state,
                         int index)
                           throws AuthLoginException
        Reset a Callback instance to the original Callback for the specified state and the specified index. This will override change to the Callback instance by the replaceCallback() method.
        Parameters:
        state - state in which the Callback[] to be reset
        index - index order of the Callback in the Callback[], index starts with 0, i.e. 0 means first callback instance, 1 means the second callback instance.
        Throws:
        AuthLoginException - if state or index is out of bound.
      • init

        public abstract void init(Subject subject,
                Map sharedState,
                Map options)
        Initialize this LoginModule.

        This is an abstract method, must be implemented by user's Login Module to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, they can be ignored.

        Parameters:
        subject - - the Subject to be authenticated.
        sharedState - - state shared with other configured LoginModules.
        options - - options specified in the login Configuration for this particular LoginModule. It contains all the global and organization attribute configuration for this module. The key of the map is the attribute name (e.g. iplanet-am-auth-ldap-server) as String, the value is the value of the corresponding attribute as Set.
      • process

        public abstract int process(Callback[] callbacks,
                  int state)
        Abstract method must be implemented by each login module to control the flow of the login process.

        This method takes an array of sbumitted Callback, process them and decide the order of next state to go. Return -1 if the login is successful, return 0 if the LoginModule should be ignored.

        Parameters:
        callbacks - Callback[] for this Login state
        state - Order of state. State order starts with 1.
        Returns:
        order of next state. return -1 if authentication is successful, return 0 if the LoginModule should be ignored.
        Throws:
        LoginException - if login fails.
      • getPrincipal

        public abstract Principal getPrincipal()
        Abstract method must be implemeted by each login module to get the user Principal
        Returns:
        Principal
      • destroyModuleState

        public void destroyModuleState()
        This method should be overridden by each login module to destroy dispensable state fields.
      • getAuthLevel

        public int getAuthLevel()
        Returns authentication level that has been set for the module
        Returns:
        authentication level of this authentication session
      • setAuthLevel

        public boolean setAuthLevel(int auth_level)
        Sets the AuthLevel for this session. The authentication level being set cannot be downgraded below that set by the module configuration.
        Parameters:
        auth_level - authentication level string to be set
        Returns:
        true if setting is successful,false otherwise
      • getCurrentState

        public int getCurrentState()
        Returns the current state in the authentication process.
        Returns:
        the current state in the authentication process.
      • getHttpServletRequest

        public javax.servlet.http.HttpServletRequest getHttpServletRequest()
        Returns the HttpServletRequest object that initiated the call to this module.
        Returns:
        HttpServletRequest for this request, returns null if the HttpServletRequest object could not be obtained.
      • getHttpServletResponse

        public javax.servlet.http.HttpServletResponse getHttpServletResponse()
        Returns the HttpServletResponse object for the servlet request that initiated the call to this module. The servlet response object will be the response to the HttpServletRequest received by the authentication module.
        Returns:
        HttpServletResponse for this request, returns null if the HttpServletResponse object could not be obtained.
      • getNumberOfStates

        public int getNumberOfStates()
        Returns the number of authentication states for this login module.
        Returns:
        the number of authentication states for this login module.
      • getRequestOrg

        public String getRequestOrg()
        Returns the organization DN for this authentication session.
        Returns:
        organization DN.
      • getSessionId

        public String getSessionId()
        Returns a unique key for this authentication session. This key will be unique throughout an entire Web browser session.
        Returns:
        null is unable to get the key,
      • getOrgProfile

        public Map getOrgProfile(String orgDN)
                          throws AuthLoginException
        Returns the organization attributes for specified organization.
        Parameters:
        orgDN - Requested organization DN.
        Returns:
        Map that contains all attribute key/value pairs defined in the organization.
        Throws:
        AuthLoginException - if cannot get organization profile.
      • getOrgServiceTemplate

        public Map getOrgServiceTemplate(String orgDN,
                                String serviceName)
                                  throws AuthLoginException
        Returns service template attributes defined for the specified organization.
        Parameters:
        orgDN - Organization DN.
        serviceName - Requested service name.
        Returns:
        Map that contains all attribute key/value pairs defined in the organization service template.
        Throws:
        AuthLoginException - if cannot get organization service template.
      • getServiceConfig

        public Map getServiceConfig(String name)
                             throws AuthLoginException
        Returns service configuration attributes.
        Parameters:
        name - Requested service name.
        Returns:
        Map that contains all attribute key/value pairs defined in the service configuration.
        Throws:
        AuthLoginException - if error in accessing the service schema.
      • getUserProfile

        public AMUser getUserProfile(String userDN)
                              throws AuthLoginException
        Deprecated. This method has been deprecated. Please use the IdRepo API's to get the AMIdentity object for the user. More information on how to use the Identity Repository APIs is available in the "Customizing Identity Data Storage" chapter of the OpenAM Developer's Guide.
        Returns the user profile for the user specified. This method may only be called in the validate() method.
        Parameters:
        userDN - distinguished name os user.
        Returns:
        AMUser object for the user's distinguished name.
        Throws:
        AuthLoginException - if it fails to get the user profile for userDN.
      • getUserSessionProperty

        public String getUserSessionProperty(String name)
                                      throws AuthLoginException
        Returns the property from the user session. If the session is being force upgraded then set on the old session otherwise set on the current session.
        Parameters:
        name - The property name.
        Returns:
        The property value.
        Throws:
        AuthLoginException - if the user session is invalid.
      • setUserSessionProperty

        public void setUserSessionProperty(String name,
                                  String value)
                                    throws AuthLoginException
        Sets a property in the user session. If the session is being force upgraded then set on the old session otherwise set on the current session.
        Parameters:
        name - The property name.
        value - The property value.
        Throws:
        AuthLoginException - if the user session is invalid.
      • getNewUserIDs

        public Set getNewUserIDs(Map attributes,
                        int num)
                          throws AuthLoginException
        Returns a set of user IDs generated from the class defined in the Core Authentication Service. Returns null if the attribute iplanet-am-auth-username-generator-enabled is set to false.
        Parameters:
        attributes - the keys in the Map contains the attribute names and their corresponding values in the Map is a Set that contains the values for the attribute
        num - the maximum number of returned user IDs; 0 means there is no limit
        Returns:
        a set of auto-generated user IDs
        Throws:
        AuthLoginException - if the class instantiation failed
      • setLoginFailureURL

        public void setLoginFailureURL(String url)
                                throws AuthLoginException
        Sets the the login failure URL for the user. This method does not change the URL in the user's profile. When the user authenticates failed, this URL will be used by the authentication for the redirect.
        Parameters:
        url - URL to go when authentication failed.
        Throws:
        AuthLoginException - if unable to set the URL.
      • setLoginSuccessURL

        public void setLoginSuccessURL(String url)
                                throws AuthLoginException
        Sets the the login successful URL for the user. This method does not change the URL in the user's profile. When the user authenticates successfully, this URL will be used by the authentication for the redirect.
        Parameters:
        url - URL to go when authentication is successful.
        Throws:
        AuthLoginException - if unable to set the URL.
      • isRequired

        public boolean isRequired(int state,
                         int index)
        Checks if a Callback is required to have input.
        Parameters:
        state - Order of state.
        index - Order of the Callback in the Callback[], the index. starts with 0.
        Returns:
        true if the callback corresponding to the number in the specified state is required to have value, false otherwise
      • getInfoText

        public String getInfoText(int state,
                         int index)
        Returns the info text associated with a specific callback
        Parameters:
        state - The state to fetch the info text
        index - The callback to fetch the info text
        Returns:
        The info text
      • getAttribute

        public String getAttribute(int state,
                          int index)
        Returns the attribute name for the specified callback in the specified login state.
        Parameters:
        state - Order of state
        index - Order of the Callback in the Callback[], the index starts with 0.
        Returns:
        Name of the attribute, empty string will be returned if the attribute is not defined.
      • setFailureID

        public void setFailureID(String userID)
        Sets the userID of user who failed authentication. This userID will be used to log failed authentication in the OpenSSO error logs.
        Parameters:
        userID - user name of user who failed authentication.
      • setUserAttributes

        public void setUserAttributes(Map attributeValuePairs)
        Sets a Map of attribute value pairs to be used when the authentication service is configured to dynamically create a user.
        Parameters:
        attributeValuePairs - A map containing the attributes and its values. The key is the attribute name and the value is a Set of values.
      • getFailCount

        public int getFailCount(AMIdentity amIdUser)
                         throws AuthenticationException
        Get the number of failed login attempts for a user when account locking is enabled.
        Returns:
        number of failed attempts, -1 means account locking is not enabled.
        Throws:
        AuthenticationException - if the user name passed in is not valid or null, or for any other error condition.
      • isSessionQuotaReached

        public boolean isSessionQuotaReached(String userName)
        Returns true if the user identified by the supplied username has reached their session quota.
        NBThe existing session count is exclusive of any session created as part of the running authentication process
        Parameters:
        userName - the username of the user who's session quota will be checked
        Returns:
        true if the user session quota is reached, false otherwise
      • getUserSessions

        public Set<SSOTokengetUserSessions(String userName)
        Returns the set of SSOTokens for a specified user
        Parameters:
        userName - The username to be used to query the sessions
        Returns:
        The set of SSOTokens for the user's current sessions, returns null on error
OpenAM Project 13.5.2 Documentation

Copyright © 2010-2016, ForgeRock All Rights Reserved.