| Sun Java Enterprise System 2003Q4 Installation Guide |
Appendix G
User Provisioning with Identity ServerThe information in this appendix provides conceptual and high-level task information on provisioning Messaging Server and Calendar Server users by using Identity Server.
This appendix contains the following sections:
Note
This appendix provides minimal Messaging Server and Calendar Server LDAP user entry provisioning using Identity Server Services. Because the interface provides no input validation, user entries that cannot receive email or otherwise don’t function will be created without reporting any errors. As a result, use this interface for demonstration purposes only.
The commadmin interface, which is described in the Sun ONE Messaging and Collaboration 1.0 User Management Utility Installation and Reference Guide (http://docs.sun.com/doc/817-4216-10), is the recommended mechanism for provisioning Messaging Server and Calendar Server users.
Overview of Provisioning Users with Identity ServerIn previous releases, you provisioned Messaging Server and Calendar Server users by using ldapmodify operations or iPlanet Delegated Administrator. In Identity Server 6.1, Messaging Server and Calendar Server user provisioning tasks are being gradually migrated to this shared facility. Java Enterprise System ships the User Management Utility provisioning tool (for Sun ONE LDAP Schema, v.2) called commadmin.
Identity Server 6.1 provides enough functionality to address minimal mail and calendar provisioning needs. Identity Server accomplishes provisioning through its extensible LDAP data management mechanism called Identity Server services. By defining an Identity Server service, you automate arbitrary LDAP object class and attribute operations and incorporate them into the Identity Server framework. The service requirements are:
The Sun ONE Messaging and Collaboration 6.0 Schema Reference Manual (http://docs.sun.com/doc/816-6710-10) documents the required object classes and attribute values for Messaging Server and Calendar Server. You can use this guide, along with the Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10), to automate basic user provisioning needs by defining your own mail and calendar services in Identity Server.
Identity Server ships with a sample XML service definition that demonstrates how to minimally provision mail and calendar users through the Identity Server console. See "Defining and Extending an Identity Server Service for Provisioning Messaging" for more information.
You can provision users for all component products by assigning the corresponding component product service to that user. You can provision individual users by using the Identity Server console, and batches of users by using the amadmin or ldapmodify commands.
About the Identity Server Console
In simplest terms, Identity Server services provide an HTML representation of an LDAP entry. This HTML representation appears as an HTML form in the right-hand frame of the Identity Server console.
Identity Server services enable you to group and configure sets of object classes plus attributes while only exposing a subset of attributes through the console interface. Identity Server services are a public interface intended to enable extension of the Identity Server administration facilities.
Java Enterprise System User Provisioning Example Using Identity Server ServicesThis section describes an example of how to provision Messaging Server and Calendar Server users through the Identity Server console. This example is comparable to the sample Messaging Server Service shipped with Identity Server. You can find the sample service in the is_svr_base/SUNWam/samples/integration/user directory.
This example provides information on how to customize the Identity Server console to do generic LDAP provisioning. The example provides only the minimal object classes and attributes needed to enable a user created in Identity Server to log in to Messaging Server and Calendar Server. This example is not intended to provide a complete picture of provisioning Communications products.
For this sample to function, you must install Calendar Server, Identity Server, and Messaging Server against the same Directory Server, and they must all be using the same Sun ONE LDAP Schema v.2 DIT.
This example explains how to add new attributes to a Java Enterprise System user so that you can manage those new attributes by using the User page in the Identity Server. You can use two methods:
The instructions in this section use the method described in the second bullet. These instructions describe two new services that will minimally provision Identity Server users for Messaging Server and Calendar Server.
Note
These example services show how to automate data management tasks by using Identity Server. While these services address the minimal needs of Calendar Server and Messaging Server users, they are not intended to provide a complete provisioning solution.
To enable full user functionality and ensure the proper values are set, refer to the Calendar Server and Messaging Server provisioning documentation. See "User Provisioning, Schema, and Tools Reference" for a listing of this documentation.
High-level Steps to Define a New Identity Server Provisioning Service
Defining a new Identity Server provisioning service involves five operations:
The following sections describe these high-level steps in more detail.
Identifying the LDAP Requirements of Your Application
Most applications that use LDAP have certain user entry requirements, including:
For more information on the object classes with their respective attribute sets, see the Sun ONE Messaging and Collaboration 6.0 Schema Reference Manual (http://docs.sun.com/doc/816-6710-10).
Table G-1 makes use of the user LDAP requirements as specified in the Messaging Server product documentation. In this table, a typical Messaging Server user entry is listed on the left. Some of these object classes and attributes are core to Directory Server and thus Identity Server already manages them.
Defining an Identity Server Service
Identity Server provides an extensible interface for managing LDAP data, enabling you to define a new Identity Server service to manage user LDAP entries. Through this service, you provision mail and calendar users.
For information on creating Identity Server services, see the Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10), Chapter 6, “Service Management.”
Defining a new Identity Server service involves six operations:
- Composing an XML file based on samples
- Adding needed Messaging Server or Calendar Server object classes under the Global section
- Adding minimal Messaging Server and Calendar Server attributes under the User section
- Importing the XML service definition
- Copying the Locale properties file to the Identity Server installation directory
- Restarting Identity Server
See "Defining and Extending an Identity Server Service for Provisioning Messaging" for more information.
Creating a Sample Java Enterprise System UserThis section describes how to quickly create a sample Java Enterprise System user to illustrate Java Enterprise System user account management through Identity Server. This section assumes you are familiar with Java Enterprise System concepts and technologies.
To Create a Sample Java Enterprise System User
- Install and configure Identity Server, Portal Server, Messaging Server, Calendar Server, Directory Server, and Administration Server, with the following sequences:
- Install Directory Server before or during the Identity Server installation.
- Install Portal Server before or during the Identity Server installation.
- Install Administration Server before or during the Messaging Server and Calendar Server installations.
- For Identity Server, specify the default organization as dc=example,dc=com.
- Run the Messaging Server and Calendar Server configuration tools, specifying dcroot as dc=example,dc=com, and Default Organization as the user tree. This creates the following organization: o=Default Organization,dc=example,dc=com. Configuring Messaging Server and Calendar Server loads the required Messaging and Collaboration schema into Directory Server.
- Update the new organization and organization unit to contain the Identity Server object classes.
Because the Default Organization branch was created outside Identity Server, you need to update it before Identity Server can make full use of it. Run the ldapmodify command as follows to mark ou=People,o=Default Organization,dc=example,dc=com with the object class iplanet-am-managed-people-container:
- Load the sample Messaging Server Service into Identity Server. The sample XML file is included with the Identity Server installation root directory.
For example:
cd /opt/SUNWam/samples/integration
/opt/SUNWam/bin/amadmin --runasdn "uid=amAdmin,ou=People,o=Default Organization,dc=example,dc=com" --password password --schema sampleMailServerService.xml
- Copy the associated properties file, which enables localization, to the locale directory.
cp sampleMailServerService.properties /opt/SUNWam/locale
- Access the Identity Server console at the following URL:
http://webserver:port/amconsole
- Register the new service on the Services tab.
- Register the new service with each organization, down to o=Default Organization,dc=example,dc=com.
The new service should be visible under the Services option for the Organization example->Default Organization.
When you create a new service through Identity Server, add the Messaging Server Service and ensure that all required Messaging Server attributes have been filled in.
Provisioning Users by Using the LDAP Modify CommandThe command-line utility ldapmodify, shipped with Solaris™ and Directory Server, operates on LDAP entries by using the Lightweight Directory Interchange Format (LDIF) format. In the example in this section, assume the following:
Before making changes, the user entry in LDAP looks as follows. (Bold object classes are specific to Identity Server).
./ldapsearch -b dc=example,dc=com -D "cn=directory manager" -w password -h localhost -s sub "uid=user1"
uid=user1,ou=People,o=DefaultMailOrg,dc=example,dc=com
sn=user1
cn=user1
iplanet-am-modifiable-by=cn=Top-level Admin Role,dc=example,dc=com
inetUserStatus=Active
uid=user1
objectClass=iplanet-am-user-service
objectClass=inetAdmin
objectClass=iPlanetPreferences
objectClass=inetOrgPerson
objectClass=organizationalPerson
objectClass=person
objectClass=iplanet-am-managed-person
objectClass=inetuser
objectClass=top
userPassword={SSHA}yitmE0+srF68Q7u52ggzxqnkAUY0FxMc+jkXYA==
iplanet-am-user-login-status=Active
By comparing the object classes to the list of required object classes (see Table 11-4), it is apparent that the user is only configured to access Identity Server.
# ldapmodify -D "cn=directory manager" -w password dn: uid=user1,ou=People,o=DefaultMailOrg,dc=example,dc=com
changetype: modify
add: objectclass
objectclass: ipuser
objectclass: userpresenceprofile
objectclass: inetmailuser
objectclass: inetlocalmailrecipient
-
modifying entry uid=user1,ou=People,o=DefaultMailOrg,dc=example,dc=com
After making changes, the user entry in LDAP looks as follows. (Bold object classes are specific to Messaging Server.)
uid=user1,ou=People,o=DefaultMailOrg,dc=example,dc=com
sn=user1
cn=user1
iplanet-am-modifiable-by=cn=Top-level Admin Role,dc=example,dc=com
inetUserStatus=Active
uid=user1
objectClass=iplanet-am-user-service
objectClass=inetAdmin
objectClass=iPlanetPreferences
objectClass=inetOrgPerson
objectClass=organizationalPerson
objectClass=person
objectClass=iplanet-am-managed-person
objectClass=inetuser
objectClass=top
objectClass=ipuser
objectClass=userpresenceprofile
objectClass=inetmailuser
objectClass=inetlocalmailrecipient
userPassword={SSHA}yitmE0+srF68Q7u52ggzxqnkAUY0FxMc+jkXYA==
iplanet-am-user-login-status=Active
At this point, user1 is able to access Messaging Server. For production user creation, you would also want to set various mail attributes. These attributes are needed to enable Messaging Server features. User user1 only has limited functionality and must bear with error messages until you properly set these values.
Note
The preceding example shows one way of adding Messaging Server support to an existing user whose entry was created through Identity Server. In an actual deployment, you would batch load your user base by creating user entries with all these values already set.
Also, this example was produced with the Solaris ldapsearch command and the output is not fully compliant LDIF. The output is in the older University of Michigan notation. When creating LDIF batches, use the standard LDIF notation as generated by the ldapsearch command that ships with Directory Server.
Defining and Extending an Identity Server Service for Provisioning MessagingThe example in this section defines a simple Identity Server service that minimally provisions an existing user for logging into Messaging Server.
Creating a service for a new application requires:
The following example is based on the Sun ONE Identity Server 6.1 Customization and API Guide (http://docs.sun.com/doc/816-6774-10), which describes how to create a service. This example is comparable to the file described previously, and uses the Sun ONE Messaging and Collaboration 6.0 Schema Reference Manual (http://docs.sun.com/doc/816-6710-10), which describes the Messaging Server object classes and attributes.
Code Example G-1 Sample Mail Service
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved
Use is subject to license terms.
-->
<!DOCTYPE ServicesConfiguration
PUBLIC "=//iPlanet//Service Management Services (SMS) 1.0 DTD//EN"
"jar://com/sun/identity/sm/sms.dtd">
<ServicesConfiguration>
<Service name="sampleMessagingServerService" version="1.0">
<Schema
serviceHierarchy="/Java Enterprise System/sampleMessagingServerService
i18nFileName="sampleMessagingServerService"
i18nKey="sample-messagingserver-service-description">
<Global>
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>ipuser</Value>
<Value>inetMailUser</Value>
<Value>inetLocalMailRecipient</Value>
<Value>nsManagedPerson</Value>
<Value>userPresenceProfile</Value>
</DefaultValues>
</AttributeSchema>
</Global>
<User>
<AttributeSchema name="mail"
type="single"
syntax="string"
any="display|required"
<DefaultValues>
<Value>username@domainname</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailAlternateAddress"
type="list"
syntax="string"
any="display|required"
i18nKey="a102">
</AttributeSchema>
<AttributeSchema name="mailDeliveryOption"
type="multiple_choice"
uitype="radio"
syntax="string"
any="display|required"
i18nKey="a103">
<ChoiceValues>
<ChoiceValue>mailbox</ChoiceValue>
<ChoiceValue>native|unix</ChoiceValue>
<ChoiceValue>autoreply</ChoiceValue>
<ChoiceValue>program</ChoiceValue>
<ChoiceValue>forward</ChoiceValue>
</ChoiceValues>
<DefaultValues>
<Value>mailbox</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailHost"
type="single"
syntax="string"
any="display|required"
i18nKey="a104">
<DefaultValues>
<Value>hostname.domain.com</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailUserStatus"
type="single_choice"
syntax="string"
any="display|required"
i18nKey="a106">
<ChoiceValues>
<ChoiceValue>active</ChoiceValue>
<ChoiceValue>inactive</ChoiceValue
</ChoiceValues>
<DefaultValues>
<Value>active</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailQuota"
type="single"
syntax="numeric"
any="display|required"
i18nKey="a107">
<DefaultValues>
<Value>-1</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailMsgQuota"
type="single"
syntax="numeric"
any="display|required"
i18nKey="a107">
<DefaultValues>
<Value>-1</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="mailMsgQuota"
type="single"
syntax="numeric"
any="display|required"
i18nKey="a108">
<DefaultValues>
<Value>100</Value>
</DefaultValues>
</AttributeSchema>
</User>
</Schema>
</Service>
</ServicesConfiguration>
Code Example G-2 en_US Locale Messages for Messaging XML file
sample-messagingserver-service-description=Messaging and Calender Sample - Java Enterprise System
a101=Mail (username@domain)
a102=Mail Alternate Address (username@domain)
a103=Mail Delivery Option (mailbox)
a104=Mail Host (mailservername.domain.com)
a106=Mail User status (active)
a107=Mail Quota (-1)
a108=Mail Msg Quota (100)
a109=extra
Importing and Registering an Identity Server Sample ServiceThis section describes how to import and register a sample Identity Server service.
To Import the New Service into Identity Server
This procedure explains how to add new attributes to the User by creating a new service. The sample service in this example contains four user attributes.
- Make sure the sampleMessagingServerService has not been previously loaded. If it has, remove it by using the amadmin command.
is_svr_base/SUNWam/bin/amadmin --runasdn uid=amAdmin,ou=People,default_org,root_suffix --password password --deleteservice sampleMessagingServerService
- Use the amadmin command to import the new service sampleMessagingServerService to Identity Server.
is_svr_base/SUNWam/bin/amadmin --runasdn uid=amAdmin,ou=People,default_org,root_suffix --password password --schema sampleMessagingServerService.xml
- Copy the properties file sampleMessagingServerService.properties to the is_svr_base/locale directory.
- Restart Identity Server.
Sample Script for Deleting and Importing an Identity Server Service
The following script can be used to delete and import an Identity Server service.
#!/bin/ksh
#
# Sample shell script to automate services import
#
MAIL=sampleMessagingServerService
AMHOME=/opt/SUNWam
SRC=.
ADMINUID="uid=amAdmin,ou=People,dc=example,dc=com"
ADMINPASS=password
#######
# installs service
#######
addService(){
echo
echo "-----------------------"
echo adding service "$1"
$AMHOME/bin/amadmin -u "$ADMINUID" -w $ADMINPASS --deleteservice $1
$AMHOME/bin/amadmin -u "$ADMINUID" -w $ADMINPASS -s $SRC/${1}.xml
echo copying properties file
cp $SRC/${1}.properties $AMHOME/locale
cat $AMHOME/locale/${1}.properties
}
addService $MAIL
$AMHOME/bin/amserver start
To Register a New Service with an Organization
- Log in to Identity Server console as administrator.
- Register the new sample service to the organization where you want users to have the new attributes.
You must click the register button and select the new services. When you are finished, you see the new category. Below it you see the new service. As this example only creates Global and User XML attributes, there will be nothing to configure for organizations.
To Assign a New Service to Users
To Configure a Service for Each User
