Chapter 6 Using Authentication APIs and SPIs

This chapter provides information on using Sun Java™ System Access Manager 6 2005Q1 authentication programming interfaces to use and to extend the Authentication Service.

Overview of Authentication APIs and SPIs

Access Manager provides both Java APIs and C APIs for writing authentication clients that remote applications can use to gain access to the Authenticate Service. This communication between the APIs and the Authentication Service occurs by sending XML messages over HTTP(S). The remote-auth.dtd is the template used in formatting the XML request messages sent to Access Manager and for parsing the XML return messages received by the external application. You can access remote-auth.dtd in the directory AccessManager-base/SUNWam/dtd.

New authentication modules are added to Access Manager by using the com.iplanet.authentication.spi package. The SPI implements the JAAS LoginModule, and provides additional methods to access the Authentication Service and module configuration properties files. Because of this architecture, any custom JAAS authentication module will work within the Authentication Service.

How the Authentication Java APIs Work

How the Authentication C-APIs Work

XML/HTTP Interface for Other Applications

How the Authentication SPIs Work



Note	If contacting the Authentication Service directly through its URL (http://identity_server_host.domain_name:port/service_deploy_uri/authservice) without the API, a detailed understanding of remote-auth.dtd will be needed for generating and interpreting the messages passed between the client and server. Sample response and return XML messages can be found in Examples of XML Messages.

How the Authentication Java APIs Work

External Java applications can authenticate users with the Access Manager Authentication Service by using the Authentication Java APIs. The APIs are organized in a package called com.sun.identity.authentication and can be executed locally or remotely. The classes and methods defined in this package are used to initiate the authentication process and communicate authentication credentials to the specific modules within the Authentication Service. The classes and methods can be incorporated into a Java application to allow communication with the Authentication Service.

The first step necessary for an external Java application to authenticate to Access Manager is to create a new AuthContext object (com.sun.identity.authentication.AuthContext). The AuthContext class is defined for each authentication request as it initiates the authentication process. Since Access Manager can handle multiple organizations, AuthContext is initialized, at the least, with the name of the organization to which the requestor is authenticating. Once an AuthContext object has been created, the login() method is called indicating to the server what method of authentication is desired.

IndexName is the value of the authentication type. Table 6-1 summarizes IndexName values and their corresponding authetnication types.

Table 6-1 IndexName Values
IndexName Value	Authentication Type
AuthContext.IndexType.ROLE	Role-based
AuthContext.IndexType.SERVICE	Service-based
AuthContext.IndexType.USER	User-based
AuthContext.IndexType.LEVEL	Authentication Level-based
AuthContext.IndexType.MODULE_INSTANCE	Module-based

The getRequirements() method then calls the objects that will be populated by the user. Depending on the parameters passed with the instantiated AuthContext object and the two method calls, Access Manager responds to the client request with the correct login requirement screens. For example, if the requested user is authenticating to an organization configured for LDAP authentication only, the server will respond with the LDAP login requirement screen to supply a user name and a password. The client must then loop by calling the hasMoreRequirements() method until the required credentials have been entered. Once entered, the credentials are submitted back to the server with the method call submitRequirements(). The final step is for the client to make a getStatus() method call to determine if the authentication was successful. If successful, the caller obtains a session token for the user; if not, a LoginException is thrown.

Because the Authentication Service is built on the JAAS framework, the Authentication API can also invoke any authentication modules written purely with the JAAS API.

For detailed information about Java APIs for authentication, see the Javadoc in the following directory:

How the Authentication C-APIs Work

C applications can authenticate users with the Access Manager Authentication Service by using the Authentication C-API. The C application contacts the Authentication Service to initiate the authentication process, and the Authentication Service responds with a set of requirements. The client application submits authentication credentials back to the Authentication Service and receives further authentication requirements back until there are no more to fulfill. After all requirements have been sent, the client makes one final call to determine if authentication has been successful or has failed. The C API can be found in IdentityServer_base/SUNWam/agents. This directory also includes a C API samples directory.



Caution	Previous releases of Access Manager contained C libraries in IdentityServer_base/lib/capi. The capi directory is being deprecated, and is currently available for backward compatibility. It will be removed in the next release, and therefore it is highly recommended that existing application paths to this directory are changed and new applications do not access it. Paths include RPATH, LD_LIBRARY_PATH, PATH, compiler options, etc.)

The sequence of calls necessary to authenticate to Access Manager begins with the function call am_auth_create_auth_context. This call will return an AuthContext structure used for the rest of the authentication calls. Once an AuthContext structure has been initialized, the am_auth_login function is called. This indicates to the Authentication Service that an authentication is desired. Depending on the parameters passed when creating the AuthContext structure and making the am_auth_login function call, the Authentication Service will determine the login requirements with which to respond. For example, if the requested authentication is to an organization configured for LDAP authentication, and no authentication module chaining is involved, the server will respond with the requirements to supply a user name and a password. These attributes correspond to elements in the remote-auth.dtd structure. The user name corresponds to the NameCallback element; the password which corresponds to the PasswordCallback element. The client loops on function call am_auth_has_more_requirements (in this specific case there will be two). The client then fills in the needed information and submits this back to the server with function call am_auth_submit_requirements. The final step is to make function call am_auth_get_status to determine if the authentication was successful or not.

XML/HTTP Interface for Other Applications

Applications written in a programming language other than Java or C can exchange authentication information with Access Manager using the XML/HTTP(s) interface. Using the URL http://server_name.domain_name:port/service_deploy_uri/authservice, an application can open a connection using the HTTP POST method and exchange XML messages with the Authentication Service. The structure of the XML messages is defined in remote-auth.dtd. In order to access the Authentication Service in this manner, the client application must contain the following:

A means of producing valid XML compliant with the remote-auth.dtd.

HTTP 1.1 compliant client implementation to send XML-configured information to Access Manager.

HTTP 1.1 compliant server implementation to receive XML-configured information from Access Manager.

An XML parser to interpret the data received from Access Manager.

Examples of XML Messages

The following code examples illustrate how customers might configure the XML messages posted to the Authentication Service.

Code Example 6-1 illustrates the initial XML message sent to the Access Manager. It opens a connection and asks for authentication requirements regarding the exampleorg organization to which the user will login.

Code Example 6-1 Initial AuthContext XML Message


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="0">
<NewAuthContext orgName="dc=exampleorg,dc=com">
</NewAuthContext>
</Request>
</AuthContext>

Code Example 6-2 illustrates the successful response from Access Manager that contains the authIdentifier, the session identifier for the initial request.

Code Example 6-2 AuthIdentifier XML Message Response


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="in_progress">
</LoginStatus>
</Response>
</AuthContext>

Code Example 6-3 illustrates the client response message back to Access Manager. It specifies the type of authentication module needed by the user to log in.

Code Example 6-3 Second Request Message With Authentication Module Specified


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<Login>
<IndexTypeNamePair indexType="moduleInstance">
<IndexName>LDAP</IndexName>
</IndexTypeNamePair>
</Login>
</Request>
</AuthContext>

Code Example 6-4 illustrates the return message from Access Manager which specifies the authentication module’s login requirements. In this case, the LDAP requirements include a user name and password. Note the page time out value of 120 seconds.

Code Example 6-4 Return XML Message With Login Callbacks


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<GetRequirements>
<Callbacks length="3">
<PagePropertiesCallback isErrorState="false">
<ModuleName>LDAP</ModuleName>
<HeaderValue>This server uses LDAP Authentication</HeaderValue>
<ImageName></ImageName>
<PageTimeOut>120</PageTimeOut>
<TemplateName></TemplateName>
<PageState>1</PageState>
</PagePropertiesCallback>
<NameCallback>
<Prompt>User Name: </Prompt>
</NameCallback>

<PasswordCallback echoPassword="false">
<Prompt> Password: </Prompt>
</PasswordCallback>

</Callbacks>
</GetRequirements>
</Response>
</AuthContext>

Code Example 6-5 illustrates the client responses to the call for login requirements. They specify amadmin as the user and 11111111 for the password.

Code Example 6-5 Response Message With Callback Values


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<SubmitRequirements>
<Callbacks length="3">

<NameCallback>
<Prompt>User Name:</Prompt>
<Value>amadmin</Value>
</NameCallback>

<PasswordCallback echoPassword="false">
<Prompt>Password:</Prompt>
<Value>11111111</Value>
</PasswordCallback>
</Callbacks>
</SubmitRequirements>
</Request>
</AuthContext>

Code Example 6-6 illustrates that a successful authentication has occurred. As the value of <Subject> uses the Java serialization, it can not be used by non-Java client applications. It’s value is retrieved by all applications from the session token.

Code Example 6-6 Successful Authentication XML Message


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=" successURL="http://torpedo.red.iplanet.com:/amconsole">
<Subject>AQICweczOhuelZ5TqD9kKOtiAepxqGP23q4oTnNMuJY//lI2S4KD1/gEN84uLwDGHl llyFSthxoKLM7NDH h2vwAvrDmpsomJvUnbqnJJ90DS+28njGiDv+lv8FqIVhhbxrctbiIUEOHYK0FzXnXjPYizdCmiW XJ+9DJ8T2HbYIDxn9U6eVNAMPq3uVb/RFuErEm5MuPu7PnWeCic12SZre4ZEcw8TI45NKNjd/NZ ZD97bcqL5gEV7SVHspFldZKmo9vA86aEkvMs9P53RiJtrusHN1FKt9+4JqSrdcVLKMzJVAr3z5E ohwHh9/hzd7hgucO661gz7IqkT7WEpve/E8R4em0mg3HgHg7Bg7i3AkyX6YSkoAncdVXMdmWnb7 OV5cBgUjO8zs8Pp5/3dA1XlwACmOqjxshk6Y6Ld6TAQ90qRFwymC1RdLGGCRnrt33kmYVyB1lJy JxT8utPKyDOEKFRHh57NlKTbFhBKc1IGcdQ2crHifpXawx6YouQgQSWGdsqW9IahY4+lqbBTPnG DyZkKz9yy2ZKVjDR05Hwku8elvEwBE40XTJ3gF/mbwCGbh3cyprahLqRXboy8eoEQf3ubQmR2My +bh+NrsRfzfFV5oCcpJE6DtvYE/4zO+uKk3FbG+/NUJzAAor920V/0prtYeS58ZPW8C7qwXINaW 0xdMQV+pgE3NZvMlp5GeZlSIMmSCtXD49n4tqopSlsoK+eiwPODKxp992+6/uJhhVHH5I0Ozuy6 CDM dCJDGvnMENVCUZvki3+tb92fqQbVWixM4Ca6Nnz3jTIKk2uhm559jq9hra8gHHOfnnu4e5jZjzf RdkO3GodiTMOHDnQATHtvT1PBXgorTfUwUa4ZjptvzFulHSi4eQaqs4Z8FAX2OAr8XGHRkhBwox rhjYiCDBpkNmpEiFNhWnTT3bwkAUFhtoDg6836kwHfxeLXKAz3T6qyNQzT+larSXUxrt/TIjwDP R3vg4GF4RzbHlWA1WQtUS/9Qe/N3aegEEEvxPvo9fWq</Subject>
</LoginStatus>
</Response>
</AuthContext>

How the Authentication SPIs Work

Extending the AMLoginModule Class

Pluggable JAAS Module

Authentication Post Processing

Access Manager provides the capability to plug new, Java-based authentication modules into its framework allowing proprietary authentication providers to be managed using the Access Manager console. A custom authentication module must first be created using Java. Once created, the custom module can be added to the list of available authentication modules.

Extending the AMLoginModule Class

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class. The class must also implement the init(), process() and getPrincipal() methods in order to communicate with the authentication module configuration files. The callbacks are then dynamically generated based on this file. Other methods that can be defined include setLoginFailureURL and setLoginSuccessURL which defines URLs to send the user to based on a failed or successful authentication, respectively.

Pluggable JAAS Module

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization. Access Manager supports pure JAAS pluggable authentication modules. In Access Manager, pure JAAS modules extend the JAAS LoginModule rather than AMLoginModule. A pure JAAS module is plugged in to the Authentication framework using the Authentication API.

Authentication Post Processing

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The following are examples of post-processing tasks:

Adding attributes to a user’s session after successful authentication

Sending notification to an administrator after failed authentication

General clean-up such as clearing cookies after logout or logging out of other system components.

The Core Authentication Service contains the Authentication PostProcessing Class attribute which contains the authentication post-processing class name as its value. Custom post processing interfaces can also be implemented.

AMPostAuthProcessInterface can be implemented for post authentication processing on authentication success, failure and logout. The SPI is configurable at the organization , service and role levels. The Authentication Service invokes the post processing SPI methods on successful, failed authentication and logout.

onLoginSuccess

onLoginFailure

onLogout

Some supporting information on these methods is provided in the following sections. For a comprehensive listing and detailed information on all Access Manager methods, see the Javadoc installed in the following directory:

onLoginSuccess

This method should be implemented for post-processing after a successful authentication. Authentication Service will invoke this method on successful authentication.

requestMap is a map containing HttpServletRequest parameters

request HttpServletRequest object

response HttpServletResponse object

onLoginFailure

This method should be implemented for post processing after a failed authentication. Authentication Service will invoke this method on failed authentication.

requestMap is a map containing HttpServletRequest parameters

request HttpServletRequest object

response HttpServletRequest object

onLogout

This method should be implemented for post-processing on a logout request. Authentication Service will invoke this method on logout.

request HttpServletRequest object is a map containing HttpServletRequest parameters

response HttpServletResponse object

ssoToken authenticated user's single sign on token

Using Authentication APIs

Access Manager comes with a number of sample programs that demonstrate how you can use the Authentication APIs to extend the functionality of the authentication service and authentication modules.

Running the Sample Authentication Programs

Running the Sample Authentication Programs

The source code and Makefile are provided for all sample programs. For some sample programs, additional supporting files are also included.The instructions for compiling and executing the sample programs are the same for all samples described in this section. See To Compile and Execute the Java API Samples. Instructions for configuring the sample programs to run in Secure Sockets Layer (SSL) mode are also included in this section. See To Configure SSL for Java API Samples.

Java API Code Samples and Their Locations

The following tables describe the locations of all the files you need to implement the sample programs on various platforms, and the variable names used for default directories in the source code and Makefiles. Table 6-2 summarizes file locations and variable names used for Solaris Sparc/x86.l Table 6-3 summarizes default directories for Linux. Table 6-4 summarizes default directories for Windows 2000.


Variable	Description	Location
Api_sample_dir	Directory that contains authentication API sample files	<install_root>/SUNWam/samples/authenitcation/api
Config_directory	Directory that contains configuration files	/etc/opt/SUNWam/config
Product_Directory	Directory where Access Manager is installed.	install_root>/SUNWam


Variable	Description	Location
Api_Sample_Dir	Directory that contains authentication API sample files	<install_root>/sun/identity/samples/authentication/api
Config_Directory	Directory that contains configuration files	/etc/opt/sun/identity/config
Product_Directory	Directory where Access Manager is installed.	<install_root>/sun/identity

Table 6-4 Default directories for Windows 2000
Variable	Description	Location
Api_Sample_Dir	Directory that contains authentication API sample files	<install_root>\samples\authentication\api
Config_Directory	Directory that contains configuration files	<install_root>\lib
Product_Directory	Directory where Access Manager is installed.	<install_root>

To Compile and Execute the Java API Samples

In the Makefile, modify the following variables as necessary to suit your Access Manager installation:

BASE_DIR: Enter the path to the directory where Access Manager is installed.

JAVA_HOME: Enter the path to the directory where the Java compiler is installed.

DOMAIN: Enter the name of the organization to login to.

SHARE_LIB: Enter the path to the directory where Access Manager jar files are stored.

JSS_JAR_PATH: Enter the path to the directory where JSS jar files are stored.

JSSPATH: Enter the path to the directory where JSS libraries are located.

In the Certificate Sample Makefile only, modify the following as necessary:

CERTNICKNAME: Enter the Certificate nickname.

URL: Enter the Access Manger Server URL.

PASSWORD: Enter the Certificate DB Password.

Copy AMConfig.properties from Config_Directory in the Access Manager server installation to the client machine.

(Note: For SSL check SSL Configuration Setup, step 2).

In the Makefile, update the classpath to include the location of the newly created AMConfig.properties.

In the client machine, create a directory named locale. Then copy all the property files from the locale directory in the Access Manager server installation machine to the client machine. The locale directory on the server machine can be found under the Product_Directory.

Update the classpath in the Makefile to include the location of newly created locale files.

Include jaas.jar in your classpath if you are using a JDK version less than JDK1.4

Compile the program.

On Solaris Sparc/x86, Linux, run the gmake command.

On Windows 2000, run the make command.

Run the sample program.

On Solaris Sparc/x86 or Linux, run the following command: gmake run

On Windows 2000, run the following command: make run

To Configure SSL for Java API Samples

In the Makefile, add this JVM property in the run target:

-D "java.protocol.handler.pkgs=com.iplanet.services.comm"

Copy AMConfig.properties from Config_Directory in the Access Manager server installation to the client machine.

Edit the following properties in AMConfig.properties.

com.iplanet.am.admin.cli.certdb.dir: Enter the path to the certificate database directory.

com.iplanet.am.admin.cli.certdb.prefix: Enter the certificate database prefix.

In the LDAP and JCDI Samples only:

com.iplanet.am.server.protocol: Change the value to https.

com.iplanet.am.server.port: Enter the appropriate port number from the server machine.

Create or copy the certificate database file to the certificate db directory. Use the directory name in com.iplanet.am.admin.cli.certdb.dir.

Rename the file to use the prefix specified in the property com.iplanet.am.admin.cli.certdb.prefix.

LDAPLogin Example

The LDAPLogin sample is an example of a custom Java application that uses the authentication remote APIs to authenticate to the LDAP module. You can modify the sample source code to authenticate to other existing or customized authentication modules. The sample source code, Makefile, and Readme.html are located in the following directory:

CertLogin Example

The CertLogin sample is an example of a custom Java application that uses digital certificates for authentication. You can modify the sample source code to authenticate to other existing or customized authentication modules. The sample source code, Makefile, and Readme.html are located in the following file:

To Run the CertLogin Program

Enable SSL.

Follow the instructions in To Configure SSL for Java API Samples.

Compile and execute the sample code.
To Compile and Execute the Java API Samples.

Using certutil for Client Certificate Management

Certutil is a command-line utility that can create and modify cert7.db and key3.db database files. It can also list, generate, modify, or delete certificates within the cert7.db file and create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key3.db file. The key and certificate management process usually begins with creating keys in the key database, then generating and managing certificates in the certificate database.

JCDI Module Example

The JCDI Module Example demonstrates the use of Java Card Digital ID (JCDI) authentication with Access Manager. The sample has two components:

Remote client

Server JCDI authentication module

The sample illustrates JCDI authentication using the Remote Authentication API.You can modify the sample source code to authenticate to other existing or customized authentication modules. The source code, Makefile, and Readme.html are located in the following directory:

C-API Sample

Access Manager provides a sample program to demonstrate how an external C application can use the API to authenticate a user via Access Manager. The sample can be found in IdentityServer_base/SUNWam/agents/samples/common/.

By default, the C Authentication sample checks the directory IdentityServer_base/SUNWam/agents/config for a properties file named AMAgent.properties.

Code Example 6-7 lists the properties that are needed by the C Authentication API. Some of these are defined in AMAgent.properties and some are not. Those that are not defined in AMAgent.properties can be added to the file so they needn’t be identified for each function call. For example, com.sun.am.auth.orgName, which identifies the organization from which you want to authenticate, can be added to AMAgent.properties.

C Header File. The C Authentication API header file, am_auth.h, can be found in IdentityServer_base/SUNWam/agents/include. It contains the function prototypes for the function calls available in the C Authentication API.

Code Example 6-7 AMAgent.properties File


# SOME PROPERTIES LISTED ARE NOT PRE-EXISTING IN THE PROPERTIES FILE

# the identity server naming service url
com.sun.am.namingURL=http://serverexample.domain.com:58080/amserver/namings ervice
# the directory to use for logging
com.sun.am.logFile=/home/uid/logs/auth-log
# the logging level, all:5 being the highest and all:3 being medium
com.sun.am.logLevels=all:5
# the directory containing the certificate and key databases
com.sun.am.sslCertDir=/home/level/certdir
# the prefix of the cert7.db and key3.db files, if any
com.sun.am.certDbPrefix=
# the password to the key3.db file
com.sun.am.certDBPassword=11111111
# true to trust SSL certificates not in the client cert7.db
com.sun.am.trustServerCerts=true
# the nick name of the client certificate in the cert7.db
com.sun.am.auth.certificateAlias=Cert-Nickname
# the identity server organization desired for authentication
com.sun.am.auth.orgName=dc=sun,dc=com

Using Authentication SPIs

Access Manager provides the following sample programs to demonstrate how you can use the Authentication service provider interfaces (SPIs) to extend authentication functionality:

Implementing a Custom Authentication Module

Implementing Authentication PostProcessing SPI

Generating an Authentication User ID

Implementing A Pure JAAS Module

Implementing a Custom Authentication Module

Access Manager contains a sample exercise for integrating a custom authentication module with files that have already been created. This sample illustrates the steps for integrating an authentication module into the Access Manager deployment. All the files needed to compile, deploy and run the sample authentication module can be found in the following directory:

Writing a Sample Login Module

Compiling and Deploying the LoginModule program

To Deploy the Login Module Sample Program

Loading the Login Module Sample into Access Manager

Running the LoginModule Sample Program

Deploying the Login Module Sample Program

About the Login Module Sample

Writing a Sample Login Module

Use the AMLoginModule SPI (Service Provider Interface) to write your own sample login module. Three steps are required:

Create a Module Properties File.

Write the Principal Class.

Implement the LoginModule Interface.

The following are the default directories used in the sample exercise for the various platforms:

Create a Module Properties File

Create a Module properties XML file with the same name of the class (no package name) and use the extension .xml. You must create an XML file with this naming convention even if no states required

Based on this configuration file, the Authentication user interface will dynamically generate a login page.

You can define page states in the module properties file as shown in Code Example 6-8. Each callback element corresponds to one login page state. When an authentication process is invoked, Callback[] values will be generated from the user's Login Module for each state. All login state definitions start with 1. The module controls the login process, and then determines what the next state is.

Auth_Module_Properties.dtd defines the data structure that will be used by each authentication module to specify its properties. Auth_Module_Properties.dtd provides definitions to initiate, construct and send required callbacks information to the Authentication UI. Auth_Module_Properties.dtd is stored in the <PRODUCT_DIR>/dtd directory.


<ModuleProperties moduleName="LoginModuleSample" version="1.0" >
<Callbacks length="2" order="1" timeout="60" header="This is a sample login page" >
<NameCallback>
<Prompt> User Name </Prompt>
</NameCallback>
<NameCallback>
<Prompt> Last Name </Prompt>
</NameCallback>
</Callbacks>
<Callbacks length="1" order="2" timeout="60" header="You made it to page 2" >
<PasswordCallback echoPassword="false" >
<Prompt> Just enter any password </Prompt>
</PasswordCallback>
</Callbacks>
</ModuleProperties>

In the module configuration sample in Code Example 6-8, page state one has two callbacks. The first callback is for user ID, and second is for Last Name. When the user fills in the callbacks, the following events occur:

The Callback[] values are sent to the module.

The process() routine validates the callback values, and then returns what?.

The module writer sets the next page state to 2.

Page state 2 has one callback to request the user to enter a password. The process() routine is again called after the user submits the Callback[] values. If the module writer throws a LoginException, then an Authentication Failed page will be sent to the user. If no exception is thrown, the user is redirected to his or her default page.

Write the Principal Class

After creating module configuration xml file, the next step is to write a Sample Principal class which implements java.security.Principal. The constructor takes the user’s username as an argument. If authentication is successful, the module will return this principal to Authentication framework. The Authentication framework populates a Subject with a SamplePrincipal representing the user.

Implement the LoginModule Interface

AMLoginModule is an abstract class which implements JAAS LoginModule. AMLoginModule provides methods for accessing Access Manager services and the module XML configuration. Login Module writers must subclass AMLoginModule class and implement the following methods:

init()

process()

getPrincipal()

For detailed descriptions, syntax, and parameters, see the Javadoc. The following provides some supporting information about these methods.

init() This is an abstract method, Module writer should implement to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, the data can be ignored. This method is called by a AMLoginModule after this SampleLoginModule has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use. The init method may additionally peruse the provided sharedState to determine what additional authentication state it was provided by other LoginModules, and may also traverse through the provided options to determine what configuration options were specified to affect the LoginModule's behavior. It may save option values in variables for future use.

process() The process method is called to authenticate a Subject. This method implementation should perform the actual authentication. For example, it may cause prompting for a user name and password, and then attempt to verify the password against a password database. If your LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule's process method should invoke the handle method of the CallbackHandler passed to this method to perform the user interaction and set appropriate results, such as the user name and password and the AMLoginModule internally passes the UI an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the UI performs the requested user interaction and sets appropriate values in the Callbacks.

Perform the authentication. If Authentication succeeded, save the principal who has successfully authenticated.

Return -1 if authentication succeeds, or throw a LoginException such as AuthLoginException if authentication fails or return relevant state specified in module configuration XML file

If multiple states are available to the user, the Callback array from a previous state may be retrieved by using the getCallbak(int state) methods. The underlying login module keeps the Callback[] from the previous states until the login process is completed.

If a module writer needs to substitute dynamic text in next state, the writer could use the getCallback() method to get the Callback[] for the next state, modify the output text or prompt, then call replaceCallback() to update the Callback array. This allows a module writer to dynamically generate challenges, passwords or user IDs. Note: Each authentication session will create a new instance of your Login Module Java class. The reference to the class will be released once the authentication session has either succeeded or failed. It is important to note that any static data or reference to any static data in your Login module must be thread-safe.

getPrincipal() This method should be called once at the end of a successful authentication session. A login session is deemed successful when all pages in the Module properties XML file have been sent and the module has not thrown an exception. The method retrieves the authenticated token string that the authenticated user will be known by in the Access Manager environment.

Compiling and Deploying the LoginModule program

If you are writing your own Custom Authentication module based on the AMLoginModule SPI or a pure JAAS module, then you can skip this step. Otherwise, after writing the sample Login Modue, compile and deploy the sample found under AccessManager-base/samples/authentication/spi/providers.

To compile the Login Module

Set the following environment variables.

These variables will be used to run the gmake command. You can also set these variables in the Makefile. This Makefile is in the following directory: AccessManager-base/samples/authentication/spi/providers.

JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

CLASSPATH: Set this variable to refer to am_services.jar which can be found in the Idetnity_base/lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)

BASE_DIR: Set this variable to the directory where the Access Manager is installed.

BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

In the AccessManager-base/samples/authentication/spi/providers directory, run gmake.

To Deploy the Login Module Sample Program

Copy LoginModuleSample.jar from JAR_DIR to AccessManager-base/web-src/services/WEB-INF/lib.

Copy LoginModuleSample.xml from AccessManager-base/samples/authentication/spi/providers to AccessManager-base/web-src/services/config/auth/default.

Redeploy the amserver.war file.

See Appendix C, "WAR Files" for detailed information on deploying Access Manager .war files.

Loading the Login Module Sample into Access Manager

Once you’ve compiled and deployed the login module, you must load the login module into Access Manager. You can load the login module by using either the Access Manager administration console, or by using the amadmin command.

To Load the Login Module Using the Administration Console

Click Service Configuration.

In Service Configuration frame, under Authentication, click Core.

Add class file name com.iplanet.am.samples.authentication.spi.providers.
LoginModuleSample
to the Pluggable Auth Modules Classes list.

Click Save.

To Load the Login Module Using using the Command Line

Write a sample XML file as shown in Code Example 6-9, which will add the LoginModuleSample auth module entry into the allowed modules and an authenticators list.

Code Example 6-9 Adding the LoginModuleSample entry.



<!--
Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved
Use is subject to license terms.
-->

<!DOCTYPE Requests
PUBLIC "-//iPlanet//iDSAME 5.0 Admin CLI DTD//EN"
"jar://com/iplanet/am/admin/cli/amAdmin.dtd"
>

<Requests>

<SchemaRequests serviceName="iPlanetAMAuthService" SchemaType="Global">
<AddDefaultValues>
<AttributeValuePair>
<Attribute name="iplanet-am-auth-authenticators"/>

<Value>com.iplanet.am.samples.authentication.spi.providers.LoginModuleSampl e</Value>
</AttributeValuePair>
</AddDefaultValues>

</SchemaRequests>
</Requests>

Use amadmin to load sample.xml:

<AMADMIN> --runasdn uid=amAdmin,ou=People,<root_suffix> --password <password> --data sample.xml

Running the LoginModule Sample Program

This sections provides instructions for running the login module on Solaris and on Windows platforms.

To Run the LoginModule on Solaris

Use the following URL to log in to Access Manager console as amAdmin: http://<host>.<domain>:<port>/<Console-Deploy-URI>

Click Identity Management, and in the Identity Management view select your organization.

From the View menu, select Services.

In the navigation frame, under Authentication, click Core.

Select LoginModuleSample to add it to the list of highlighted modules in Organization Authentication Modules.

Click Save.

Log out.

Enter the following URL:

http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login?module=
LoginModuleSample

If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter.

To Run the Login Module on Windows 2000

Set the following environment variables. These variables will be used to run the make command. You can also set these variables in the Makefile.

This Makefile is in the same directory as the Login Module Sample program files: AccessManager-base\samples\authentication\spi\providers

JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

BASE: Set this variable to base-directory

CLASSPATH: Set this variable to refer to am_services.jar which can be found in the base-directory\lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)

BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

In the base-directory\samples\authentication\spi\providers directory, run the make command.

Deploying the Login Module Sample Program

To Deploy the Login Module

Copy LoginModuleSample.jar from JAR_DIR to AccessManager-base\web-src\services\WEB-INF\lib

In the Web Container from which this sample has to run, update the classpath with LoginModuleSample.jar.

Update server.xml with the new classpath and server.xml locations:

Sun Java System Web Server : <WS-install-dir>\https-<WS-instance-name>\config\server.xml

Sun Java System Application Server: <AS-install-dir>\domain\<appserver domain>\<appserver_instance>
\config\server.xml
Example:
<AS-install-dir>\domain\domain1\server1\config\server.xml

Copy LoginModuleSample.xml from base-directory\samples\authentication\spi\providers to base-directory\web-src\services\config\auth\default.

Restart the web container

WebServer: <WS-home-dir>\https-<WS-instance-name>\restart

Application Server: AppServer-home-dir>\domains\
<domain name>\<server_instance>\bin\restartserv

Implementing Authentication PostProcessing SPI

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The AMPostProcessInterface Javadocs are available at:

AccessManager-base/SUNWam/docs/com/sun/identity/authentication/spi/
AMPostAuthProcessInterface.html

The SPI is configurable at the organization, service and role levels. The Authentication Service invokes the post processing SPI methods on successful or failed authentication and on logout.

About the PostProcessing SPI Sample

Solaris Sparc/x86: AccessManager-base/SUNWam

Linux: AccessManager-base/sun/identity

To Compile the ISAuthPostProcessSample Program on Solaris Sparc/x86 or Linux

Follow these steps given below to compile the sample found under AccessManager-base/samples/authentication/spi/postprocess .

Set the following environment variables.

JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

CLASSPATH: Set this variable to refer to am_services.jar which can be found in the AccessManager-base/lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)

BASE_DIR: Set this variable to the directory where the Access Manager is installed.

BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

In the directory AccessManager-base/samples/authentication/spi/postprocess, run the gmake command.

To Deploy the ISAuthPostProcess Sample Program

Copy ISAuthPostProcess.jar from JAR_DIR to AccessManager-base/lib.

Update the Web Container configuration file server.xml.

Add ISAuthPostProcessSample.jar to the classpath. The server.xml file for different web containers can be found at the following locations:

Web Server:<WS-home-dir>/https-<WS-instance-name>/config/

Application Server:<AS-home-dir>/domain/domain1/server1/config/

For all other web containers consult, the manufacturer’s documentation.

Restart the web container.

Configuring the Authentication Post Processing SPI

The Authentication PostProcessing Sample can be configured at the Organization,Service or Role level.

To Configure ISAuthPostProcess Sample for an Organization

Click Identity Management, and select your organization.

From the View menu, click Services.

In the navigation frame, under Authentication, click Core.

Add the following to the Authentication PostProcessing Class attribute:

com.iplanet.am.samples.authentication.spi.postprocess

Add the following to the Authentication PostProcessing Class attribute:

ISAuthPostProcessSample

Click Save.

Log out.

Go to the following URL http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login

The postprocessing SPI will be executed on successful authentication, on failed authentication, and on Logout.

To Configure the ISAuthPostProcess Sample for a Service

Click Identity Management, and select your organization.

From the View menu, select Services.

Select Authentication Configuration

From the Service Instance frame, select New Instance.

Enter a name for the service.

Add the following to the Authentication PostProcessing Class attribute: com.iplanet.am.samples.authentication.spi.postprocess.
ISAuthPostProcessSampl

Click Submit to save the changes.

Click Service Name and define the Authentication Configuration for the new service.

Log out.

Go to the following URL: http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/
Login?service=<servicename>

If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter.

The postprocessing SPI will get executed on successful authentication, failed authentication and on Logout for the service accessed.

To Configure ISAuthPostProcess Sample for a Role

Click the Identity Management tab, and select your organization.

From the View menu, select Roles to view the role properties.

From the View menu, select Services.

Click Edit to edit the authentication configuration.

Add the following to the Authentication post Processing Class attribute:

com.iplanet.am.samples.authentication.spi.postprocess.
ISAuthPostProcessSample

Click Submit to save the changes.

Log out.

Go to the following URL: http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login?role=roleName

If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter. Example: org=orgName

The postprocessing SPI will be executed for the service accessed on successful authentication, on failed authentication, and on Logout.

Compiling On Windows2000

Go to the base-directory\samples\authentication\spi\postprocess directory and run make.

To Deploy the ISAuthPostProcessSample Program

Copy ISAuthPostProcess.jar from JAR_DIR to base-directory\lib

In the Web Container from which this sample has to run, update the classpath with ISAuthPostProcess.jar.

Restart Access Manager.

base-directory\bin\amserver start

To Configure Authentication Post Processing SPI

This sample can be can be set in the Core Auth Service for Organization and Authentication Configuration Service for Role OR Service.

Generating an Authentication User ID

This file explains how to compile, deploy and configure the Authentication User ID Generation SPI Sample.

To Compile the UserIDGeneratorSample on Solaris Sparc/x86, Linux

To Deploy the UserIDGeneratorSample program

Configuring the UserIDGeneratorSample Program

Compiling the UserIDGeneratorSample Program on Windows 2000

In the following sections, the PRODUCT_DIR setting depends on which platform you’re using:

To Compile the UserIDGeneratorSample on Solaris Sparc/x86, Linux

Set the following environment variables.

These variables will be used to run the gmake command. You can also set these variables in the Makefile which is located in the following directory:

AccessManager-base/samples/authentication/spi/genuid

JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

CLASSPATH: Set this variable to refer to am_services.jar which can be found in the <PRODUCT_DIR>/lib directory. (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)

BASE_DIR: Set this variable to the directory where the Access Manager is installed.

BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

In the directory AccessManager-base/samples/authentication/spi/genuid, run the gmake command:

To Deploy the UserIDGeneratorSample program

Copy UserIDGeneratorSample.jar from JAR_DIR to AccessManager-base/lib.

in the Web Container from which this sample has to run, update the classpath with UserIDGeneratorSample.jar.

On Sun ONE Web Server, go to server instance's config directory: <WS-home-dir>/https-<WS-instance-name>/config/

On Sun ONE Application Server, in the directory <AS-home-dir>/domain/domain1/server1/config/ update server.xml with the new classpath.

For all other containers, consult the documentation that came with the product.

Restart web container.
<WS-home-dir>/https-<WS-instance-name>/start

<AS-home-dir>/domains/domain1/server1/bin/start

Configuring the UserIDGeneratorSample Program

The Authentication User ID Generation Sample can be configured at the Organization level, and then used or invoked by the out-of-box Membership/Self- registration authentication module.

To Configure UserIDGeneratorSample for an Organization

Click the Identity Management tab, and select your organization.

From the View menu, select Services.

In the navigation frame, under Authentication, click Core.

Add the following to the “Pluggable User Name Generator Class" attribute: com.iplanet.am.samples.authentication.spi.genuid.
UserIDGeneratorSample

Click Save to save the changes.

Log out.

To Access an Authentication Module for an Organization

This module is the one which invokes the UserIDGenerator SPI implementation class. By default, only the Membership/Self-registration authentication module calls this SPI implementation.

Make sure that you have registered and enabled the Membership authentication module, and that you have created a template for the organization.

Enter the following URL:

http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/
Login?module=Membership

If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter. Example: org=orgName

Click New User.

You should be able to register any existing username or user ID.

The UserIDGeneratorSample will be executed. You will be presented with the generated User IDs choice menu to choose any one username or user ID.

Compiling the UserIDGeneratorSample Program on Windows 2000

In the <install-root>\samples\authentication\spi\genuid directory, run the make command.

To deploy the UserIDGeneratorSample Program

Copy UserIDGeneratorSample.jar from JAR_DIR to <install-root>\lib

In the Web Container from which this sample has to run, update the classpath with UserIDGeneratorSample.jar.

Restart Access Manager.

<install-root>\bin\amserver start

To Configure the UserIDGeneratorSample Program

Implementing A Pure JAAS Module

A sample program demonstrates how to write pure a JAAS module to replay callbacks by authenticating using Access Manager Auth Remote API. It will authenticate a user by replaying the callbacks required by Access Manager the Authentication Module. You can modify this program to use other existing or customized Access Manager Authentication modules. This sample module can be plugged in into any standard JAAS framework using the JAAS API.

Conventions Used in the Samples


Variable	Description	Location
Config_directory	Directory that contains configuration files	/CONFIG_DIR = /etc/opt/SUNWam/config
Product_Directory	Directory where Access Manager is installed.	PRODUCT_DIR = <install_root>/SUNWam


Variable	Description	Location
Config_Directory	Directory that contains configuration files	CONFIG_DIR = /etc/opt/sun/identity/config
Product_Directory	Directory where Access Manager is installed.	PRODUCT_DIR = <install_root>/sun/identity

Table 6-7 Default directories for Windows 2000
Variable	Description	Location
Config_Directory	Directory that contains configuration files	CONFIG_DIR = <install_root>\lib
Product_Directory	Directory where Access Manager is installed.

To Run the Sample on Solaris Sparc x86 or Linux:

In the Makefile, set the following variables:

BASE: Enter the path to the directory where Access manager is installed.

JAVA_HOME: Enter the path to the directory where Java compiler is installed

CONFIG: Enter the entry specified in the login configuration file. This entry will be used to do the user authentication

Copy AMConfig.properties from Access Manager server installation machine location <CONFIG_DIR> to the client machine where the sample will be run.

On the client machine, be sure the following are in your classpath:

am_services.jar

jaas.jar

jss3.jar

AMConfig.properties

Include jaas.jar in your classpath if you are using a JDK version less than JDK1.4

A sample configuration file purejaassample.config is provided for testing this sample. It contains only one entry named Sample. Sample is the name to be entered for CONFIG in the Makefile.:

Sample {

PureJAASSampleLoginModule required ORG_NAME="dc=iplanet,dc=com" INDEX_NAME="LDAP" debug=true;

};

The entry specifies that the LoginModule to be used to do the user authentication is the PureJAASSampleLoginModule and that this SampleLoginModule must succeed in order for authentication to be considered successful. It passes options with ORG_NAME as the organization name and INDEX_NAME as the Access Manager authentication module to which this sample must authenticate.

If you must use a different login configuration, modify the Makefile. For example, change the following:

To compile, run the gmake command.

To run the sample program run the gmake run command.

To Enable SSL

In the sample client program, add this JVM property:

-D "java.protocol.handler.pkgs=com.iplanet.services.comm"

In the AMConfig.properties file, edit the following properties:

com.iplanet.am.admin.cli.certdb.dir: <PRODUCT_DIR>/servers/alias

com.iplanet.am.admin.cli.certdb.prefix: https-machine1.com-machine1-

com.iplanet.am.server.protocol: https

com.iplanet.am.server.port: Enter the appropriate port on the server machine where machine1 is the host name of the server

To Run the Sample on Windows 2000

In make.bat, set the following properties:

Copy AMConfig.properties from Access Manager server installation machine location <CONFIG_DIR> to the client machine where this sample will be run.

On the client machine, make sure the following are in your classpath:

am_services.jar

jaas.jar

jss3.jar

AMConfig.properties

Include jaas.jar in your classpath if you are using JDK version less than JDK1.4.

A sample configuration file purejaassample.config is provided for testing this sample. It contains only one entry named.Sample. Sample is the name to be entered for CONFIG in the Makefile.

Sample {

PureJAASSampleLoginModule required ORG_NAME="dc=iplanet,dc=com" INDEX_NAME="LDAP" debug=true;

};

The entry specifies that the LoginModule to be used to do the user authentication is the PureJAASSampleLoginModule. SampleLoginModule is must succeed in order for authentication to be considered successful. It passes options with ORG_NAME as the organization name and INDEX_NAME as the Access Manager authentication module to which this sample has to authenticate.

If you must use a different login configuration, modify the Makefile. For example, change the following:

-Djava.security.auth.login.config=purejaassample.config

to this:

-Djava.security.auth.login.config=<yourj_jaas_config_file.config>

To compile, run the make command.

To run the sample program, run the make run command.

To Enable SSL

In the sample client program, add this JVM property:

-D "java.protocol.handler.pkgs=com.iplanet.services.comm"

Edit the following properties in the AMConfig.properties file:

com.iplanet.am.admin.cli.certdb.dir:
<ISinstall-dir>\SUN\IdentityServer6\Servers\alias

com.iplanet.am.admin.cli.certdb.prefix:
https-machine1.red.iplanet.com-machine1-

com.iplanet.am.server.protocol: https

com.iplanet.am.server.port: Enter the appropriate port on the server machine where machine1 is the host name of the server

For the detailed information, see the Javadoc for Remote Client APIs. By default, Access Manager Javadoc is installed in the following directory:

For the detailed information on how to plug the Login Module into the standard JAAS Context, see the JAAS Reference Guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASRefGuide.html.

Previous Contents Index Next
Sun Java System Access Manager 6 2005Q1 Developer's Guide


Note	Although the client application need only write XML based on the remote-auth.dtd, when these messages are sent they include additional XML code produced by the Authentication API. This additional XML code is not illustrated in the following examples.


Note	This guide does not document the JAAS. For more information on these APIs, see the Java Authentication And Authorization Service Developer’s Guide. Additional information can be found at http://java.sun.com/products/jaas/.


Note	To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid.


Note	For detailed information on JAAS, see the Sun Developer Documentation at the following URL: http://java.sun.com/products/jaas/. For detailed information on how to write a JAAS module, see the JAAS LoginModule Developer’s Guide at the following URL: http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html