Chapter 1   DSAME Programmer's Overview


The Directory Server Access Management Edition Programmer's Guide describes how service developers and programmers can customize the following public interfaces in DSAME 5.0:

• the Java client Application Programming Interfaces (APIs) that enable service developers to customize the Single Sign-On solution;

• the Java Pluggable Authentication Service Provider Interfaces (SPIs) which allow service developers to create a custom pluggable authentication service;

• the client Authentication Service interfaces which allow service developers to customize the authentication login, logout, and timeout screens by modifying the HTML templates;

• the command line interface (amadmin tool) which enables service developers and customization engineers to import custom service XML files, and batch update XML files to perform operations such as creates, deletes, and gets on various directory objects in the DIT (such as users, groups, roles, people containers, etc.).

This chapter contains the following sections:

• Extending iPlanet Directory Server Access Management Edition

• Which APIs, SPIs, and XML over HTTP Interfaces you can customize

• Overview of Service Development Process when extending DSAME Interfaces

The Programmer's Guide provides information for programmers customizing iPlanet Directory Server Access Management Edition (DSAME) software. It documents the public Java application programming interfaces (APIs) and service provider interfaces (SPIs) that are included in the iPlanet Directory Server Access Management Edition product, as well as documents the exposed HTTP over XML interfaces. For example, you can use the Single Sign-On APIs and the Authentication SPIs to integrate the application with the iPlanet Directory Server Access Management Edition software and use single sign-on capabilities.

The Pluggable Authentication SPIs and Single Sign-On SPIs are for authenticating users and issuing a single-sign-on (SSO) token. The SSO APIs provides Java interfaces that validate the SSO tokens and maintain authentication credentials for the user. The SSO APIs can be used to provide a mechanism by which users need to authenticate only once, and then can access multiple we-based applications without having to re-authenticate. Additionally, it provides interfaces for applications to store generic key-value pairs and to register callback listeners, which will be invoked when the SSO token is destroyed.

DSAME's single-sign-on solution is primarily intended for web-based applications; however, service developers can use the Single Sign-On APIs to write Java-based services.

The Single Sign-On APIs provide methods to:

• get the SSO token from its string representation (token ID)

• validate or invalidate the SSO token

• get the principal name of the authenticated user

• get the token ID

• get the authentication type

• get the authentication level

• get the hostname of the client that sent the SSO token

• method to get the value of a property stored in the SSO token

• add a listener that will be called when the token is destroyed, or has reached its maximum idle timeout, or has reached its maximum session timeout.

• get the SSO token in a string format

• check if two SSO tokens are equal.

• get the SSO token from its string representation that is provided by the token ID.

• notify applications when the SSO token expires.

• get the time when the token expired.

• get the cause for the token to expire.

The third major interface that can be customized by programmers is the HTML templates. Service developers or programmers can modify the HTML templates to create custom authentication login, logout, and timeout pages for different organizations in DSAME console.

The fourth customizable interface in DSAME 5.0 is the XML interface. Service developers can use the amadmin CLI tool to import custom service XML files such as when creating a custom pluggable authentication service. Also, they can use the amadmin tool to import batch update XML files that update objects in the DIT (such as creating, reading, and deleting roles, users, organizations, groups, people containers, and services). Developers writing programs that will communicate with the exposed XML over HTTP interface to iPlanet Directory Server Access Management Edition need to understand and be able to use eXtensible Markup Language (XML) and HTTP.

---

Note	Detailed information on the public APIs and SPIs in DSAME 5.0 (Single Sign-On and Authentication) is available in the Javadocs. (The Javadocs are located in <dsame_root>/web-apps/services/docs/en_USjavadocs.

---

Extending iPlanet Directory Server Access Management Edition

---

DSAME can be extended in several ways, which is described in this section. If additional authentication capabilities are needed, use the public Java Pluggable Authentication SPIs to create them. To add Java-based services that can make use of the single sign-on solution, use the Single Sign-On APIs and the Authentication SPIs to integrate them into the iPlanet Directory Server Access Management Edition framework. (Note that the Single Sign-On solution is primarily a web-based solution, but can be extended using the Java APIs.)

DSAME can be extended by adding new or custom services or applications, such as authentication plugin modules or custom single sign-on solutions. Typically, for most services, DSAME and Directory Server must be updated with any new objectclasses and attributes that an application or service will use, in order for DSAME to manage those service attributes. (For general information on the necessity of updating the schema in Directory server when adding a service, see Chapter 5 "Understanding DSAME XMLs and DTDs." For information on updating schema when adding a custom authentication module, or a single sign-on solution, see Chapter 2 "Pluggable Authentication SPI" and Chapter 6 "Using the Command Line Interface," respectively.)

Which APIs, SPIs, and XML Interfaces You Can Customize

This section gives brief descriptions of which interfaces are customizable by programmers in the DSAME 5.0 release:

• Authentication SPI — Java interfaces for creating custom pluggable authentication services. You can use the exposed Java Service Provider Interfaces (SPIs) and classes to create a server-side plug-in authentication module.

• Single Sign-On Client APIs — Single Sign-On component provides Java interfaces so that applications can participate in the SSO solution. These APIs are intended primarily for web-based applications, but they can be extended to any Java-based applications.

• amadmin CLI tool — The amadmin CLI tool is considered a declarative interface. The two primary purposes of the amadmin command line interface tool are to import service schema and configuration data into DSAME, and to perform batch updates to the Directory Server (such as creating, getting, and deleting roles, users, organizations, groups, people containers, and services).

The iPlanet Directory Server Access Management Edition APIs, SPIs, and XML over HTTP interfaces that are customizable in the DSAME 5.0 release fall into several broad categories:

To do:	Use these APIs/SPIs/XML over HTTP Interfaces
Single Sign-On	Single Sign-On APIs are programmatically customizable. Customers can use the seven public single sign-on APIs to create custom services.
Authentication Extension	Three Authentication service provider interfaces (SPIs) are public in this release so customers can write their own supplemental authentication module (SPI—service provider interface) to plug into iPlanet Directory Server Access Management Edition.
Service XML and Bulk Updates XML Files	Service developers and/or customization engineers can extend the service XMLs to create their own custom services or applications to integrate into DSAME. Additionally, they can use the bulk operations XMLs to create, get, and delete user objects in the DIT (Directory Information Tree) such as roles, users, organizations, groups, people containers, and services.

Overview of Service Development Process When Extending DSAME Interfaces

---

This section describes the development process (at a high level) when extending the public DSAME APIs, SPIs, and/or XML interfaces to create a custom service to integrate into the iPlanet Directory Server Access Management Edition product.

The following main steps outline the process:

1. Define high-level application requirements.

2. Determine which iPlanet Directory Server Access Management Edition APIs, SPIs, or service XMLs (Authentication, etc.) support the high-level requirements.

3. Define the iPlanet Directory Server Access Management Edition attributes.

4. Define the privileges that determine the policy for the service. Create an XML file to define the service attributes as they will display, and thus be manageable from, the DSAME console.

5. Import the XML file to the DSAME server with the amadmin CLI tool.

6. Configure and modify the services through the DSAME console.

For more detailed information on creating services to integrate into DSAME, see the section "High Level Flow for Creating and Registering Services" of this guide.

Each XML DTD specifies the content and format of the information that can be sent to and received from the iPlanet Directory Server Access Management Edition services. (See Chapter 5 "Understanding DSAME XMLs and DTDs" and Chapter 6 "Using the Command Line Interface" for information on the service XML and batch update XML files used in DSAME, and how to use the command line interface to import the service XMLs and the batch updates XML files into DSAME.)