Chapter 1   Introduction


The iPlanet Directory Server Access Management Edition (DSAME) Programmer's Guide describes how service developers and programmers can customize the DSAME application to fit the specific needs of their organization. It offers information on the public Java APIs, XML-based service configuration files and HTML-based graphical interfaces. This introductory chapter contains the following sections:

• DSAME Overview

• Web Access

• Extending DSAME

• DSAME File System

DSAME Overview

---

iPlanet DSAME is designed to help organizations manage secure access to their web-based resources. The product integrates an identity system with the management and enforcement of authentication and access privileges. It contains a number of features towards this end. They include:

• Authentication—provides Java APIs for writing custom authentication server plug-ins, an HTML-defined client interface for gathering the user's credentials and a framework that connects the client interface with the plug-in module.

• Single Sign-on (SSO)—provides Java APIs to create and manage SSO tokens and a service to manage SSO sessions.

• Service Management—provides a solution for customizing and registering services and managing their attributes (configuration parameters). It includes an eXtensible Markup Language (XML) Document Type Definition (DTD) that defines the rules for creating a service and its attributes as well as Java APIs to manage the same.

• Identity Management—provides a solution for managing the structure of DSAME's directory data store. This includes Java APIs for adding, modifying and removing identity-related objects and their attributes as well as templates that define the configuration parameters of same.

• Policy Management—provides a solution for defining and retrieving organization-based privileges that secure the web resources of an enterprise.

• DSAME console—provides a graphical, JATO-based interface for identity, service, and policy management.

• Command-line interface—provides an amadmin executable to perform service schema and metadata integration as well as identity, policy and service management.

These listed features are executed by DSAME services that are installed out of the box. They would internal services as distinguished from customized or external services that are added on after installation. The basic functionality of internal services can be extended. Customized external components can be defined using the APIs, the sample code packaged with DSAME and the information in this guide.

How DSAME Works

---

DSAME can be used to manage access to resources in two ways. An administrator can access DSAME via a web browser or, an application can access DSAME directly, requesting user profile information.

Web Access

When a user requests access to an application or a protected page via a web browser, they must first be authenticated. The request is redirected to the Authentication service. This module determines the type of authentication to initiate based on the method chosen by the user's organization. For instance, LDAP is a simple user name and password-based authentication. The authentication module would send a HTML form to the web browser. For more complex types of authentication, it might send multiple forms for authentication information.

Having obtained the user's credentials, the Authentication module would call the respective provider to perform the authentication. Once verified, the module generates a Single Sign-On (SSO) token (using the SSO API) which holds the user's identity. The SSO API then generates a SSO token ID, a random string associated with the SSO token. This ID is then sent back to the browser in the form of a cookie. Once authenticated, the authentication component re-directs the user back to the requested application or page.

---

Note	Web access through DSAME includes an additional security measure which uses web agents to evaluate a user's access privileges. For more information, see the iPlanet Policy Agent Pack 1.0 documentation.

---

Java Application Access

Java applications can access DSAME for user attributes. (For example, a mail service might store its users' mailbox size information in iPlanet Directory Server and retrieve the information using DSAME.) To achieve this, the system that runs the Java application must have the DSAME SDK installed. As well, there must be at least one instance of iPlanet Web Server running the DSAME internal services (specifically for the user authentication and SSO components).

Extending DSAME

---

DSAME can be extended in several ways. If additional authentication capabilities are needed, the Authentication APIs can be used to create them. To add Java-based applications, the SSO and Log APIs can be used to integrate them into the framework. The architectural goal of DSAME is to provide this extensible interface. This interface can be defined in one of three ways:

1. DSAME services are defined using XML.

2. DSAME screen templates are written using HTML.

3. DSAME services are implemented using Java.

Service Definition With XML

A DSAME service is a grouping of attributes defined under a common name. The attributes (or configuration parameters) can be a random set grouped together for easy management or a related set grouped together for a specific purpose. DSAME ships with a number of internal services of the latter type. These include, but are not limited to, logging, administration, and session services. More information on the internal services can be found in the iPlanet Directory Server Access Management Edition Administration Guide.

All DSAME services are written using the XML. The XML configuration file of a service must adhere to the form put forth in the sms.dtd, which is located in the Install_Directory/SUNWam/dtd/ directory. Using the XML, organizations can modify the XML configuration files of internal DSAME services or configure the XML configuration files of external ones.

---

Note	DSAME services manage attribute values stored in iPlanet Directory Server. They do not implement the behavior of the attributes or dynamically generate code to interpret them. It is up to an external application to interpret or utilize these values.

---

HTML Templates

DSAME uses HTML template files to control the look of the screens that a DSAME user sees. These templates can be modified to make changes to the design; for instance, an organization's logo can be added in place of the iPlanet logo. The entire template can also be replaced with an organization's custom HTML page.

The Java APIs

There are five public API packages provided with DSAME version 5.1. These APIs provide interfaces to implement the behavior of extended or customized DSAME services. The packages are introduced below.

Authentication API

DSAME allows the use of multiple and disparate authentication modules including, but not limited to, RADIUS, LDAP, Certificates, Unix, Membership (self-registration), SafeWord and Anonymous. Using the Authentication API, a service developer can write a custom authentication module. The API package name is com.iplanet.authentication.spi.

DSAME SDK

DSAME provides the framework to create and manage users, roles, groups, people containers, organizations, organization units, and sub-organizations. It also includes the functionality to create and modify service templates. This API is the core of the identity, service and policy management modules and provides Java classes that can be used to customize them. The API package name is com.iplanet.am.sdk.

Utilities API

This API provides a number of Java classes that can be used to manage system resources. This includes, among others, thread management and debug data formatting. The API package name is com.iplanet.am.util.

Logging API

The DSAME logging service records, among other things, access approvals, access denials and user activity. The Logging API can be used to enable other Java applications to call the DSAME logging service. The API package name is com.iplanet.log.

Single Sign-On API

DSAME provides Java interfaces for validating and managing the single sign-on (SSO) tokens and for maintaining the user's authentication credentials. All applications wishing to participate in the SSO solution can use this API. The API package name is com.iplanet.sso.

---

Note	The Overview page for the complete set of public DSAME Javadocs can be accessed at Install_Directory/SUNWam/docs/index.html.

---

DSAME File System

---

DSAME installs its packages and files in a directory named SUNWam. The file system layout for a Solaris installation is as follows:

Install_Directory/SUNWam/

• bin/ ---> contains executables such as amserver & amadmin.

• docs/ ---> contains DSAME documentation.

• java/ ---> contains the Java Development Kit.

• locale/ ---> contains the internationalization resource files.

• servers/ ---> contains the iPlanet Web Server.

• config/ ---> contains configuration files such as the iPlanet Directory Server name and port as well as XML files which define DSAME services.

• dtd/ ---> contains the XML DTDs used by DSAME applications and services.

• lib/ ---> contains DSAME jar files as well as platform specific C libraries.

•       migration/ ---> contains tools for iPlanet Directory Server data migration from earlier versions to version 5.1.

• samples/ ---> contains sample java programs on how to use the DSAME Java APIs.

• web-apps/ ---> contains two WAR-based deployments and their associated files: Services (authentication, policy management, identity management, SSO, SMS management, etc.) and Applications (DSAME console).

Runtime Directory

On Solaris, DSAME uses Install_Directory/SUNWam as its runtime directory for logs and debug files. On Windows 2000, DSAME uses DSAME_root as its runtime directory. Both directories can be configured.

DSAME performs three types of administration:

• Identity management deals with managing the structure of a customer's directory. This includes creating, deleting, and modifying roles, organizations.

• Policy management deals with the creation of policies and how they are applied within the application.

• Service management deals with service registration, unregistration, and activation.