There are a lot of details you need to know when you are writing your own Custom Authentication Class for Novell's Access Manager product.
We attempt to help by putting the things you need to know.
Java API 3.0.X
#
A very limited Java API for 3.0.X is documented by Novell
Do not know when or if Novell will publish a Java API for 3.1.X. The documentation does not address the doAuthenticate() method which was new back in in Access Manager 3.0 SP3 an later. The documentation uses the authenticate() method. Though 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.
Supported Authentication Class Types#
When you create an authentication class, you must specify an authentication type. An authentication type is required, because some service providers request contracts, not by URI, but by authentication type. The Identity Server can reply to such a request with all the contracts that fit the requested authentication type. The Identity Server supports the following types of authentication classes:| Constant | Description |
|---|---|
| AuthnConstants.BASIC | Specifies a basic authentication over HTTP. It uses the login page of the browser to prompt the user for a name and a password. |
| AuthnConstants.PASSWORD | Specifies a form-based authentication using a name and password over HTTP. |
| AuthnConstants.PROTECTED_BASIC | Specifies a basic authentication over HTTPS. It uses the login page of the browser to prompt the user for a name and a password. |
| AuthnConstants.PROTECTED_PASSWORD | Specifies a form-based authentication using a name and password over HTTPS. |
| AuthnConstants.X509 | Specifies authentication using an X.509 certificate. |
| AuthnConstants.TOKEN | Specifies a token-based authentication type. |
| AuthnConstants.SMARTCARD | Specifies a smart-card-based authentication method. |
| AuthnConstants.SMARTCARDPKI | Specifies a multiple authentication method using a smart card. |
| AuthnConstants.OTHER | Default. Used for all other types not defined above. |
doAuthenticate Method#
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 an later. 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.
The 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:
| Constant | Description |
|---|---|
| HANDLED_REQUEST | The request has been handled and a response provided. Further processing or information is needed to complete authentication. Typically, this value is returned when a page is returned to query for credentials. |
| NOT_AUTHENTICATED | The authentication failed. |
| AUTHENTICATED | The authentication succeeded in identifying a single NIDPPrincipal object (user). |
| CANCEL | The authentication process was canceled. This typically occurs only during authentication after a request from a service provider. |
| PWD_EXPIRING | Although authentication is successful, a user’s password is about to expire. This condition causes a redirection to the expired password servlet if one is defined on the authentication contract. |
| PWD_EXPIRED | Authentication is unsuccessful, because the user’s password is expired. This condition causes a redirection to the expired password servlet if one is defined on the authentication contract. |
When the doAuthenticate() method succeeds, you must return AUTHENTICATED. The doAuthenticate() method can succeed only when:
- a single NIDPPrincipal object from a Identity Data Store using the credentials obtained.
- credentials are verified
Each Identity Data Store is searched until one of the follow conditions is met:
- Successful authentication: Indicates that a single user/object is located.
- Unsuccessful authentication with an error: Indicates that more than one user/object is located.
Authentication Methods#
When implementing the doAuthenticate method(), you can use the following methods to retrieve and manage authentication credentials:| Method | Description |
|---|---|
| authenticateWithPassword() | Takes a user ID and password as its arguments. The method succeeds if a user with the given ID and password is located. |
| authenticateWithQuery() | Takes a string in the form of an LDAP query and a password as its as its arguments. It succeeds if the query result locates a single user with the associated password. |
| findPrincipals() | Locates the users in a directory that match the specified user ID. The method does not do any password verification. It returns an array of NIDPPrincipal objects that result from the search. |
| findPrincipalsByQuery() | Locates the users in a directory that match the specified LDAP query. The method does not do any password verification. It returns an array of NIDPPrincipal objects that match the query. |
| getCredentials() | Gets the list of credentials used to authenticate the user or principal. The Identity Server uses this method to obtain the credentials verified by an authentication class for possible later use with an Identity Injection policy. An authentication class does not typically call this method. |
| addCredential() | Adds a credential used for authentication to a user or principal. This method is called by a class so that the Identity Server can call the getCredentials() method. |
| addLDAPCredentials() | Adds an LDAP credential, other than the password, to a user or principal. |
| clearCredentials() | Clears the credentials of the user or principal. |
Authentication Error Messages#
The following error messages have been defined for the LocalAuthenticationClass and are returned:| Value | Error Message Description |
|---|---|
| LOG_INCORRECT_PASSWORD | The password entered does not match any of those authorized in the specified Identity Data Stores. |
| LOG_INTRUDER_DETECTION | (eDirectory only) The user account is locked because of intruder detection. |
| LOG_RESTRICTED_ACCOUNT | (eDirectory only) This account has restricted access and the user is attempting to access it during a time period when the account has been configured to deny access. |
| LOG_DISABLED_ACCOUNT | The account requested is disabled. |
| LOG_BAD_CONNECTION | The authentication channel is unable to communicate the user request. |
Status Methods#
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.- setFailure() - Sets a failure state for the current authentication instance.
- isFailure() - Indicates whether or not the authentication failed. Returns True if authentication failed, otherwise, returns False.
- setUserErrorMsg() - Sets the error message to be displayed to an end user.
- getUserErrorMsg() - Gets the error message that will be displayed to the end user.
- getLogMsg() - Gets the message for the associated error ID. This method is used primarily by the Identity Server to obtain the credentials verified by an authentication class.
- setErrorMsg() - Sets the error message to be seen by the end user, as well as the error message to be put into the log file.
- setErrorMsg() - Sets the error message to be seen by the end user, as well as the error message with a parameter to be put into the log file.
Other Methods#
The following are miscellaneous methods that you might find useful.- showErrorJSP() - Causes an error JSP to be executed to display an error message.
- showJSP() - Forwards execution to a specific JSP.
- escapeName() - Escapes characters typed by the user.
- initializeRequest() - Initializes the authentication class with the current request/response. Normally, this method is called only by the Identity Server when it initializes the authentication class with the current request/response.
Links for Authentication Classes#
- Authentication Class for OpenID Authentication
- Developer Docs 3.0.4
- Novell Access Manager SDK Sample Code
- Novell Access Manager SDK Sample Code 3.1