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

• LDAPLogin Example

• CertLogin Example

• JCDI Module Example

• C-API Sample

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.

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 2–2 summarizes file locations and variable names used for Solaris Sparc/x86.l Table 2–3 summarizes default directories for Linux. Table 2–4 summarizes default directories for Windows 2000.

<install_root>/SUNWam/
	samples/authenitcation/api

<install_root>/sun/
	identity/samples/authentication/api

<install_root>\samples\
	authentication\api

These steps are for all platforms.

To Compile and Execute the Java API Samples

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

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

3. 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).

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

5. In the client machine, create a directory named locale.

   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.

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

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

8. Compile the program.

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

     • On Windows 2000, run the make command.

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

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

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

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

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

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

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

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

   For the details, see the Javadoc for the Remote Client API.

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:

AccessManager-base/ SUNWam/samples/authentication/LDAP

To compile and run the sample program, follow the steps in To Compile and Execute the Java API Samples.

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:

AccessManager-base/ SUNWam/samples/authentication/Cert

To Run the CertLogin Program

1. Enable SSL.

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

2. Compile and execute the sample code.

   See 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 remote client component is located in the following directory:

AccessManager-base/samples/authentication/api/jcdi

The server JCDI authentication module is located in the following directory:

AccessManager-basesamples/authentication/spi/jcdi

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:

AccessManager-basesamples/authentication/api/jcdi

To compile and run the sample program, follow the steps in Running the Sample Authentication Programs.