Custom Authenticator and Login Module
This tutorial covers how to create a custom
authenticator and a
The following topics will be covered:
- How to implement a custom
authenticatorthat collects the username and password by using a request to a predefined URL
- How to implement a custom
login modulethat checks credentials that are received from the
- How to define a
realmthat uses your custom
- How to use this
realmto protect resources.
The authentication process can be interactive (for example, using a username and password), or non-interactive (for example, header-based authentication).
This process can involve a single-step (a simple user name/password form) or multiple steps (it might have to add a challenge after it issued the first password).
realm includes the class name of an
authenticator and a reference to a
- An authenticator is an entity that collects user information, such as a login form
- A login module is a server entity that validates the retrieved user credentials and builds the user identity
Authentication settings such as
login modules are configured in the authenticationConfig.xml file that is generated for every MobileFirst project.
login module, and
user identity instances are stored in a session scope. Therefore they exist as long as the session is alive.
You can write custom login modules and authenticators when the default provided ones do not match your requirements.
In previous tutorials, form-based authentication was implemented using a non-validating login module. Adapter-based authentication was also implemented without having to add login modules, and credentials validation was manually ran.
In some cases, though, when credentials validation cannot be run at the adapter-level and requires more complex code, you can implement an extra login module.
For example: When credentials validation must be customized for a specific enterprise, or when more information must be retrieved from each client request, such as
realms section of authenticationConfig.xml, define a realm called
Make sure that it uses
MyCustomAuthenticator as the class name, which will be implemented later.
loginModules section, add a
MyCustomLoginModule as the class name, which will be implemented later.
securityTests section, add a security test.
Later, this security test will be used to protect the adapter procedure. Therefore, use a
customSecurityTest element. Remember the security test name because it will used later.
Creating a custom Java authenticator
WorkLightAuthenticator API includes the following methods:
init method of the
authenticator is called when the
authenticator instance is created. It takes the parameters that are specified in the definition of the realm in the authenticationConfig.xml file.
processRequest method is called for each request from an unauthenticated session.
processAuthenticationFailure method is called if the
login module returns a failure of credentials validation.
processRequestAlreadyAuthenticated method is called for each request from an already authenticated session.
getAuthenticationData method is used by a login module to get the credentials that are collected by an
changeResponseOnSuccess method is called after authentication success. It is used to add data to the response after the authentication is successful.
clone method is used to create a deep copy of class members.
MyCustomAuthenticator class in the server\java folder.
Make sure that this class implements the
authenticationData map to your authenticator to hold the credentials information.
This object is retrieved and used by a login module.
You must add a dependency on server runtime libraries to use server-related classes, for example, HttpServletRequest.
- Right-click your MobileFirst project and select Properties
- Select Java Build Path → Libraries and click Add Library
- Select Server Runtime and click Next
- You see a list of server runtimes that are installed in your Eclipse
- Select one and click Finish
- Click OK
init method is called when the authenticator is created. As its parameter, this method takes the map of options that is specified in a realm definition in the authenticationConfig.xml file.
clone method of the authenticator creates a deep copy of the object members.
processRequest method is called for each unauthenticated request to collect credentials.
processRequest() method takes the
isAccessToProtectedResource arguments. The method might retrieve data from a request and write data to a response, and must return a specific
AuthenticationResult status as described later.
authenticator collects the credentials for a
login module; it does not validate them.
The application sends an authentication request to a specific URL. This request URL contains a
my_custom_auth_request_url component, which is used by the
authenticator to make sure that this request is an authentication request. It is recommended to have a different URL component in every
authenticator retrieves the username and password that are passed as request parameters.
authenticator checks the credentials for basic validity, creates an
authenticationData object, and returns
SUCCESS means only that the credentials were successfully collected; after that, the
login module is called to validate the credentials.
If a problem occurs with the received credentials, the
authenticator adds an error message to the response and returns
CLIENT_INTERACTION_REQUIRED. The client must still supply authentication data.
isAccessToProtectedResource argument specifies whether an access attempt was made to a protected resource.
If not, the method returns
REQUEST_NOT_RECOGNIZED, which means that the
authenticator treatment is not required, and can proceed with the request as is.
If the request made to a protected resource does not contain authentication data, the
authenticator adds an
authStatus:required property to the response, and also returns a
getAuthenticationData method is used by a
login module to get collected credentials.
After the authenticated session is established, all requests are transported through the
processRequestAlreadyAuthenticated methods. You can use these methods to retrieve data from requests and to update responses.
changeResponseOnSuccess method is called after credentials are successfully validated by the
You can use this method to modify the response before you return it to the client.
This method must return
true if the response was modified, otherwise
false is returned.
Use it to notify a client application about the authentication success.
processRequestAlreadyAuthenticated method returns
AuthenticationResult objects for authenticated requests.
login module returns an authentication failure, the
processAuthenticationFailure method is called. This method writes an error message to a response body, and returns the
Creating a custom Java login module
The WorkLightAuthLoginModule API includes the following methods:
init method of the
login module is called when the
login module instance is created. This method receives the options that are specified in the
login module's definition of the authenticationConfig.xml file.
login method of the login module is used to validate the credentials that are collected by the
createIdentity method of the
login module is used to create a
userIdentity object after validation of the credentials succeeds.
abort methods are used to clean up cached data after a logout or authentication aborts.
clone method is used to create a deep copy of the class members.
MyCustomLoginModule class in the server\java folder. Make sure that this class implements the
Add two private class members,
PASSWORD, to hold the user credentials.
init method is called when the
login module instance is created. As its parameter, it takes the map of options that are specified in a login module definition in the authenticationConfig.xml file.
clone method of the
login module creates a deep copy of the object members.
login method is called after the
authenticator returns the
When called, the
login method gets an
authenticationData object from the authenticator.
login method retrieves the username and password that the
authenticator previously stored.
In this example, the
login module validates the credentials against hardcoded values. You can implement your own validation rules. The
login method returns
true if the credentials are valid.
If the validation fails, the
login method can either return
false or throw a
RuntimeException. The exception string is returned to the
authenticator as an
createIdentity method is called when the
login method returns
true. It is used to create a
UserIdentity object. You can store your own custom attributes in it to use later in Java or adapter code.
UserIdentity object contains user information. Its constructor is:
abort methods are used to clean up class members after the user logs out or aborts the authentication flow.
Creating the client-side authentication components▲
- Custom Authenticator and Login Module in hybrid applications
- Custom Authenticator and Login Module in native Android applications
- Custom Authenticator and Login Module in native iOS applications