Username/password based authentication

You can use authentication hook to perform Username/password based authentication.

This mechanism requires a client to supply a username and password on the opening of his Server API connection to the IBM Security Directory Integrator server. In order to configure this authentication method an authentication hook is used.

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 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 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 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 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 Directory Integrator Server folder. To deploy this sample LDAP authentication mechanism users can copy that file to the IBM Security 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";
}