Chapter 11 Provisioning Organizations and Users

The information in this chapter provides conceptual and high-level task information on creating and managing Java Enterprise System organizations and users to use and access Sun ONE component products.

Understanding Directory Server

This section provides the basis for understanding the relationship of Directory Server to provisioning users for Java Enterprise System component products. This section also describes the idea of common user provisioning for all component products, and introduces the notion of a system-wide Java Enterprise System user account.

Overview of Directory Organizations and Users

Java Enterprise System component products, such as Portal Server, Messaging Server, and Calendar Server, use Directory Server to store user information as LDAP entries. The Java Enterprise System Directory Server is a hierarchical LDAP database. The hierarchy is commonly referred to as the Directory Information Tree (DIT). The fundamental building block in an LDAP directory server is termed an entry.

The DIT mirrors the tree model used by most file systems, with the tree’s root, or first entry, appearing at the top of the hierarchy. At installation, Directory Server creates a default directory tree.

The root of the tree is called the root suffix. At installation, the directory contains three subtrees under the root suffix:


Note	For Messaging Server and Calendar Server installations, you run the Directory Server Setup script, comm_dssetup.pl, to prepare the directory. This script configures the Users/Groups base suffix, selects schema type, configures the DC root, and performs other activities against the directory. See "To Configure Calendar Server After Installation" and "To Configure Messaging Server After Installation" for more information.

The following figure shows a sample DIT. In this figure, the o=userRoot suffix has been renamed to dc=example,dc=com, and additional subtrees have been added to reflect the organizational hierarchy.

The tree shown in the previous figure represents a basic shared Identity Server and Messaging Sun ONE LDAP Schema v.2 DIT. Sun ONE LDAP Schema v.2 provides easier integration with Identity Server and other third party LDAP-aware applications than Sun ONE LDAP Schema v.1. See Chapter 12, "Provisioning and Schema Concepts for Messaging Server 6.0" for more information on Sun ONE LDAP Schema v.2.

Information for the Java Enterprise System user accounts is stored in user entries, denoted in Figure 11-1 by uid=. User entries are organized by Domain components, denoted by dc=. Organizations are denoted by o=, and Organization Units by ou=.

Describing Java Enterprise System Users

An individual end user who can use any of the following applications: Identity Server, Portal Server, Messaging Server, Calendar Server, or Instant Messaging Server.

End user data that is stored in an LDAP database entry. In the simplest scenario, all component products read and write to the same user entries.

An end user who has access to component product applications only if proper values are set in that user’s entry.

A user account that is the LDAP user entry or entries that contain all the user data needed by the component product applications.

Common Organization Tree Structures

Java Enterprise System enables all component products to share a common set of LDAP user entries. Access to application functionality is controlled through the same entries. You can interact with a common user entry by using the Identity Server console and other provisioning and user management tools.

Java Enterprise System Benefits

Java Enterprise System permits creation of a single user account in LDAP that supports all component product applications. Such a user account greatly reduces the cost of the system by removing the need to maintain multiple user directories with redundant information and by removing the need to synchronize such directories. The result is simplified administration, which results in lower cost of ownership.

Overview of Provisioning Interfaces

The act of provisioning users is the adding, modifying or deleting of entries in Directory Server. The following provisioning interfaces exist for directory entries:

The Identity Server console and command-line utilities (for Sun ONE LDAP Schema v.2)

LDAP command-line utilities

Sun ONE Administration Server user interface to Directory Server

Directory Information Tree (DIT) Considerations

This section describes information you need in order to plan your DIT as part of your overall Java Enterprise System deployment.

Component Product DIT Considerations

To plan large Java Enterprise System deployments, you need to understand the LDAP requirements of each component product. This section provides background information to help you develop this understanding.

Java Enterprise System has evolved from the union of two general directory server aware technologies:

The communications component products, which include Sun ONE Calendar Server and Sun ONE Messaging Server

The Sun ONE Portal Server and Sun ONE Identity Server technologies, which include Sun ONE Portal Server, Secure Remote Access, and Sun ONE Instant Messaging

Each technology and component product has its own subtleties in terms of how it uses Directory Server. Use the following table as a starting point for understanding these subtleties and planning your deployment.

Table 11-1 DIT Planning Considerations
Consideration	Identity Server, Portal Server, Secure Remote Access, and Instant Messaging	Messaging Server and Calendar Server
Communication	Communicate through the Identity Server API layer, which abstracts the Directory Server.	Communicate directly to the Directory Server.
Identity Dependency	A runtime requirement. Identity is the foundation for all these component products.	Single sign-on only. Both products communicate with the Directory Server directly during runtime.
Inheritance	Heavily leverage Identity Server’s organization and role attribute value inheritance mechanism. Directory level Class of Service and roles are accessed invisibly through the Identity Server API.	None in the Identity Server sense. However, both products make explicit use of Directory Server Class of Service and roles.
Session Management	All products share the same Identity Server user sessions.	Both products maintain internal user sessions, which are synchronized with Identity Server SSO mechanisms.
Access Control	Handled through the Identity Server Policy layer, which abstracts the Directory Server access control rules.	Managed with explicit Directory Server access control rules.
Organization Concerns	Require Identity Server managed People container to function (ou=People).	Require the concept of a “mail domain” at specific organizations.
Directory Root	Are only aware of a single DIT root.	Are aware of multiple DIT roots.
DIT	Operate on a single DIT below one directory root.	Operate on multiple DITs below different directory roots. (Examples include Address Books, domains in Sun ONE LDAP Schema v.1, and so on.)
Sun ONE LDAP Schema v.1 versus Sun ONE LDAP Schema v.2	Identity Server uses Schema v.2 with a single DIT and can also support a Schema v.1-style DIT once Schema v.2 compatibility object classes and attributes are added. However, Schema v.2 was created with single DIT integration in mind.	Fully supports both schema models and the hybrid compatibility model. The schema mode affects how mail domains are configured in Directory Server, how the mail domains are resolved by Messaging Server and Calendar Server, and the number of DITs to be managed. The examples provided in this chapter are Schema v.2.
User Uniqueness	The user is searched for in the default organization, unless otherwise specified in the Identity Server Login page. In Identity Server, users are truly unique if they have a unique DN.	Uniqueness is always evaluated within a domain. In both Schema v.1 and Schema v.2, each domain is eventually resolved to a sub-tree in the directory. Within each domain’s sub-tree, a given unique ID must not appear in more than one user entry and a given email address within that domain must not appear in more than one user entry. Schema v.2 provisioning tools require that namespaces be explicitly marked to enforce uniqueness of the unique ID attribute.

Single Sign-on (SSO) and Users

To test SSO across component products, you must provision the test user for each application. Users can use SSO only if they can log in and use the applications.

A shared directory structure is not required to enable SSO between the Java Enterprise System servers. However, having a shared entry with shared attribute values facilitates SSO by reducing complexity. SSO will work between two Sun One applications that use two separate directory servers. Nevertheless, if shared attribute values (that is, user naming attribute cn=, uid=, and so forth) differ in the two databases, you must take extra care to avoid naming issues.

Managing Java Enterprise System Users

You create new users by adding a new user entry into the LDAP database and then configuring the user entry to work with each Sun ONE application.


Note	Even though user entries have been created, new users cannot use an application until their entries have been configured for that application. Each Sun ONE application has its own set of requirements, which are summarized in this section.

There are a variety of graphical and command-line tools for creating and configuring user entries for use with all applications. See "User Provisioning, Schema, and Tools Reference" for more information.

Managing Java Enterprise System users involves creating the organization tree structure in LDAP, adding users under this organization tree, and configuring the entries to work with the various Sun ONE applications.

Planning users and organizations

Determining what your user organization structure will look like

Determining which applications you want your users to access

Identifying each application’s data requirements

Installing users (creating the desired LDAP tree)

Configuring users (marking the organization entries so the applications can properly use your LDAP tree)

Administering users

Creating user entries

Marking the user entries so the applications can be properly accessed

Planning Users and Organizations

Reviewing key LDAP conventions, including:

LDAP database. The process and data store that holds organization and user information.

Tree structure. LDAP databases are hierarchies of organizations, domain components, resources, and users.

Entries. Data is stored in the entries.

Schema. Defines what types of values are allowed in LDAP entries.

Object classes. Special data type that defines an entry’s purpose and the valid attributes for that entry.

Attributes. Atomic data types.

User provisioning. The process of planning out the directory structure, then assigning object classes and attribute values to entries.

Referring to Sun ONE Directory Server 5.2 Getting Started Guide (http://docs.sun.com/doc/816-6696-10) for more information.

Reviewing how Sun ONE component products use LDAP

All component products have inherent dependencies on certain object classes and attribute values. Each product requires that certain object classes be added to the Organization (o=) and User (uid=) entries. The object classes serve two purposes:

“Marking” the entry as usable by the application

Allowing an entry to contain a new set of attributes

Users cannot access applications until:

Their parent organization entries have been propagated with the necessary values. (This is usually done once by the installer.)

In the case of hosted organizations and domains, every time you create a new organization in Identity Server, you need to assign the service to the domain and tag the domain with the service specific object classes and attributes. The installer takes care of this only for the default or initial organization.

Their own user entries have been propagated with the necessary values. (This is done with each user.)

The following table illustrates the effect of adding the correct object classes to a user entry. Consider two user entries that have different object classes. Only user2 has the correct entry values to use Identity Server, Messaging Server, and Portal Server.

Table 11-2 Example User Entries and Object Classes
User Entry	General Object Classes	Available Services
		Identity	Messaging	Calendar	Portal
user1	Base directory server object classes
user2	Base directory server object classes and Identity Server, Messaging Server, and Portal Server object classes	X	X		X

The respective component product documentation describes what each product requires from LDAP. Table 11-4 provides a list of these requirements.

Deciding on organizations

During the installation and post-installation configuration of Java Enterprise System, you must supply a root suffix, LDAP root, or usergroup organization. To enable all component products to operate on the same user entries, you must ensure all products share the same directory tree.

Most products are flexible when it comes to defining organization names and the depth of the directory tree.

Determining the component products to be installed

When selecting the products that you want to install, note your chosen shared tree structure. Depending on the component product, you supply LDAP values in either the Java Enterprise System installer or in the component product post-installation “configure” script.



Note	You need to coordinate installer values. Java Enterprise System’s post-configuration tools give users the flexibility to specify their own DIT structures, independent of other component products. If you want to install all products so they share common user entries, you must coordinate the DIT-specific values supplied during the various component configuration steps.

The following table shows example installer LDAP values. Notice the example input values, and that the root suffix is the same for all component products. For this table, default domain replaces the Default Organization value.

Table 11-3 Example Installer Input Values
Component Product	Configuration Method	Input Field	Default	Example Input Value
Identity Server	Java Enterprise System installer	Base DN	Default DNS domain	dc=example,dc=com
Portal Server	Java Enterprise System installer	(Inherited from Identity Server)	Identity Server Base DN	dc=example,dc=com
Instant Messaging	Component product’s script	(Implicitly the same as Identity Server)	(Implicitly the same as Identity Server)	(Implicitly the same as Identity Server)
Messaging Server	Component product’s script	Base DN	Root	dc=example,dc=com
Messaging Server	Component product’s script	Usergroup organization	Default Mail Org	o=default domain,dc=example, dc=com
Calendar Server	Component product’s script	Usergroup organization	Default Org	o=default domain,dc=example, dc=com



Note	The configure utility provides you with a two-level organization tree, o=Default Organization,dc=example,dc=com. Neither Messaging Server nor Calendar Server require this kind of organizational tree. You need these two levels in case you are planning additional mail or calendar domains from the same deployment. When you define a domain at the root node, you are prevented from creating additional domains beneath the root, because this would result in nested namespaces that are not allowed in Sun ONE LDAP Schema v.2. You can define any LDAP structure you want after the initial configuration step.

Installing and Configuring Component Products

You supply the DIT-specific values mentioned in the previous section during the installation and post-configuration steps. There are potentially six places where you supply values:

Running the Java Enterprise System installer

Running the comm_dssetup.pl script, located in the /opt/SUNWmsgsr/lib directory

Running the Messaging Server configure script, located in the ms_svr_base/sbin/ directory

Running the Calendar Server csconfigurator.sh utility, located in the cs_svr_base/SUNWics5/cal/sbin directory

Running the Instant Messaging configurator, located in the ims_svr_base/SUNWiim/opt directory

Within Administration Server, for Messaging. (Configurator requirement)

Refer to this guide for more information on installing and configuring component products.

Provisioning Users

Provisioning users involves populating database entries with the necessary values so that applications can operate on users and organizations. If an entry is missing a required object class or attribute value, the application is unavailable to that user.

Preparing the database structure for use by all applications

Ensuring user entries have all the data needed to use each application, which in LDAP database operations means:

Marking your organization entries (and creating more organization entries if desired)

Marking your user entries (either by creating new user entries or modifying existing ones)

Reviewing Data Requirements

The following table shows the object class and attribute requirements for each component product. For each application, you must add all the checked object classes to the user’s entry before that user can use that application.

Table 11-4 Object Class and Attribute Requirements for Component Products
Entry Type	Object Class	Messaging Server	Calendar Server	Identity Server
Organization dc=,o=	Domain	X	X
	InetDomain	X	X	X
	Organization	X	X
	SunManagedOrganization	X	X	X
	SunNameSpace	X	X	X
	MailDomain	X
	IcsCalendarDomain		X
Organizational Unit ou=	Iplanet-am-managed-org-unit			X
People ou=people	Iplanet-am-managed-people-container			X
User cn=,uid=, and so forth	person	X	X
	InetUser	X	X	X
	OrganizationalPerson	X	X
	InetOrgPerson	X	X	X
	IpUser	X	X
	UserPresenceProfile	X
	InetMailUser	X
	InetLocalMailRecipient	X
	IcsCalendarUser		X
	Inetadmin			X
	Iplanet-am-managed-person			X
	Iplanet-am-user-service			X
	iplanetPreferences			X

In addition to the previous object classes, most applications require that additional attributes are set to “activate” the user.


Note	Portal Server and Instant Messaging are built on Identity Server and implicitly require all Identity Server attributes. While Portal Server saves user data in the same LDAP entry, the preferred way of provisioning Portal Server users is with the Identity Server console or amadmin command, and the Portal Server dpadmin command. Because Portal Server leverages the Identity Server organization and role inheritance mechanisms, little or no per-user configuration is required. Once you create Identity Server users by using LDAP or the Identity Server, the user entries inherit most attribute values from their role or organization.

Some of these object classes are defined by the component products. Others are Internet standards shipped with Directory Server itself. For example, InetOrgPerson is the user entry base object class, which defines attributes such as uid, mail, and givenName.

All products do not require core or shared classes. For a minimal set of per-product object classes and their use, refer to the following component product documentation:

Sun ONE Messaging and Collaboration 6.0 Schema Reference Manual (http://docs.sun.com/doc/816-6710-10).

Sun ONE Identity Server 6.1 Installation and Configuration Guide, Chapter 5 “Installing Identity Server Against an Existing Directory Server” (http://docs.sun.com/doc/816-6771-10)

Sun ONE Portal Server 6.2 Administrator’s Guide (http://docs.sun.com/doc/816-6748-10)

Getting Started—Choosing an LDAP Administration Option

The object classes in Table 11-4 need to be added to the proper entries in the LDAP database. When you configure all products to install against the same directory structure, most of the needed values will be added to the organization entries. However, depending on your install sequence, all values might not be present to support all users. Always verify that your organization tree was provisioned properly before you begin provisioning users.

The following table summarizes the four choices for viewing, creating and modifying LDAP entries. See "Provisioning Users by Using the LDAP Modify Command" for an example of how to modify users by using the ldapmodify command.

Table 11-5 Choices for Viewing, Creating, and Modifying LDAP Entries
Level of Complexity	Tools and Method	Minimal Number of Toolsets 1	Where to Go in the Sun ONE Documentation
Basic	Identity Server console; or amadmin and commadmin	2	Sun ONE Identity Server 6.1 Administration Guide (http://docs/sun.com/doc/816-6773-10) and Sun ONE Messaging and Collaboration 1.0 User Management Utility Installation and Reference Guide (http://docs.sun.com/doc/817-4216-10)
Moderate	Sun ONE Administration Server (a graphical tool to directly manipulate the LDAP database entries)	1	Sun ONE Directory Server 5.2 Getting Started Guide, Chapter 3 “A Quick Look at Directory Server Console,” Managing Entries (http://docs.sun.com/doc/816-6696-10)
Advanced	ldapmodify ldif_input_file	1	Sun ONE Directory Server 5.2 Getting Started Guide, Chapter 4 “A Quick Look at Directory Server Command-Line Utilities,” Adding, Changing and Deleting Entries (http://docs.sun.com/doc/816-6696-10)
Expert	Identity Server with custom services	1	Sun ONE Identity Server 6.1 Administration Guide (http://docs.sun.com/doc/816-6773-10) and Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10), Chapter 6 “Service Management,” Service Definition See "Java Enterprise System User Provisioning Example Using Identity Server Services" for more information.

1Component product tool sets modify only user entries for their own purposes. To manage Java Enterprise System user entries in this fashion, you need to run tools from multiple products.


Note	Identity Server does not recommend ldif operations on anything but user entries.

User Provisioning, Schema, and Tools Reference

This section is a reference for the provisioning and schema documentation and tools available for Calendar Server, Identity Server, Messaging Server, and Portal Server.

Component Product Documentation

Table 11-6 describes the type of information and location in the Java Enterprise System and Sun ONE component product documentation that you will need to provision users and understand schema issues.

Table 11-6 Component Product Provisioning and Schema Documentation
Book Title	Chapter and Section	Contents
Sun ONE Identity Server 6.1 Migration Guide (http://docs.sun.com/doc/816-6771-10)	Chapter 3, “Configuring Identity Server with a Provisioned Directory”	This chapter provides instructions for installing Identity Server against an existing directory that contains user data. It also explains how to configure Identity Server to work with your directory information tree (DIT), and how to make the necessary changes to your existing Directory Server and directory entries.
Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10)	Chapter 6, “Service Management”	This chapter provides information on how to define a service, the structure of the XML files and the service management application programming interfaces (API).
Sun ONE Messaging and Collaboration 1.0 User Management Utility Installation and Reference Guide (http://docs.sun.com/doc/817-4216-10)	“Chapter 3, “Command-Line Utilities	This guide explains how to install and configure User Management Utility for Sun ONE Messaging and Collaboration. This guide also describes the User Management Utility commands (commadmin), providing syntax and examples. User Management Utility is a set of command-line tools for provisioning users, groups, domains, and resources for Messaging Server and Calendar Server using Identity Server 6.1.
Sun ONE Messaging and Collaboration 6.0 Schema Reference Manual (http://docs.sun.com/doc/816-6710-10)	Chapter 1, “Overview” - Data Model for Sun ONE LDAP Schema, v.2	Read this guide if you want to provision Sun ONE Messaging Server, or Sun ONE Calendar Server, using LDAP. The audience for this manual consists of: System architects who want to develop customized provisioning tools that interface between Messaging and Collaboration product entries in the LDAP directory and their existing source of users, groups, and domains information such as a company database or billing system. Site Administrators who want to know how to create domain, user, group, or resource entries using LDAP.
Sun ONE Calendar Server 6.0 Administrator’s Guide (http://docs.sun.com/doc/816-6708-10)	Chapter 2, “Managing Calendar Server Users and Calendars” - Provisioning New Calendar Server Users	This section provides the following information about provisioning new Calendar Server users: Directory Server Requirements Calendar Identifiers (calids) Checking if a User is Enabled for Calendaring Provisioning a New User Creating a New Calendar
Sun ONE Calendar Server 6.0 Release Notes (http://docs/sun.com/doc/816-6715-10)	“New LDAP Schema Version”	This document points out the existence of support for Schema v.2, and refers to Messaging Server 6.0 Schema Reference Manual.
Sun ONE Messaging Server 6.0 Release Notes (http://docs.sun.com/doc/816-6736-10)	Entire Release Notes	This document describes late-breaking developments to the commadmin utility.

Component Product Provisioning Tools

The following table describes the provisioning tools for Sun ONE component products.

Table 11-7 Component Product Provisioning Tools
Component Product	Tools	Description
Calendar Server and Messaging Server	commadmin	Enables you to manage different communication services for users, groups, domains, and organizations. You can also use ldapmodify, and Identity Server services for minimal provisioning.
Directory Server	ldapmodify	The ldapmodify command enables you to add, edit, and delete your directory contents. Use ldapmodify to manage both the configuration entries of the server and the data in the user entries. You can use ldapmodify to write scripts to perform bulk management of one or more directories.
Directory Server	Sun ONE Server Console	Sun ONE Server Console enables you to graphically manage Sun ONE software in your enterprise.
Identity Server	amadmin	The amadmin command enables you to update the DIT by loading XML service files into the Directory Server. The amadmin command also enables you to perform batch administrative tasks on the DIT.
Identity Server	Identity Server Console	The Identity Server Console graphically displays the XML that is used to update the DIT. Note: You can also use the ldapmodify command in place of the amadmin command.
Portal Server	dpadmin	Enables display profile objects to be retrieved, added, modified, and removed from a display profile document. All interactions with display profile objects must be in their native XML format. You must always use the dpadmin command in conjunction with Identity Server tools.