Configure a Java Custom Authentication Scheme Instance

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.
casso1283
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.
This topic describes the following:
2
Creating a Custom Authentication Scheme
Follow these steps:
  1. Navigate to the Authentication Scheme dialog.
  2. Enter a name and description (optional) for the authentication scheme.
  3. Select Custom for the authentication type.
  4. Enter the name of the library.
    All custom authentication schemes in Java use the same library file,
    smjavaapi
    . This library file is included with the Policy Server.
  5. Enter any parameters in the parameter field after the class name. A space character separates the class name from the parameters list.
    The parameters are passed as a single string. Parameters can be delimited in any way that the custom class requires.
  6. Click Submit.
The authentication scheme is configured.
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.
After you have deployed a custom authentication template, you can specify this template when you configure an authentication scheme instance.
Custom SMAuthScheme Methods
query()
The query() method returns information about the authentication scheme or about the kind of credentials that the authentication scheme requires. The type of information returned to the Policy Server depends upon the type of information the Policy Server specifies when calling the method. The Policy Server passes the type of information it is looking for in the request parameter. The authentication scheme returns the information in the output parameter response.
Syntax
This method has the following format:
SmAuthStatus query(java.lang.String parameter,
                   java.lang.String secret,
                   SmAuthQueryCode request,
                   SmAuthQueryResponse response)
Parameters
This method includes the following parameters:
  • parameter
    The optional parameter string specified in the Administrative UI, to be used in any way that the authentication scheme requires.
  • secret
    The shared secret specified for the authentication scheme in the Administrative UI. The shared secret is used for any purpose that the authentication scheme requires, such as enryption or credentials operations. Your authentication scheme may or may not require a shared secret.
  • request
    The request code. The type of information that the authentication scheme returns in response depends upon the request code that the Policy Server passes, as follows:
    • SMAUTH_QUERY_DESCRIPTION
    • SMAUTH_QUERY_CREDENTIALS_REQ.
Response
The requested information to pass back to the Policy Server.
Returns
This method returns one of the following values:
  • SMAUTH_SUCCESS
    on success
  • SMAUTH_FAILURE
    on failure
init()
The init() method performs any initialization procedures that the authentication scheme requires. The Policy Server calls this method once for each authentication scheme instance.
Syntax
This method has the following format:
SmAuthStatus init(java.lang.String parameter,
                  java.lang.String secret)
Parameters
This method has the following parameters:
  • parameter
    Indicates the optional parameter string specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
  • secret
    Indicates an optional shared secret specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
Returns
This method returns one of the following values:
  • SMAUTH_SUCCESS
  • SMAUTH_FAILURE
authenticate()
The authenticate() method performs the custom authentication and returns the authentication result. The Policy Server calls this method at least once during user disambiguation and once during user authentication.
Syntax
This method has the following format:
SmAuthenticationResult authenticate(java.lang.String parameter,
                                    java.lang.String secret,
                                    int challengeReason,
                                    SmAuthenticationContext context)
Parameters
This method includes the following parameters:
  • parameter
    Indicates the optional parameter string specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
  • secret
    Indicates an optional shared secret specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
  • challengeReason
    Indicates the reason code from a previous authentication that failed or was challenged, or zero if unknown. The reason code that the gets passed is the REASON_ constant that the authentication scheme returned in SmAuthenticationResult after the failed or challenged authentication.
  • context
    Indicates an object that contains request context objects, and also methods for passing error and user messages directly to the Policy Server.
Returns
This method returns an SmAuthenticationResult object containing status and reason codes. How the returned status code is interpreted depends on the phase during which the authentication scheme is called, as follows:
  • During the user disambiguation phase:
    • SMAUTH_NO_USER_CONTEXT: The authentication scheme asks the Policy Server to disambiguate the user. When returning this status code, pass an empty string in setUserText().
    • SMAUTH_SUCCESS: The authentication scheme asks the Policy Server to disambiguate the user. When returning this status code, pass the user's login ID in setUserText().
    • SMAUTH_SUCCESS_USER_DN: The authentication scheme disambiguates the user and passes the complete user DN or ODBC database ID to the Policy Server. The information is passed in setUserText(). Only one DN or database ID can be passed at one time.
    • SMAUTH_ATTEMPT: The user cannot be found in the directory.
    • SMAUTH_FAILURE: An error occurred. Return any error text through setUserText().
       
  • During the user authentication phase:
    • 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 the Policy Server through setUserText(). Also, a reason code must be supplied in the SmAuthenticationResult object returned by authenticate(). The Policy Server passes back this reason code in the challengeReason parameter in a subsequent call to authenticate().
    • SMAUTH_FAILURE: An error occurred. Return any error text through setUserText().
release()
The release() method performs any rundown procedures that the authentication scheme requires. The Policy Server  calls this method once for each authentication scheme instance.
Syntax
This method has the following format:
SmAuthStatus release(java.lang.String parameter,
                     java.lang.String secret)
Parameters
This method includes the following parameters:
  • parameter
    Indicates the optional parameter string specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
  • secret
    Indicates an optional shared secret specified in the Administrative UI. The authentication scheme can use this parameter in any way that best suits its requirements.
Returns
This method returns one of the following values:
  • SMAUTH_SUCCESS
  • SMAUTH_FAILURE
Classes to use with in the SmAuthScheme Interface
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 the Policy Server.
SmAuthenticationResult
Contains status and reason codes returned to the Policy Server after a call to authenticate().
SmAuthQueryCode
Contains the type of request that the Policy Server is making of the authentication scheme (version number and description, or information about the credentials that the Policy Server must collect). The Policy Serverpasses 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 the Policy Server 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 the Policy Server.
SmAuthStatus
Contains Authentication API status codes such as SMAUTH_ACCEPT and SMAUTH_REJECT. This object can be passed back to the Policy Server 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 the Policy Server Loads the Custom Authentication Scheme Java
When user authentication is to occur against a custom authentication scheme created with the Java API, the Policy Server 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 the Policy Server Initializes Authentication Processing
Immediately after the scheme is loaded, the Policy Server calls the following methods in the custom class implemented from SmAuthScheme:
  • query().
     The Policy Server 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.
    When the Policy Server passes SMAUTH_QUERY_CREDENTIALS_REQ in query(), the Policy Server requesting that the authentication scheme specify the kind of credentials that are required. SiteMinder then collects the specified credentials.
  • init(). 
    The Policy Server 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.
The following figure shows how user credentials are authenticated:
custom java auth scheme flow
custom java auth scheme flow
Supported Credentials
Authentication of User Credentials
The following figure shows the key activities that occur during authentication:
The Java Authentication API supports authentication based on the following general types of credentials requirements:
  • Username/Password
  • X.509 Certificate
  • Custom user attributes
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
  • 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
. The Policy Server or the authentication scheme can disambiguate the user.
The Policy Server 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:
  1. User login
    . The user supplies a login ID (such as jsmith) for authentication purposes.
  2. 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.
  3. 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
The Policy Server first calls authenticate() at the beginning of the user disambiguation phase.
The Policy Server 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 the Policy Server  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 the Policy Server  to disambiguate the user. When returning this status code, the authentication scheme should also return an empty string through the setUserText() method. The Policy Server gets the login ID from the Agent, constructs the DN or search expression based on the login ID and the information defined in the Administrative UI User Directory Properties dialog box, and disambiguates the user by looking up the user in the user store.
  • SMAUTH_SUCCESS: The authentication scheme asks the Policy Server  to disambiguate the user. The authentication scheme passes the login ID to the Policy Server  through setUserText(). The Policy Server 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 the Policy Server  disambiguates the user.
    If the authentication scheme passes an empty string in setUserText(), the Policy Server 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 the Policy Server 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 the Policy Server through the setUserText() method.
User Authentication
During this phase, the Policy Server 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 the Policy Server  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 the Policy Server 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 authentication events. If authentication events are enabled in the realm where the user is being authenticated, the Policy Server  evaluates optional policies tied to OnAuthAccept
,
OnAuthReject
,
OnAuthAttempt
,
and OnAuthChallengerules. 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.
For more information, see Java SDK API Reference.