2.3 Creating an Authentication Class

The project used to create the custom class must include the nidp.jar file shipped with Access Manager. This JAR file is located here:

A customized authentication class must extend the abstract class com.novell.nidp.authentication.local.LocalAuthenticationClass, which is found in nidp.jar. The base class contains a single required constructor. Your custom class must implement one of two methods, either doAuthenticate(), which is preferred, or authenticate(), which was used in previous releases of this SDK.

The doAuthenticate() method is new in Access Manager 3.0 SP3. Previous releases used the authenticate() method. The older method is still supported, but new classes created for SP3 and later should use the doAuthenticate() method because it performs additional Novell SecretStore® checks. SecretStore now supports a security flag that locks the SecretStore when secrets are modified. The doAuthenticate() method performs checks to determine the state of the SecretStore. If it is locked, it prompts the user to supply the passphrase that can be used to unlock the SecretStore. If you use the older authenticate() method and the SecretStore is locked, no indication of this state is returned. The SecretStore remains locked, and Access Manager cannot retrieve the secrets for policies or applications that require them.

Identity Server calls the doAuthenticate() method during its interaction with the class. Multiple calls to authenticate often are made to collect the necessary authentication credentials. The method returns a value indicating any of the following authentication states:

When the doAuthenticate() method succeeds, it needs to return AUTHENTICATED. It can succeed only when it obtains a single NIDPPrincipal object from a user store using the credentials obtained to verify the principal. After credentials are obtained, each user store is searched to locate a user identified by the credentials. Each user store is searched until one of the follow conditions is met:

When implementing the doAuthenticate method(), you can use the following methods to retrieve and manage authentication credentials:

To override the class properties, use the following properties at the Method Properties level. These must be set at the Method pages on the Properties page as custom properties. This is done because no modifications are done to the Method Properties to add convenient ways to set the captcha variables for the method. The interface changes are done only at the Authentication Class level.

Typically, classes have properties assigned to them. The installed Identity Server authentication classes have associated properties. Because these classes and their properties are known, Administration Console displays configuration pages for their required properties. For information about these properties, see Creating Authentication Classes in the NetIQ Access Manager 4.5 Administration Guide.

When you deploy your class, Administration Console has a generic page that allows an administrator to configure property key name and value pairs. When you create a class, you need to create a key name and value pair for each configuration item for which you want input from the administrator. For example, if you want to allow the administrator to use a different JSP page in the login form, you can create a key name of JSP with an expected value of filename. You would use the getProperty() method to obtain the value of the JSP key name. If the method returns null, you would have your code use your default JSP page. You need to document any key names that you create and the type of value that it requires, and make this information available to the administrator.

The class property methods return all values as strings. However, you can manipulate the string value as required by your code. For example, if your key name requires a number and the administrator configures the key name with a letter value, you need to decide how to handle such an error (continue and use a default value or throw an exception). As a minimum, the error should be logged, so that the administrator can discover the cause of the configuration problem.

The following methods are available for retrieving information about configuration properties:

The following methods allow you to set status information about the authentication instance, to retrieve status information about the instance, to set and get error messages, and to log messages.

The following methods allow you to set the identity of who has been authenticated and to set values for any associated attributes. If the instance is persistent, you can retrieve this same information. User authorities are the LDAP servers that Identity Server has been configured to use for verifying authentication credentials. The principal user authority is the LDAP server that was used to verify the user’s credentials.

To use a custom authentication class in the WS-Trust/STS/OAuth Resource Owner credential authentication, implement the com.novell.nidp.authentication.local.CallbackAuthentication interface in the authentication class.

To perform the STS/OAuth Resource Owner credential authentication, you need to implement the cbAuthenticate method in the authentication class.

For a sample implementation of cbAuthenticate, see Section 2.4.5, PasswordClass Example Code.

The following tables lists other useful methods: