Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Server Deployment Guide

Chapter 3
Identity Server Architecture

Sun ONE Identity Server provides interfaces for managing identity objects, policies and services. This chapter describes these interfaces as they relate to the core architecture of the product and specific architectural details of its services. It contains the following sections:


Identity Server is built on the Java™ 2 Platform, Enterprise Edition (J2EE) platform and uses a web container as the infrastructure for operating the servlets, web service endpoints, and web applications which provide these services. Each of the provided services are implemented as web services which are built using a set of emerging standards and centrally provided on a network. In order to implement these services across the enterprise, Identity Server provides interfaces for managing identity-related objects, policies and services. The primary interfaces for this include policy agents that provide security for a wide variety of web and application servers, Java™ and C application programming interfaces (API), eXtensible Markup Language (XML) files, JavaServer Pages™, HyperText Markup Language (HTML) pages, a command line interface (CLI), and a graphical user interface (Identity Server console). With these interfaces it is possible to administer identity information in Sun ONE Directory Server, as well as extend SSO, authentication, policy-based authorization, and the logging functionality to applications across the enterprise. Figure 3-1 illustrates the functional architecture of Identity Server 6.1 and how the different components interact with each other.

Figure 3-1  Identity Server 6.1 Functional Architecture

Functional architecture of Identity Server detailing integration points.

Specific details on the individual architecture of these components can be found in the Sun ONE Identity Server Customization And API Guide. The following section, Integration Points, details how some of these components interact with each other.

Integration Points

Identity Server is a distributed system that relies on a variety of integration points to enable the delivery of its services. An integration point is a connector that allows an application to work smoothly with third-party systems or software. The primary integration points for Identity Server are policy agents and the software development kit (SDK).

Policy Agents

Access control in the Identity Server is enforced using policy agents that protect content on designated web , application, or proxy servers from unauthorized intrusions. Policy agents are provided under separate cover from Identity Server. The most current Sun ONE Identity Server Policy Agents can be downloaded from the Sun Microsystems Download Center. They are divided into two categories: those that protect resources on web and proxy servers and those that protect J2EE applications in a variety of deployment containers.

Web And Proxy Server Agents

Web and proxy server policy agents protect content deployed on said servers from unauthorized intrusions. The agents control access to a multitude of services and web resources based on policies configured by an administrator. When a user points a browser to a URL deployed on a protected web server, the agent intercepts the request and validates the user’s session token, if any exists. If the token’s authentication level is insufficient (or none exists), the appropriate Authentication Service is called for a login page, prompting the user for (further) authentication. The Authentication Service verifies that the user credentials are valid. (For example, the LDAP service verifies that the username and password are stored in Sun ONE Directory Server.) After the user’s credentials are properly authenticated, the policy agent examines all the roles (which contain the policies) assigned to the user. Based on the aggregate of all policies assigned to the user, the individual is either allowed or denied access to the URL.

J2EE Agents

Identity Server provides agents for protecting J2EE applications in a variety of deployment containers. These applications can include servers like IBM Lotus´┐Ż Domino™ and applications from companies such as PeopleSoft. The J2EE agents are generally comprised of two components (although this is partially subject to the interfaces exposed and supported by the deployment container): an Agent Filter and an Agent Realm that handle Authentication and Authorization, respectively.

Agent Filter

The Agent Filter is a servlet filter that intercepts an inbound request to the server. It checks the request to see if it contains a session token. If one is available, the Agent Filter validates the token using the Identity Server Session Service. If no token is available, the user is re-directed to the Authentication Service as in a typical SSO exchange. Once the user is authenticated, they are directed back to the server where the Agent Filter once again intercepts the request, and then validates the newly acquired token. After validation, the filter instantiates the principal and realm for the container, and the request is allowed to pass through the filter to the application. Through this mechanism, the Agent Filter ensures that only requests with a valid Identity Server token are allowed to access a protected application.

Agent Realm

The Agent Realm provides the Authorization component. A realm is a means for a J2EE-compliant application server to provide information about users, groups, and access control to applications deployed on it. It is a scope over which security policy is defined and enforced. The server is configured to use a specific realm for validation of users and their roles, when attempts are made to access resources. By default, many application servers ship with a number of realm implementations, including the default File Based as well as LDAP, NT, Unix, and Relational Database Management System (RDBMS). The Agent Realm implements the server’s Realm interface, and allows user and role information to be managed by the Identity Server deployment. The Agent Realm makes it possible to provide granular role-based Authorization of J2EE resources to users who have been authenticated by the Agent Filter.


For more detailed information, see the Sun ONE Identity Server Web Policy Agents Guide or the Sun ONE Identity Server J2EE Policy Agents Guide .

Identity Server SDK

Another means to integrate anapplication within Identity Server is programatically via the SDK. SDK access is provided primarily in Java, with C interfaces being provided for some funtionality. It is also possible to interface directly with Identity Server services via XML over HTTP(s), although the document format is subject to change in subsequent releases. Future versions of Identity Server will formally support web service interfaces with Web Service Defintion Language (WSDL) defined endpoints. The following SDKs are currently provided:


Identity Server provides interfaces for validating and managing session tokens, and for maintaining the user’s authentication credentials. All applications wishing to participate in the SSO solution can use this API. The package name is com.iplanet.sso.

Authentication API And Authentication SPI

Identity Server provides a JAAS implementation which allows programmatic authentication against Identity Server. This provides remote access to the full capabilities of the Authentication Service. Additionally, an Authentication SPI following the JAAS PAM specification allows creation of new authentication types.

Policy API

The Policy API can be used to evaluate and manage Identity Server policies as well as provide additional functionality for the Policy Service. A policy evaluator which directly loads and inteprets policy from the Policy Store is provided, as well as a remote policy evaluator, which acts as a client of Identity Server using the Java API for XML-based Remote Procedure Calls (JAX-RPC). The API also provides the ability to determine which resources an identity has access to.

Identity Managment SDK

Combined with Identity Server templates that describe the data modeling used in the underlying Directory Server, the Identity Management SDK provides the framework to create and manage users, roles, groups, containers, organizations, organizational units, and sub-organizations. It provides an interface at a much higher abstraction level then the LDAP client APIs, and simplifies the management of directory-based identity information. The core packages here are which operates directly against Directory Server, and which operates remotely against Identity Server via JAX-RPC which, in turn, acts against Directory Server on its behalf. (This is part of am_services.jar.) Finally, SPIs are provided to create plugins to the core SDK for tasks such as data validation, or password policy enforcement.

Logging API and Logging SPI

The Logging Service records, among other things, access approvals, access denials and user activity. The Logging API can be used to enable logging for external Java applications, providing a common logging facility to any integrated application. The Logging SPI can be used to develop plug-ins for customized features.

Service Management SDK

The service management interfaces can be used by developers to register service definitions that will be used to manage application configuration data. The API package name is

Client Detection API

Identity Server can detect the type of client browser that is attempting to access its resources and respond with the appropriately formatted pages. The API package used for this purpose is This package is part of am_services.jar.


Identity Server uses the SAML API to exchange acts of authentication, authorization decisions and attribute information. The API package names begin with com.sun.identity.saml. This package is part of am_services.jar.

Federation Management API

Identity Server uses the Federation Management API to add functionality based on the Liberty Alliance Project specifications. The API package name is com.sun.liberty. This package is part of am_services.jar.

Functional Processes

Identity Server contains a number of integrated functionalities. They include:

The integrated processes are discussed in the following sections. More specific details on many of the programmatic points can be found in the Sun ONE Identity Server Customization And API Guide.

Authentication and User Sessions

The Authentication Service is the entry point of Identity Server. A user must pass an authentication process before accessing the Identity Server console and its corresponding management functions. A user attempting to access a service or application protected by Identity Server must also authenticate before access is allowed. The Authentication Service invokes authentication modules to collect and validate the necessary credentials. Identity Server also provides APIs that allow applications to participate in a single sign-on functionality enabling a user to authenticate only once yet access multiple resources.

There are two ways to authenticate to the Identity Server: an administrator or end user attempts to access the Identity Server console itself for management purposes and is re-directed to the Authentication Service or, a user attempts to access an application protected by Identity Server and is re-directed to the Authentication Service. The former uses a HTML over HTTP(S) interface and the latter uses C-based or Java APIs.


A third option entails a user’s attempt to access any protected resource on a remote server machine. This option includes the installation of Identity Server policy agents and will be discussed in "Integrated Policy".

HTML Over HTTP(S) Interface

In a typical web-based scenario, an administrator or end user desiring to open Identity Server for management purposes would first access the authentication user interface Java servlet by typing the Authentication Service uniform resource indicator (URI) into the location window of a web browser.


A URI is a generic term that encompasses the more well-known URL.

The URI is pre-configured to an authentication process that defines one or more authentication modules. The servlet parses the URI, contacts the Session Service which creates a session token (in an invalid state) and embeds the token in a cookie. The Authentication SPI (com.sun.identity.authentication.spi) invoke the specific authentication modules and pass the login pages and the token/cookie to the requesting browser. The user enters their credentials and the Authentication SPI returns the information to the Authentication Service which validates it against information in the corresponding data store. Upon successful completion of all required authentication processes, the user’s policies (including URL access and deny lists), authentication level, and configuration parameters are passed to the Session Service which sets the token to a valid state. (Session information is not embedded in the token, but stored on the server. The token is only a pointer to the information.) Finally, the URL parameters are used to direct the user to the proper resource.


Additional information on the Authentication Service in general and URL parameters in particular can be found in the Sun ONE Identity Server Customization And API Guide.

XML Over HTTP(S) Interface

Both Java and C applications can request user authentication from Identity Server with the Authentication API. The Java package, com.sun.identity.authentication provides interfaces to initiate the authentication process, and communicate the unvalidated authentication credentials from the application back to the Authentication Service.


com.sun.identity.authentication can be implemented locally or remotely. Remotely, developers incorporate the classes and methods from this package into their Java applications.

Java calls are converted into an XML message and passed to Identity Server over HTTP(S). Once received, the XML message is converted back into Java to be interpreted by the Authentication Service. C application developers would follow the same process but first must contact Identity Server.


http://server_name.domain_name:port/service_deploy_uri/authservice is a servlet which speaks using the XML over HTTP protocol. The relevant DTD, remote-auth.dtd, can be found in the IdentityServer_base/SUNWam/dtd directory.

After opening a connection, the C application is developed to send its authentication requests to the Identity Server as XML messages over HTTP(S). Again, when received, the XML messages are converted back into Java and is parsed by the Authentication Service which determines the authentication method, contacts the Session Service which creates a session token in an invalid state and embeds the token in a cookie. The Authentication SPI (com.sun.identity. authentication.spi) invokes the specific authentication modules and pass the login pages and the token/cookie to the requesting application. The user enters their credentials and the Authentication SPI returns the information to the Identity Server which validates it against the information in the corresponding authentication date store. Upon successful completion of all required authentication processes, the user’s policies (including URL access and deny lists), authentication level, and configuration parameters are passed to the Session Service which embeds the information in the session token and sets it to a valid state. Finally, the requestor is granted access to the application.

Integrated Policy

Both authentication and single sign-on within an Identity Server deployment are interdependent; this means that there is not much a user can do after successful authentication if they do not also have a session token. The Policy Service has that same interdependence. Because a user’s policies define their privileges regarding protected resources within the deployment, there is not much a user can do without Identity Server first regarding their defined policies. This function is taken care of through the use of policy agents, installed in web servers on the remote machines that store the resources protected by Identity Server.


The most current policy agents can be downloaded from the Web And Directory Servers page of the Sun Microsystems Download Center at

When a user connects to a web server protected by a policy agent, the agent intercepts the request and checks for a session token embedded in a cookie. In the case where no token/cookie is found, the agent redirects the user to the login URL configured for this particular agent to begin the authentication process and create a session token. From this point, the process detailed in "Authentication and User Sessions" is followed. After the user has received a valid session token, they are directed back to the originally requested resource where the agent once again intercepts the request and checks for the session token. Finding one, the agent must now validate the new token so a request is made to the Naming Service to decrypt the token and pass along the specific Session Service to contact for validation. The agent receives the response, extracts the URL for the Session Service, and contacts it for token validation. The Session Service sends a response back to the agent, validating the token. The agent then requests of the Session Service to receive notification if, for any reason, the session times out or becomes invalid. The Session Service responds in the affirmative. In order to get the user’s defined policies, the agent can now contact the Policy Service which responds with a decision. The agent then uses this decision to allow or deny access to the requested resource. In addition, a log message is sent to the Logging Service.

Integrated Client Detection

The first step in authenticating a user is to identify the client type making the request. The Authentication Service uses the URL information to retrieve the browser type’s characteristics. Based on these characteristics, the correct authentication pages are sent back to the client browser; for example, HTML pages. Once the user is validated, the client type is added to the session token where it can be retrieved by other services. More information on client detection can be found in the Client Detection chapter of the Sun ONE Identity Server Customization And API Guide.

CDSSO, SAML and Federation

Cross-Domain Single Sign-on (CDSSO), Security Assertion Markup Language (SAML) Service, and Federation Mangement are separate features of Identity Server that provide the same functionality in different ways. CDSSO is Identity Server’s proprietary feature that allows single sign-on to occur across multiple DNS domains. The SAML Service can be used for the same purpose (cross domain single sign-on) in organizations that have implemented the SAML specifications in their existing deployments. Federation Management uses the Liberty Alliance Project’s version 1.1 specifications for federated identity management. They enable simplified sign-on through a linked network of partners, and user control over the use and disclosure of personal identification.


The Liberty specifications are built integrating the SAML specifications although, in this case, the use of SAML is not a part of the Identity Server SAML service itself.


CDSSO is a configurable part of the Identity Server authentication and authorization process. It includes the installation and configuration of policy agents which is discussed in "Authentication and User Sessions". More indepth information can be found in the Single Sign-On chapter of the Sun ONE Identity Server Customization And API Guide as well as the Sun ONE Identity Server Web Policy Agents Guide or the Sun ONE Identity Server J2EE Policy Agents Guide.


The SAML Service is based on an open-standard protocol that uses an XML framework to exchange security information between an authority and a trusted partner site. Information on its architecture within Identity Server can be found in the SAML Service chapter of the Sun ONE Identity Server Customization And API Guide.


Federation Management enables the configuration and management of authentication domains, hosted providers and remote providers using the Identity Server console. This enables users to sign on once but gain access to any other federated resources. Information on the federation architecture can be found in the Federation Management chapter of the Sun ONE Identity Server Customization And API Guide.

Extending Identity Server

Identity Server can be deployed with remote web or application servers, LDAP load-balancers such as Sun ONE Directory Proxy Server, and in multi-master replications. Before installation, consider how the following products might fit into a deployment. In some cases, they must be installed and configured before Identity Server.

Web Containers

Some web containers are remote relative to the Sun ONE Web Server (or other web container) on which Identity Server itself is deployed. Remote web containers may already be deployed to serve content pages for your organization; additional ones might be needed. They become integrated within the Identity Server environment when a policy agent is installed to protect the content. For detailed web container installation and administration information, see the documentation that comes with the server, or access the Sun ONE Web Server documentation.

Multiple Directory Server Instances

Multiple instances of Directory Server can be installed for upgrading, setting up failover directories, or deploying multi-masters. Directory Server must be installed, configured and deployed properly for the Identity Server deployment to be successful. Database replication agreements must be defined before installing Identity Server. For detailed Directory Server installation and deployment information, see the Sun ONE Directory Server Installation And Tuning Guide and the Sun ONE Directory Server Deployment Guide.

LDAP Load Balancers

Identity Server can be configured to work with load balancers such as Sun ONE Directory Proxy Server. Load balancing across replicated servers and locating replicated servers closer to users are two ways to improve Identity Server performance and response time. Using load balancers adds a layer of high availability and directory failover protection beyond the basic level that comes with Identity Server. They manage request traffic as well as reject client queries when all back-end LDAP servers are unavailable. For detailed installation and administration information, see the Sun ONE Directory Proxy Server 5.2 documentation. For information on other load balancers, see the documentation that comes with the product.

Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.