Username/password based authentication

Authentication hook

This hook allows the provision of custom JavaScript code that performs username and password based authentication. This hook allows bundlers/deployers to write customized JavaScript code, which given a username and password pair determines whether the authentication should succeed or not.

The property allowing for this custom JavaScript authentication is specified in the IBM® Security Verify Directory Integrator Server configuration file

global.properties or solution.properties:

api.custom.authentication. The api.custom.authentication property points to a JavaScript text file on the disk that contains custom authentication code. If this property is not specified then the IBM® Security Verify Directory Integrator 6.0 SSL-based authentication mechanism is used. When the api.custom.authentication property is specified, the JavaScript code contained in the specified file is executed for each username and password based authentication request.

The authentication script has access to the predefined script object userdata. This object provides the following two public members:

• userdata.username - contains the name of the user requesting authentication
• userdata.password - contains the password provided by the user

The script is free to perform whatever checks and authentication actions it needs. It returns whether the authentication is successful through the ret object:

• set ret.auth = true to specify that the authentication is successful
• set ret.auth = false to specify that the authentication is not successful; in this case the authentication script can provide additional information for why the authentication failed through the ret.errordescr attribute (for example ret.errordescr = "Invalid user name") and ret.errorcode (for example ret.errorcode = 1).

The description and error code fields is provided by the AuthenticationException thrown by the ServerAPI on unsuccessful authentication.

The authentication script has access to the main script object. It can be used for logging custom messages in the IBM® Security Verify Directory Integrator Server log file (for example main.logmsg("Authentication failed for user : " + userdata.username)).

An example authentication hook

An example authentication hook JavaScript file is available (in TDI_install_dir/examples) in order to demonstrate what the JavaScript of an authentication hook could look like. This example JavaScript can also be used as the basis of real-world IBM® Security Verify Directory Integrator authentication hooks. The example JavaScript demonstrates how an authentication hook can use an LDAP server (IBM Security Directory Server, Active Directory, and so on) for authenticating client requests.

The JavaScript file is named "ldap_auth.js" and is installed in the examples/auth_ldap IBM® Security Verify Directory Integrator Server folder. To deploy this sample LDAP authentication mechanism users can copy that file to the IBM® Security Verify Directory Integrator solution folder and specify api.custom.authentication=ldap_auth.js in *global.properties or solution.properties. The JavaScript code in "ldap_auth.js" tries to bind to an LDAP Server with the specified username and password. If the bind operation is successful, the script indicates a successful authentication, otherwise the authentication is rejected. The details for connecting to the LDAP Server like the server URL are specified in the "ldap_auth.js" script - this means that users have to edit this file and set the proper connection parameters before using the script. Here is the sample "ldap_auth.js" script: *

env = new Packages.java.util.Hashtable();
env.put("java.naming.factory.initial", "com.sun.jndi.ldap.LdapCtxFactory");
env.put("java.naming.provider.url", "ldap://192.168.113.54:389");
env.put("java.naming.security.principal", userdata.username);
env.put("java.naming.security.credentials", userdata.password);
env.put(Packages.javax.naming.Context.SECURITY_AUTHENTICATION, "simple");

main.logmsg("Authentication request for user: " +  userdata.username);

try
{
    mCtx = new Packages.javax.naming.directory.InitialDirContext(env);
    ret.auth = true;
}
catch(e)
{
    ret.auth = false;   
    ret.errordescr = e.toString();
//  ret.errorcode = "49";
}