2.3 Creating an Authentication Class

Identity Server architecture provides a programming interface that allows you to create a custom authentication class that can be plugged in to the Access Manager system. Custom authentication classes can define additional ways of obtaining and validating end-user credentials. You use the Access Manager Administration Console to identify your custom classes and specify any needed initialization properties. Custom classes must be configured to be in the class path of Identity Server.

The following sections explain project requirements and methods for creating a custom class:

For the Javadoc associated with these methods, see LocalAuthenticationClass.

2.3.1 Project Requirements

The project used to create the custom class must include nidp.jar shipped with Access Manager.

2.3.2 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. 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:

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.

SHOW_JSP

Further 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, 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:

  • Successful authentication: Indicates that a single user/object is located.

  • Unsuccessful authentication with an error: Indicates that more than one user/object is located.

2.3.3 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.

See authenticateWithPassword

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.

See authenticateWithQuery

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.

See findPrincipals

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.

See findPrincipalsByQuery

getCredentials()

Gets the list of credentials used to authenticate the user or principal. 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.

See getCredentials

addCredential()

Adds a credential used for authentication to a user or principal. This method is called by a class so that Identity Server can call the getCredentials() method.

See addCredential

addLDAPCredentials()

Adds an LDAP credential, other than the password, to a user or principal.

See addLDAPCredentials

clearCredentials()

Clears the credentials of the user or principal.

See clearCredentials

2.3.4 reCAPTCHA Methods

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.

Method

Description

recaptchaEnable

“true” or “false” if reCAPTCHA is enabled

recaptchaThreshold

“0” indicates always show the reCAPTCHA on the login page, “2” indicates that the failed login count must be 2 or more times before the reCAPTCHA displays

recaptchaSiteKey

The Google reCAPTCHA Site Key

recaptchaSecretKey

The Google reCAPTCHA Secret Key

2.3.5 Class Property Methods

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 5.0 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:

Method

Description

getProperty()

Obtains specific properties needed by an authentication class. Property values are specified when configuring the authentication class in Administration Console.

See getProperty

getBooleanProperty()

Returns a Boolean value for the specified property and sets a default value if the value cannot be found.

See getBooleanProperty

getType()

Identifies one of the authentication types known to Identity Server. The value returned by this method is used primarily when a service provider initiates an authentication request by asking for a specific authentication type.

When such a request is made, a check of all executed contracts is made. If a contract has executed a method by using a class that defines the particular type, the authentication succeeds. See Supported Authentication Class Types for a list of supported types.

See getType

getProvisionURL()

Gets the URL to call to provision a user and returns the redirect URL for user provisioning, or Null if it is not available.

See getProvisionURL

getReturnURL()

Returns the URL to which a user interaction should post data, or Null if it is not available.

See getReturnUrl

mustPersist()

Indicates whether the class must persist for interaction with the user during the entire authentication session. If this is the case, returns True. For more information about persistence, see Class Persistence.

See mustPersist

isFirstInstance()

Determines if this authentication class instance is the first instance after the system was started or was reconfigured. Returns True if it is the first instance.

See isFirstInstance

isCancelAppropriate()

Determines if the option to cancel an authentication is appropriate for this instance.

See isCancelAppropriate

isDefinesUser()

Determines if the authentication class instance needs to identify a user. If so, returns True.

For more information, see the Identifies User option in see Creating Authentication Methods in the Access Manager 5.0 Administration Guide.

See also isDefinesUser.

isUserIdentification()

Determines if this authentication class instance is the result of an assertion being returned to an unauthenticated session. The request for authentication is the result of an assertion from an identity provider, and it is necessary to identify the user for the purpose of completing the federation process.

See isUserIdentification.

isFirstCallAfterPrevMethod()

Defines the sequence of the authentication process after a method is called and determines if this authentication class instance is the result of an assertion being returned to an unauthenticated session.

This is useful to determine if an authentication class begins execution immediately after the successful completion of another class. This enables a class to know if credentials were actually used by the previous class.

See isFirstCallAfterPrevMethod.

isPendingAuthnRequest()

Determines whether there is a pending authentication request from a Service Provider. Returns True if there is a pending request, otherwise, returns False.

See isPendingAuthnRequest.

getAuthnRequest()

Gets the request that might have caused this authentication class to be invoked.

See getAuthnRequest

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. Identity Server can reply to such a request with all the contracts that fit the requested authentication type.

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 a browser to prompt a user for name and 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 multi-authentication method using a smart card.

AuthnConstants.OTHER

Default. Used for all other types not defined above.

Class Persistence

Persistence of a class is session based. A session is created when a user is prompted to provide credentials for a contract. Each method of a contract gets executed in the order defined in the contract. When a method executes, it creates an instance of the class. The class can persist between requests for credentials if necessary. If keeping state is not required by the class, then it does not need to persist. By default, classes persist. If this is not the desired behavior, use the mustPersist() method to return False.

If the class is configured to persist, the instance of the class persists as long as the doAuthenticate() or authenticate() method of the class returns HANDLED_REQUEST. When this method returns any other value, the instance of the class is removed. For a list of possible return values, see Section 2.3.2, doAuthenticate Method.

2.3.6 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.

Method

Description

setFailure()

Sets a failure state for the current authentication instance.

See setFailure

isFailure()

Indicates whether or not the authentication failed. Returns True if authentication failed, otherwise, returns False.

See isFailure

setUserErrorMsg()

Sets the error message to be displayed to an end user.

See setUserErrorMsg

getUserErrorMsg()

Gets the error message that will be displayed to the end user.

See getUserErrorMsg

getLogMsg()

Gets the message for the associated error ID. This method is used primarily by Identity Server to obtain the credentials verified by an authentication class.

See getLogMsg

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.

See setErrorMsg.

See Authentication Error Messages.

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.

See setErrorMsg.

See Authentication Error Messages.

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 user stores.

LOG_INTRUDER_DETECTION

(eDirectory) 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.

2.3.7 User Information Methods

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.

Method

Description

getPrincipal()

Gets the principal authenticated by this class. This value is Null if the authentication class is set to not define a user or if the authentication fails. This method is used primarily by Identity Server to obtain the credentials verified by an authentication class.

See getPrincipal

getPrincipalAttributes()

Gets the attributes for the principal that has been authenticated.

See getPrincipalAttributes

getPrincipalUserAuthority()

Gets the user authority for the identified principal, assuming that m_Principal has been set.

See getPrincipalUserAuthority

getUserAuthorityCount()

Gets the number of searchable user authorities.

See getUserAuthorityCount

getUserAuthority()

Gets a specific user authority. The getUserAuthorityCount() method returns the index range.

See getUserAuthority

setPrincipal()

Sets the principal to be authenticated by this class.

See setPrincipal

setPrincipalAttributes()

Sets attributes for a principal that has been authenticated.

See setPrincipalAttributes

setSessionProperties()

Sets user session properties that can be used later by other custom authentication classes and risk-based authentication rules.

With the following code snippet, you can set session properties by using custom authentication class:

// Create a new HashMap HashMap<String, Object> map = new HashMap<String, Object>(); map.put("Name", "InuputName"); map.put("ExternalEmail", "email@email.com"); // Call the API to set the Map setSessionProperties(map);

getSessionProperties()

Gets user session properties that were previously set by other custom authentication classes.

With the following code snippet, you can set session properties by using custom authentication class:

// Create a new HashMap HashMap<String, Object> map = new HashMap<String, Object>(); // Get the session properties from session map = getSessionProperties(); String email = (String)map.get("ExernalEmail");

getPrincipalAttributesFromPreferredLDAPReplica()

Gets the attributes for the authenticated Principal, from the last used User Store replica for a particular user session.

Use this method when there is a need to read attributes soon after the same were written to the User Store. This will avoid any errors that may occur in case the attributes have not been synchronized across all replicas yet.

setPrincipalAttributesInPreferredLDAPReplica()

Sets the attributes for the authenticated Principal, in the last used User Store replica for a particular user session.

Use this method to avoid any errors that may occur in case the attributes have not been synchronized across all replicas yet.

2.3.8 CallbackAuthentication Method

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 PasswordClass Example Code.

2.3.9 Other Methods

The following tables lists other useful methods:

Method

Description

showError()

Causes an error JSP to be executed to display an error message.

See showError

showJSP()

Forwards execution to a specific JSP.

See showJSP

escapeName()

Escapes characters typed by the user.

See escapeName

initializeRequest()

Initializes the authentication class with the current request/response.

Normally, this method is called only by Identity Server when it initializes the authentication class with the current request/response.

See initializeRequest.