Custom Authentication Scheme Creation Uisng Java

Programming Guides › Programming Guide for Java › Java Authentication and Authorization Guidance › Custom Authentication Scheme Creation Uisng Java

Custom Authentication Scheme Creation Uisng Java

Authentication schemes provide a way to collect a user’s credentials and determine the user’s identity.

The Policy Server includes a variety of standard authentication schemes. These schemes range from basic user name/password authentication and HTML forms-based authentication to digital certificate and token authentication.

If the standard authentication schemes included with the Policy Server do not provide the kind of authentication functionality required at your site, you can use the Java Authentication API to create a custom authentication scheme.

Classes and Interfaces in the Authentication API

The base interface in the Java Authentication API is SmAuthScheme. All custom authentication schemes created with the Java Authentication API must implement this interface.

SmAuthScheme Methods

SiteMinder calls the following methods in the base interface SmAuthScheme:

Method	Description
authenticate()	Performs the custom authentication and returns the authentication result. SiteMinder calls this method at least twice—to establish user context and to authenticate the user’s credentials.
init()	Performs any initialization procedures that the authentication scheme requires. SiteMinder calls this method once for each authentication scheme instance, when the authentication scheme is loaded.
query()	Provides SiteMinder with either of the following kinds of information, depending on the value SiteMinder passes in the reason parameter (object SmAuthQueryCode): The version and description of the authentication scheme. The kind of credentials that SiteMinder should collect from the user, and optionally, the URL for the site where credentials should be collected.
release()	Performs any rundown procedures that the authentication scheme requires. SiteMinder calls this method once for each authentication scheme instance, when SiteMinder is shutting down.

Other Classes in the Authentication API

The following classes are used in conjunction with the SmAuthScheme base interface:

Class	Description
SmAuthenticationContext	Contains the following context classes passed to authenticate(): APIContext UserContext UserCredentialsContext The set... methods in this object pass information directly to SiteMinder.
SmAuthenticationResult	Contains status and reason codes returned to SiteMinder after a call to authenticate().
SmAuthQueryCode	Contains the type of request that SiteMinder is making of the authentication scheme (version number and description, or information about the credentials that SiteMinder must collect). SiteMinder passes this object to the authentication scheme in query().
SmAuthQueryResponse	Contains constants that specify the kind of credentials that are required for authentication, if any. Also allows a text message to be returned to SiteMinder for display to the user. Optionally, the authentication scheme can call setResponseBuffer() to specify a URL where credentials must be collected. The set... methods in this object pass information directly to SiteMinder.
SmAuthStatus	Contains Authentication API status codes such as SMAUTH_ACCEPT and SMAUTH_REJECT. This object can be passed back to SiteMinder in SmAuthenticationResult. It is also the return value type for the authentication scheme’s init(), query(), and release() methods.
UserCredentialsContext	Contains credentials information and other information from the user directory where user context was established. This object is contained in the SmAuthenticationContext object passed to authenticate().

How SiteMinder Loads a Custom Authentication Scheme in Java

When user authentication is to occur against a custom authentication scheme created with the Java API, SiteMinder loads the custom scheme by loading:

The standard library file smjavaapi that is installed with the Policy Server
An instance of the custom class implemented from SmAuthScheme

How SiteMinder Initializes Authentication Processing

Immediately after the scheme is loaded, SiteMinder calls the following methods in the custom class implemented from SmAuthScheme:

query(). SiteMinder passes SMAUTH_QUERY_DESCRIPTION in the request parameter, requesting that the authentication scheme pass back the version number and description of the Java Authentication API.
Note: When SiteMinder passes SMAUTH_QUERY_CREDENTIALS_REQ in query(), SiteMinder is requesting that the authentication scheme specify the kind of credentials that are required. SiteMinder then collects the specified credentials.
init(). SiteMinder passes the parameter string and shared secret that were defined when the authentication scheme was configured in the Policy Server. The scheme then performs any initialization procedures it requires.

Authentication of User Credentials

The following figure shows the key activities that occur during authentication:

An illustration describing how user credentials are authenticated.

Supported Credentials

The Java Authentication API supports authentication based on the following general types of credentials requirements:

Username/Password
X.509 Certificate
Custom user attributes

You specify the authentication credentials that are required through the setResponseBuffer() method in the object SmAuthQueryResponse. This object contains a number of constants that indicate the specific credentials that are required or whether no credentials are required.

User Disambiguation and Authentication

The authentication process includes two phases—user disambiguation and user authentication.

Before a user can be authenticated, the user’s profile information must be retrieved from the user store so that the user’s stored credentials can be compared with the credentials supplied at login. Looking up the user in a user store (such as an LDAP user directory or an ODBC database) is called user disambiguation. Either SiteMinder or the authentication scheme can disambiguate the user.

SiteMinder calls SmAuthScheme.authenticate() at least once during the disambiguation phase and at least once during the authentication phase:

During disambiguation, it is called once per directory where disambiguation occurred.
During authentication, it is called once per user found in the directory.

The basic steps are as follows:

User login. The user supplies a login ID (such as jsmith) for authentication purposes.
Disambiguation phase. Before the user lookup in the data store can begin, a complete DN or a search expression must be constructed based upon the supplied login ID. For example, if the login ID is jsmith, the DN used to search the user store might be constructed as follows:
```
uid=jsmith,ou=marketing,o=myorg.org
```
An LDAP search expression can also be used to search an LDAP user directory, and a SQL query is used to search an ODBC database—for example:
```
(&(objectclass=inetOrgPerson)(uid=jsmith))
```
select Name from SmUser where Name = 'jsmith'

Multiple results are possible, given that the LDAP DN or the ID stored in the ODBC database might apply to different users who have different passwords.
Authentication phase. The custom authentication scheme compares the known credentials of each disambiguated user with the credentials supplied during login—for example, by comparing the hash of the supplied password against the hash in the user store.

User Disambiguation

SiteMinder first calls authenticate() at the beginning of the user disambiguation phase.

Either SiteMinder or the custom authentication scheme can disambiguate the user. The authentication scheme indicates whether it has performed the disambiguation through a combination of the following:

One of the status codes listed below
Whether a value is passed to SiteMinder in the setUserText() method of SmAuthenticationContext

The status codes are set in the SmAuthStatus object. This object is passed in the status parameter of the SmAuthenticationResult constructor. SmAuthenticationResult is returned from authenticate():

SMAUTH_NO_USER_CONTEXT
The authentication scheme asks SiteMinder to disambiguate the user.

When returning this status code, the authentication scheme should also return an empty string through the setUserText() method. SiteMinder gets the login ID from the Agent, constructs the DN or search expression based on the login ID and the information defined in the SiteMinder User Directory Properties dialog box, and disambiguates the user by looking up the user in the user store.
SMAUTH_SUCCESS
The authentication scheme asks SiteMinder to disambiguate the user.

The authentication scheme passes the login ID to SiteMinder through setUserText(). SiteMinder uses that value to construct the DN or search expression and disambiguate the user in the user store. This approach gives the authentication scheme the opportunity to modify the login ID before SiteMinder disambiguates the user.

Note: If the authentication scheme passes an empty string in setUserText(), SiteMinder uses the login ID provided by the Agent (the same behavior as with return code SMAUTH_NO_USER_CONTEXT).
SMAUTH_SUCCESS_USER_DN
The authentication scheme disambiguates the user by constructing the complete DN or search expression and looking up the user in the user store. The authentication scheme passes the user’s complete DN or ODBC database ID to SiteMinder in setUserText(). Only one DN or database ID can be passed in setUserText().
SMAUTH_ATTEMPT.
The user cannot be found in the directory.
SMAUTH_FAILURE
This is returned if an error condition exists. Error text is returned to SiteMinder through the setUserText() method.

User Authentication

During this phase, SiteMinder calls authenticate() again to allow the authentication scheme to verify the supplied credentials after the user context has been established during disambiguation. The method sets one of the following status codes:

SMAUTH_ACCEPT. The user is authenticated.
SMAUTH_REJECT. The user is not authenticated.
SMAUTH_CHALLENGE. The user is challenged. The scheme passes the challenge message to SiteMinder through the setUserText() method. Also, a reason code must be supplied in the SmAuthenticationResult object returned by authenticate().
SMAUTH_FAILURE. An error condition occurred. Error text is passed to SiteMinder in setUserText().

Redirection

Your authentication scheme can have the Policy Server instruct the agent to perform a redirect. To build redirection capabilities into your authentication scheme:

Specify the redirection URL in:
```
SmAuthenticationContext.setErrorText()
```
When creating an SmAuthenticationResult object to return from authenticate(), specify REASON_ERROR_MESSAGE_IS_REDIRECT in the reason parameter of the constructor.

Authentication Events

Authentication results are tied to SiteMinder events. If authentication events are enabled in the realm where the user is being authenticated, SiteMinder evaluates optional policies tied to OnAuthAccept, OnAuthReject, OnAuthAttempt, and OnAuthChallenge rules. You can configure these policies to return custom responses based on a user’s identity, redirect the user to another location based on the result of the authentication, or update the user data in an external database.