Previous     Contents     DocHome     Next     
Directory Server Access Management Edition Programmer's Reference Guide



Chapter 5   Understanding DSAME XMLs and DTDs


This chapter provides information on the two types of XMLs and DTD files used in DSAME, and how they can be used to create custom services. The two major types of XML and DTDs are:

  • service XML files that are defined per the sms.dtd (Services Management Service) Document Type Definition

  • batch update XML files are defined per the amAdmin.dtd. (These batch update XML files are used to perform creates, gets and deletes on various objects (users, groups, roles, people containers, organizations, etc.) in the Directory server tree

The service XMLs are used to define DSAME internal services and custom or external services. These are defined according to the rules defined in an XML DTD (called sms.dtd) in DSAME. Service XMLs and the service DTD is described in this chapter.

The other type of XML and DTD in DSAME is the batch updates XML files and DTD (amAdmin.dtd). These batch update XML files can be used by an administrator or customization engineer to perform batch updates to the Directory server DIT, such as create, get, or delete users, roles, groups, organizations, people containers, etc. This chapter provides some information on the batch update XML file, the amAdmin.dtd which defines rules by which to perform the batch updates to the DIT. Also refer to Chapter 6 "Using the Command Line Interface for information on using the amadmin CLI tool, which administrators and service developers must use to load the service XMLs into DSAME, and to load the batch update XML files.

This chapter provides the following sections:



Understanding DSAME Services

In DSAME, a service is a group of similar attributes defined under a common name. The common name is the service name. The attributes for a service can be attributes from an external service or application like Calendar or they can be from a internal service within DSAME such as authentication, session, logging, or URL policy agent. A service can also be a random set of attributes that a customer might want to group together and manage as a service.

A service can have attributes (user and service) and policy (privilege) attribute/value pairs which are described in service XML files. Attributes are simply configuration parameters with default values assigned to them. A service can contain policy attributes (which define privileges). After services are defined, they can be loaded (imported) into the Directory server using the amadmin CLI tool. Adding the service to DSAME enables an administrator to manage and configure the attribute values in iDS.

A service in DSAME is a set of attributes that are grouped together so that they can be manageable from the DSAME console. This service could be something like "Ford Car Parts", into which you could add 30 attributes, and they could then be managed as a service within DSAME. The DSAME console lets you set and get these attributes; it does not interpret the behavior. Interpreting the behavior is performed by the client application that reads attributes from Directory server.

In DSAME, each service can be modelled as an Directory server auxiliary class with the attributes specified in the XML. Service metadata and default values taken from the XML are stored in a service config branch of the DIT: ou=services,<rootsuffix>, for example, ou=services,o=iplanet.com. (<root_suffix> represents the top of the Directory server tree, for example, o=sun.com or ibm=sun.com or o=iplanet.com.

All the service XML files in DSAME (whether internal or external services that customers might write and integrate) must adhere to the sms.dtd which is located in the <dsame_root>/SUNWam/web-apps/services/dtd directory. Service XML files describing each DSAME (internal) service can be found in <dsame_root>/SUNWam/web-apps/services/WEB-INF/config/xml directory.



Things to Consider about DSAME Services


As mentioned previously, a service in DSAME is a grouping of like attributes defined under a common name. The common name is the service name, for example, "bronze_engineering_mail_service". The attributes for a service can be attributes from an external application like Calendar or they can be from one of the internal services within DSAME such as Authentication, Session, Logging, or URL Policy Agent.

A service can also be a random set of attributes that you might want to group together and manage as a service. For example, a customer might have an auxiliary object class with 10 attributes that are common to all user entries in their Directory server. To manage these attributes through DSAME, they must be described in a service within DSAME. One option would be to add them to the iPlanetAMUserService service. (You can add these attributes through DSAME console or by modifying the amUser.xml file.) This is the service within DSAME that, by default, includes many common attributes from the inetOrgPerson and inetUser objectclasses. This service could be extended to include the attributes in the customer's object class, or the customer might choose to create a new service to manage these attributes. Whether you are extending an existing service or creating a new service, the attributes, after being imported or loaded with the amadmin CLI tool, would be manageable through the DSAME console.

It is important to understand that adding a service to DSAME enables DSAME to manage the attribute values in iPlanet Directory Server (iDS). It does not implement any behavior behind those attributes or dynamically generate any code to interpret the attributes. This means that DSAME can set and get the values, but it is up to an external application to interpret and use these values.

Continuing with the example above, if attributes common to all users were added, an administrator can then set those values or add them to roles or organizations through the DSAME console. For example, a Calendar or phonebook application might typically read those values from the Directory server. An administrator could add new users, setting those new attributes through the DSAME console, but the phone book application would be reading those attributes from the Directory server when querying for specific users.


Internal Services vs. External Services

Note that in the DSAME console under Services that there are many DSAME services shipped with the product—Logging, Naming, Session, URL Policy Agent, etc. These services are managed in the same way as external services. The difference is that DSAME provides code implementations that use these internal services' attributes.

A good example of this is the DSAME URL Policy Agent service. This service defines three attributes that are used by the web agents to check user access to URLs. The DSAME console allows the administrator to configure these attribute values, but the web agent is the external DSAME application that is using those attributes. The core DSAME features (such as logging, authentication, session services, etc.) are each described and managed as any external service would be managed. You can view the XML files that describe each DSAME service in the xml directory under /SUNWam/web-apps/services/WEB-INF/config/xml. This is good place to start when describing or adding a service to DSAME.


Service Schema defines service attributes and optionally default values

A service in a DSAME XML file contains a schema definition section and optionally default values defined within the schema section. Note that in DSAME, the internal services and the sampleMailService files provided in the sampleMailService directory in the DSAME product have only schema definitions sections, where default values are defined. (These defaults appear in DSAME console after the services are loaded into DSAME.)

The schema section of an XML file defines attributes (also called configuration parameters), and optionally default values for each attribute schema defined in the service schema section. The schema section of a service XML file is where a service developer or customization engineer defines configuration parameters for a service and some default values (optional). Note the global schema definition from the sampleMailService.xml file in Code Example 5-1 which defines a global schema attribute and some default values.

Code Example 5-1    Global Schema definition with default values from sampleMailService.xml File  
<ServicesConfiguration>
<Service name="sampleMailService" version="1.0">
<Schema
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
   <Global>
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
</DefaultValues>
</AttributeSchema>
   </Global>

In the case of the sampleMailService.xml provided in the <dsame_root>/samples/admin/cli/sampleMailService directory and the other internal DSAME service XMLs provided in the DSAME product, the schema is defined along with any default values that the service developer wants to define for that service's attribute. This way, these default values display in DSAME console, and speed the process of creating service templates for administrators.



What Happens When you Register a Service


To register a service, the absolute requirement is that you must define schema in a service XML. Optionally, a service developer can define default values for the attributes within each attribute schema definition. (See Code Example 5-1 for an example of an attribute schema definition with some default values defined.) If you do not define default values for the attributes defined in the schema, then no default values will display in the attribute fields for the service in DSAME console.

After registering a service (either through amadmin or DSAME console), the configuration data (which is the attribute schema definitions with any default values) is uploaded for that particular service. Then the administrator or customization engineer can change the configuration parameters' values from the default values, if they exist, through the DSAME console. The configuration data is what the administrator sees displayed in the DSAME console after the service XML schema and configuration data is imported using amadmin.



Overview of Services Management in DSAME


This section provides some information on the types of service management provided by DSAME. DSAME enables different types of administrators perform three types of management:

  • Services and User management—The Services Management module (comprised of services and user management) provides a solution for registering services and managing service and user attributes. The Services Management service (module) is also comprised of user management, which deals with managing the structure of a customer's directory. This includes creating, deleting, and getting organizations, sub-organizations, groups, roles, and users.

  • Policy management—The Policy Service provides solutions for managing (defining, modifying, and removing) policies for resources, and to determine users' privileges to resources. It deals with the creation of policies and how they are applied to a role or an organization.

In the iPlanet DSAME product, there are 17 services (including DSAME console, Logging, Session, six Authentication services (such as LDAP, Radius, Certificate, Anonymous, Self-registration (Membership)), URL Policy Agent, Naming, etc.) that get installed by default when the product is installed. (These DSAME services are sometimes referred to as "internal" services, as distinguished from "external", or customized services that customers may add to DSAME.) If customization engineers or service developers want to add new services that are external to DSAME, they must write service XML files and load them into DSAME, for DSAME to be able to recognize and manage the service's attributes. Service developers must write service XML files when creating a custom service if you want a service's attribute/value pairs to be manageable through DSAME console. For example, if creating a custom pluggable authentication service in DSAME 5.0, you must create a new service XML for your custom service and load it into DSAME using the amadmin CLI tool. (See Chapter 6 "Using the Command Line Interface for information in using the amadmin CLI tool to load services.)


Services Management Module in DSAME

DSAME's service management component provides a mechanism for services to define and manage their configuration data. It is during the development stage that service schema and configuration parameters get defined (typically by a customization engineer or service developer), and it is during the deployment stage that these parameters get configured (typically by an deployment engineer or administrator). Consider, as an example, the implementation of a mail service. It is during its development that configuration parameters such as cache size, mail quota, and mail servers get defined, typically by a service developer who is developing a service or application. Then, during deployment, administrators and/or users typically configure these service attributes, also called "configuration parameters."

DSAME's service component provides a mechanism for service developers to define their configuration parameters and optionally provide default values. The mechanism is through multiple service XML files that must adhere to the DTD defined by DSAME (sms.dtd). The DTD and some sample service XML files are described later in this chapter. The definition of the configuration parameters and optional default values in the service XML file is called the "service schema" and sometimes referred to as "configuration data."

Services typically have different kinds of configuration parameters. For example, certain parameters are applicable to an entire DSAME installation (such as port number and server name), and some are applicable to users (such as mail quota). These different kinds of configuration parameters are stored and managed differently. The services management services component in DSAME provides the following service attribute categories for applying and differentiating control parameter definitions.

In DSAME, all the service attributes you define in service XML files must be one of the following five types of service attributes:

  • global

  • organization

  • dynamic

  • policy

  • user

These service attribute types are described in more detail later in this chapter, along with examples of each type of service attributes, and when a service developer would use them when defining a custom service.

The following sections provide brief descriptions of the five attributes used by DSAME 5.0.


Global Attributes

The following apply for global attributes:

  • Global: parameters that are common across a DSAME configuration for all services, and for the entire DSAME installation. Changes to these parameters would affect the entire service.

    Examples: A port number or a security algorithm that must be used by all servers. Cache size and maximum number of threads.

    Global parameters or attributes are only manageable from the DSAME console Services page. They cannot be configured for an organization, user, or role.

  • Cannot be configured for organizations, roles, or users.

  • They are global across a DSAME configuration.

  • Values of these attributes can be modified using the Service Management page in DSAME console.

In DSAME 5.0, organization and global attribute data cannot be accessed from an external application. This is because these attributes are not stored as LDAP objects in the Directory server; they are stored as static blobs of data, thus they are not accessible by using LDAP commands. The global and organization attribute types can be considered private in DSAME 5.0, except for when creating custom authentication services.


Organization Attributes

  • Organization: parameters that can be configured differently for various organizations. Changes to these parameters would affect only the organization. An organization attribute does not use CoS. In DSAME, all the internal authentication services are defined at the organization level.

    Example: Authentication services used by an organization.

    When defining a custom authentication service XML in DSAME 5.0, you use global and organization attributes only.


Dynamic Attributes

The following apply for dynamic attributes:

  • These attributes can be assigned to roles or organizations which are then inherited by users that possess the role or belong to an organization.

  • Default values can be specified.

  • When service attributes are assigned to more than one role or organization, a conflict can arise. In such cases, there could be two possible behaviors, attribute aggregation (merge-schemes) or single value based on template priority (default).

  • Uses CoS (class of service). (For details on CoS, see the Directory server documentation.) A dynamic attribute/value pair set at the organization level will be inherited by all subentries including users. For example, a dynamic attribute set in a role will be inherited by any user that possesses that role.

  • Parameters that apply to all user objects. Changes made to these parameters would affect all the user objects.

    Examples: Organization's address; mail servers; company name; manager's name.

    Dynamic service attributes are modelled using CoS (Class of Service). A dynamic attribute set at the organization level will be inherited by all subentries including users. A dynamic attribute set in a role will be inherited by any user that possesses that role. (Dynamic attributes function and are used internally the same as policy attributes.)


Policy Attributes

The following apply to policy attributes:

  • Policy attributes are a special type of dynamic attribute. Policy attributes function identically to dynamic attributes in DSAME. Policy attributes are used specifically only when defining policy objects.

  • Used to create named policies under an organization.

  • There is no support for default values.

  • Currently, DSAME has only one service with policy attributes—URL Policy Agent.

  • Attributes for URL Policy Agent use the CoSQualifier aggregation option. The default is aggregation. (CoSQualifier has two settings: aggregation (default) or merge-schemes.)

  • Policy (and dynamic) attributes can be retrieved and accessed using LDAP commands; they are stored as LDAP objects in the Directory server.

  • Policy attributes are parameters that define the privileges provided by the service.

    Example: A web server defining the URL access privileges through either GET or POST.

Administrators can manage policy attributes only from the Policy page in DSAME console. You cannot set policy attributes at the user level—only the organization and role level.

Policy or named policy objects are not manageable by LDAP; they are stored as static blobs of data in Directory server.


User Attributes

The following apply to user attributes:

  • Attributes that will only be part of the user entry, and that different for each user entry.

  • User attributes are parameters that are specific to a user. Changes to these parameters would affect a particular user. Configuration information that can only be set in a specific user entry; it cannot be set at the role and organization level.

    Example: A user's locale. Another example of a user attribute would be password.

    Administrators can only set user attributes in a user entry—not in a role or an organization entry.

Although the service management module provides support for storing and managing the schema for the service, it manages schema data only for global and organization types. The user and dynamic configuration data is managed by the user management module, and policy configuration is managed by the policy management module. However, both user management and policy rely on service management for service schema management. The elements and attributes in the DTD (sms.dtd) that are supported in DSAME 5.0 are described later in this chapter. Service developers can use the supported elements and attributes to described later in this chapter in their custom services.

The service schema and any default values defined within the schema section in a service XML file are stored in the Directory Server. (Note, however, that global and organization attribute data is stored as static blobs of data, thus global and organization attribute data is not accessible through LDAP commands. Also, they should be used only when writing custom authentication services in DSAME 5.0.


Defining and Adding Services to DSAME

This section provides some information to consider when using existing applications whose attributes you want to be manageable from DSAME console, as well as when creating new services to be manageable by DSAME console.


Adding a Custom Service to DSAME

If you are writing an application or if you have an existing application that already has attributes in the Directory server, and you want that application's attribute data to be manageable from DSAME console, then you need to define a service XML using the elements and attributes that DSAME 5.0 supports. (See the sections in this chapter that describe the supported elements and attributes for defining services in DSAME 5.0.)

If an application already uses certain Directory server attributes, DSAME should be able to manage these attributes with little customization required. You might need to change some of the attributes so that the application can get certain attribute values from the user.

Typically, you could model user and dynamic attributes and the application would work and you could manage the attributes through DSAME console. For example, for an existing customer application "BronzeMailService1", a customization engineer could create a service XML file for that mail service called "BronzeMailService1.xml", define some attributes in it, then run the amadmin tool to load the service and its attribute/value pairs into DSAME, modify certain configuration files, and then the attributes will be manageable from the DSAME console, and will be readable and writable by Directory server.


Note

There can be only one default value for a particular Global attribute (configuration parameter) for the entire platform. These attribute values are defined in the service XML files with "global" schema attribute types.


When a service developer or customization engineer is configuring DSAME, he/she configures attribute schema and default values within the schema section in the service XML files. Later, when an administrator enables a service for an organization in DSAME console, the attribute schema and default values that were specified previously in the service XML file will display, thus be manageable, in DSAME console. For example, when an administrator enables Authentication under the Services page, you would see the runtime defaults that were configured at installation time when DSAME loaded in the service schema for all the attributes for that service, along with default values for the attributes, from all the service XML files.


When You Create a Service XML, Attributes Must be Defined (Default Values are Optional, but Recommended)

When the service is first created, however, its attributes and default values are defined in the XML files. Service XML files are loaded into DSAME through the amadmin CLI tool. When an administrator changes the default values in DSAME console, he/she can change those attribute values, then click Submit to create a modified service template for an organization or a role.

Remember that you only need to define a service XML if you want that service's attributes to be manageable from DSAME console; otherwise, there is no need to define a service XML.

You must model any new services in service XML files if you want that service's attributes to be manageable from DSAME console.


Attribute value in schema provides a default value for administrators and users

The attribute value a service developer defines in a schema section of a service XML file provides a default value for that attribute or configuration parameter. The administrator can always change the default value to some other value in DSAME console.

After importing a service schema with attribute/value pairs defined using amadmin, then the administrator can change the values from the defaults on an as-needed basis, then click Submit to create a new template, which creates a new configuration template.


DSAME's service XML files provide default values for service attributes
DSAME has the notion of default values for service attributes. When describing an attribute for a service in XML, the default value(s) can be set. The defaults specified in the service XML files are used when adding the service attributes to a role or organization. At the time an administrator configures the attributes for a role or organization in DSAME console, a page is displayed with the default values. Administrators can change the defaults or the submit the service template using the defaults. Or, the default values can be set in the service management pages in DSAME console. These defaults are global and can not be set per organization.


Defining an empty attribute value in Schema

A service developer could also define an empty field in the schema definition with double quotes. For example, you could define " " as one of the attribute values.

Code Example 5-2    Excerpt showing an empty attribute value in schema
   <Global>
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
</DefaultValues>
</AttributeSchema>
   </Global>


Using DSAME to manage attributes in your existing DIT

You may want to use DSAME to manage attributes in your existing DIT. Your existing DIT might happen to have a lot of customized user attributes. In this case, you could define all your attributes to be User attribute types in either a User service XML file (defined in the amUser.xml) or a service XML file (which could be a customized service XML file you add to DSAME, called an "external" service XML file).


When Adding a new Service or Application, You must Define Schema (Object classes and attributes) in Directory Server

If a service or application's attributes do not already exist in the Directory server's schema, you need to define the schema (object classes and attributes) in Directory server. You would need to add object classes for every new attribute that the Directory server does not already have in its schema so that DSAME and Directory server can manage those attributes.


One way to define new service attributes in DSAME
A customer could also define new service attributes. To add attributes to the Directory server schema, one way is to go to Configuration/Schema page in Directory Server console which contains the schema for the Directory server.


Adding an Existing Application to DSAME

Typically, if a customer is using an existing application, and wants its attributes to be manageable by DSAME, the schema is probably already defined and has been loaded into Directory server, so that Directory server already knows what attributes and object classes that application uses.

If Directory server does not already have your existing application's attributes and object classes loaded into it, then you need to update the Directory server with the new or modified objectclasses and attributes using the ldapmodify command or by using Directory Server Console.


Enabling a Service for an Organization or Role in DSAME console

In the DSAME console, you assign service attributes to an organization or a role by enabling that service for the organization or role, then creating a service template and modifying the attributes for that service. After you have created the template and set the values, all users under that organization will inherit those service attributes.


Note

For every node or object underneath that organization or that role will inherit that service's attribute/value pairs only if dynamic attributes have been assigned at the organization level or the role level.)


To assign the service attributes to a role, you must first register the service in the role's parent organization. Then the administrator could configure the service for the role and set the values. When a user is assigned to the role, he or she will inherit the attributes from that role, provided that the attributes defined at the organization or role are defined as dynamic attributes. A user can have multiple roles thus would inherit attribute values from multiple parent organizations.



Defining Global Attribute Types in a Service


You could also define or have attributes in a service that are "global". For example, an application might use a global attribute such as "port number", and it also might have an attribute such as User phone number, which is always specific to a user. A User attribute is one that would not make sense for it to be applied to the entire organization, for example, but would apply only to a specific user, for example, FirstName and Last Name, or EmployeePhoneNumber. The DSAME console shows a User attribute only in the context of a specific user; it does not apply to the organization or role level.

Global attributes are attributes that cannot be applied to organizations, roles or users. They are global across a DSAME configuration. They are typically used for things like ports, protocols, and server names. Global attributes are settable in the DSAME console under Service Management.


Note

In DSAME 5.0, attributes defined as Global (and Organization) can only be accessed using the DSAME SDK. Global and organization attributes are stored as static blobs of data in the Directory server, and are not accessible by using LDAP commands such as ldapsearch.

Because the DSAME SDK is not public (not exposed to customers for customization purposes) in DSAME 5.0, when customizing or creating external services, you should not use the Global or Organization attribute type (except for Authentication services). The global (and organization) attributes are the only attributes that you should use for your custom authentication services in DSAME 5.0.


Global attributes are platform-wide attributes that are global across an entire configuration, for example, server_host or port_number. The values of these attributes can be modified through the Service Management page in DSAME console.

Global attributes are typically applicable to things such as protocol, host name, server name, and port number. Global applies to attributes that apply across the entire platform or DSAME installation. Global attributes are attributes that everyone using that platform configuration will get by default. After an administrator configures a service for a particular organization or role in DSAME console, he/she could customize that service and its attributes thus creating a new service template, and then assign that service template to an organization or a role.

Typically, authentication modules in DSAME use only global and organization attributes.)

The Services page in DSAME console displays the default attribute/value pairs for each service that has been previously loaded into DSAME. For example, global attributes can be managed by administrators through the Services page. A global attribute might be platform locale. Whenever DSAME performs logging, it logs to the platform locale; it should be logged on one platform locale. The parameters loginUrl and logoutUrl also apply to the entire platform, thus are defined as global attributes. Naming service attributes are typically also defined as global attribute types.

Global attributes cannot be applied to organizations, roles, or users.

DSAME allows you to manage and change attribute values, either through XML files or by modifying default values for attributes, then creating a new service template.

When you display a role or an organization for a service, you get a generic Edit page. All that Edit page does is grab all the attribute values and types from the service XML and displays them; it does not interpret the attribute/value pairs and behavior.



Defining Organization Attributes in a Service


Authentication attributes are a good example of Organization attributes. Because authentication would apply on a per-organization basis, it would not make sense for the attributes to be dynamic since all users would inherit those attributes. All Authentication service attributes in DSAME are defined as Organization type.

Organization attributes are attributes that only apply to organization entries and when it is not desired that users inherit those attributes, as would happen if they were defined as dynamic attributes.


Note

In DSAME 5.0, attributes defined as Organization (and Global) attributes can only be accessed using the DSAME SDK. Global and organization attributes are stored as static blobs of data in the Directory server, and are not accessible by using LDAP commands such as ldapsearch.

Because the DSAME SDK is not public (not exposed to customers for customization purposes) in DSAME 5.0, when customizing or creating external services, you should not use the Global or Organization attribute type (except for Authentication services). The only service in DSAME 5.0 that global (and organization) attributes can be used for are when creating a custom pluggable authentication service.

However, global and organization attributes are used by the DSAME internal services, such as session, naming, logging, authentication, etc.




Defining Dynamic Attributes in a Service


Dynamic attributes are attributes that can be assigned to roles or organizations which are then inherited by users that possess the role or belong to the organization. Dynamic attributes promote ease of administration and scalability by allowing attributes to be assigned to roles or organizations instead of setting these attributes in each user's entry. (See Section "Adding attributes Common to all Users to the User Service in DSAME" on page 125.) When these attributes change, the administrators only have to change them in the role or organization instead of in every user entry. Also, by setting the attributes in a top level or suborganization they can be used as defaults unless overridden by roles or suborganization attributes that have a higher priority.

An example of a Dynamic attribute might be a mail server. Typically, an entire building might have a common mail server, so each user would have a mail server attribute in their entry. If the mail server ever changed, every user attribute would have to be updated. If the attribute was in a role that each user in the building possessed, then only the attribute in the role would have to be modified. That, of course, is a very simple example, but a role or organization may have many attributes from different services assigned to it.

Dynamic attributes are attributes that are modelled using class of service (CoS in Directory server). (Dynamic attributes in DSAME use the iPlanet Directory Server CoS and roles feature. For more information on how CoS works in Directory server, refer to the Directory server 5.0 documentation.) A dynamic attribute that is set at the organization level in DSAME console will be inherited by all subentries including users. A dynamic attribute set in a role will be inherited by any user that possesses that role.


Organizations and Dynamic Attributes

The following things apply to organizations and dynamic attributes:

  • Multiple services can be registered per organization or sub-organization.

  • Attribute and policy values of an activated service are customizable per organization.

  • After service activation, all the entries in the sub-tree of the organization inherit the service attributes.



Defining Dynamic and Policy Attributes

Because DSAME uses CoS, the service definitions typically need to be defined at the organization level. So, if an entry has a certain CoS entry, it gets a CoS definition. Roles know that based on this filter, all these users have this role. It is done differently for regular roles for users; they just have a pointer to that role.

Dynamic attributes can be defined for an organization, for an organizational unit (ou), and they can be defined for a role. It depends on how people want to manage their users. You do not even have to use roles at all; you could use organizational unit (ou's) instead.

In the example discussed previously, where you have a manager and an employee, it would be better to have one role that is for a manager and an employee, instead of one role for a manager and one role for an employee and then aggregate it.

Or another way is just to aggregate in all the other attributes. What DSAME does is it performs a get operation on the User object, and then based on this schema data, it can tell what service it's from. DSAME can distinguish among different types of attributes, for example, it can determine which are your authentication attributes, which are your session attributes, etc.



Roles in DSAME


Roles in DSAME don't have anything to do with ACIs, at least within the context of looking at roles from the DSAME console. A role is just a way to group some attributes for services which you can then apply to a user, based on whether that user possesses that role or not. Internally, DSAME uses roles for administrator permissions based on ACIs. Roles in DSAME are just a group of service-related attributes, which are viewable from the DSAME console.

In DSAME, a role uses the nsrole attribute. An administrator can add or assign services and attributes to roles. In Directory server, roles are primarily a way to group users. However, in Directory server, it is recommended that if you are creating a new DIT, you should use roles instead of groups because they are more efficient. In Directory server, a role is an entry grouping mechanism that allows applications to locate the role of an entry, rather than select a group and browse the members list.

For example, for inheritance to work, you could define a role that is located within an organization that has a role filter of objectclass=*. What that means is that it's a filtered role which means that if you pass this filter, the entry's got that role. Thus, objectclasses with an asterisk at this level means that every subentry has that role.


What Happens when a User is Assigned to a Role

When a user is assigned to a role, that user inherits the attributes from that role. A user can have multiple roles and inherit attribute values from multiple parent organizations. DSAME has the notion of default values for service attributes. When describing an attribute for a service in XML, the default value can be set. The defaults are used when adding the service attributes to a role or organization. At the time an administrator configures the attributes for a role or organization, a page displays with the default values. The administrator can change these defaults and submit a newly-created template, or submit the template using the defaults. The default values can be set in the service management pages. The defaults are global (that is, they apply to the entire DSAME installation or platform, and may not be set per organization.)


Overview of Roles in DSAME

This section provides some information on how DSAME uses roles, ACIs, and CoS (Class of Service).

In the DSAME 5.0 release, there is no notion of an "administrator" or "admin" in the DSAME console; that is, administrator roles or admin roles are not distinguished from other roles.

The admin roles are not differentiated from other roles that might be created by administrators in DSAME console. For example, when you are at an organization level in the DSAME console, for example, o=sun.com, and you go to the Roles page, you can view all the roles. These roles could be administrator roles, such as HelpDeskAdminRole, or a Policy_role, a mail_role, an OrgAdminRole, etc. All the roles are listed on the same page. If you have 100 roles, you see a list of 100 roles.

When you sit at the organization level, you get an entire list of roles. Say, you wanted to find the admin for PeopleContainer, which may be down another level. You have to go to the organization level, then look for the role based on the name, click on that, then add the user to the role.

When you are at the Organization level, and click on suborganization, you see all the roles—administrator-type roles (TopLevelHelpDeskAdmin Role, HelpDeskAdminRole, OrgAdmin, OrgHelpDeskAdmin, etc.) and other types of roles created by administrators. These could be termed "access control roles", as they are roles that define a user's access. There could also be some "service roles", for example, "mail_service_role" or "authentication_service_role".

You can no longer go to the PeopleContainer, for example, and view your roles there. You must go up the Organization level and then view the roles there.

The notion of a role represents access control. The point of a role is to get service attributes and policy attributes. Within DSAME console, an administrator can assign a service to a role.


How DSAME uses Roles

This section gives some information on how DSAME uses roles and CoS.

  • Multiple roles can be created for each organization or sub-organization.

  • A role can be enabled with any number of services with customized attributes and policy.

  • By adding a service to a role, any user with that role will inherit the service attributes and policy from that role. Users can have any number of roles.

DSAME uses Classic CoS and role templates. (For information on Classic CoS, see the iDS 5.0 documentation.)


Roles

Roles are a new entry grouping mechanism in iDS 5.0 that unify the static and dynamic groups. Roles are designed to be more efficient and easier to use for applications. For example, an application can locate the role of an entry, rather than select a group and browse the members list.


CoS

Class of Service (CoS) allows you to share attributes between entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements.


CoSQualifiers used by DSAME

  • DSAME supports default and merge-schemes CoS qualifiers. The qualifier can be specified in the XML (service schema description) file when describing the manageable attribute of the service.

  • If no CoS qualifier is specified, default is assumed.

As an example, the URL Policy Agent uses merge-schemes to obtain aggregated values for Allow, Deny, and Not Enforced attributes.


Organizations and CoS

  • Multiple services can be registered per organization or sub-organization.

  • Attribute and policy values of an activated service are customizable per organization.

  • After service activation, all the entries in the sub-tree of the organization inherit the service attributes.


Registering a Service Creates a CoS Definition and CoS Template

Registering a service for a particular organization creates a COS definition for that service.

A class of service (COS) allows you to share attributes between entries in a way that is transparent to applications. COS simplifies entry management and reduces storage requirements.

There are three COS definitions:

  • Indirect COS Definition

  • Direct/Classic COS Definition.

  • Pointer COS Definition.

When an imported service gets registered for an organization, a Direct/Classic COS Definition is created for that service based on the policy template type and non-policy template type.

A classic COS identifies the template entry by both its DN and the value of one of the target entry's attributes.

This service must have been imported by using the amadmin CLI tool for that particular organization.


Roles in DSAME are at a higher level of abstraction than Directory server roles

Roles are a new entry grouping mechanism in Directory Server 5.0 that unify the static and dynamic groups. Roles are designed to be more efficient and easier to use for applications. For example, an application can locate the role of an entry, rather than select a group and browse the members list.

Roles in DSAME do not function in the same way as Directory server roles. They are a higher level of abstraction. DSAME roles are an abstraction of Directory server roles.

Access control in DSAME is implemented using Directory Server roles. Users in DSAME inherit the directory access permissions using directory roles. ACIs are not created using the groupdn as the subject.

When DSAME is installed, eight different administrator role types are created. Administrators can create new admin roles and modify them through DSAME console.

Default ACIs for the roles are stored in a global configuration attribute in the iplanet-am-admin-console-default-acis attribute. This attribute is defined in the iPlanetAMAdminConsole service XML profile. Default ACIs can be modified through the DSAME console.


How Organizations and Roles use Dynamic Attributes

Organizations and roles in DSAME frequently use dynamic attributes. Dynamic attributes would typically be used when you want to define a role at the organization level and have all the users inherit that role and its attribute/value pairs.


One way to Add new attributes to user entries
If an administrator does not care about defining a role at the organization level and having all the users inherit a particular attribute and its values, then the customization engineer could define all the attribute types as User. For example, you might have 50 auxiliary classes that all users possess. To manage those 50 auxiliary classes, you might define one service XML file that defines all these auxiliary classes, then load them into DSAME using amadmin. Those attributes would then appear in the DSAME console.

If you have an existing DIT, you may not care about using dynamic attributes. You may not care if it's time-consuming to change one attribute for 50 users. One way a customization engineer might make these changes is to just modify or add the attributes for the 50 users through Directory Server Console.


How Dynamic Attributes are used in Roles

For example, you might decide to create a contractors role which has attributes from the session service and the URL Policy Agent service. Then, when new contractors start, the administrator could just assign them a single role instead of setting all the attributes in the contractors entry. If the contractor were to become a full-time employee, the administrator could just assign them a different role.


How Dynamic Attributes are used in Organizations and Roles

In the DSAME console, you assign service attributes to an organization by enabling that service for the organization, then creating a service template and modifying the attributes for that service, then assigning the service to an organization or a role. (Creating a template typically consists of changing some default values for a service in DSAME console, then clicking Submit to create the template. You can also create a template without changing any of the default values.) After you have created the template and set the values, all users under that organization will inherit those service attributes (only for dynamic attributes that are assigned to an organization).


How DSAME Dynamic and Policy Attributes Use CoS

Both dynamic and policy attributes uses CoS. Class of service (CoS) allows you to share attributes among entries in a way that is transparent to applications. CoS simplifies entry management and reduces storage requirements. For specific information on how CoS works, see the Directory server 5.0 documentation on advanced entry management.

Clients of the Directory server read the attributes on a user's entry. With CoS, some attribute values may not be stored with the entry itself. Instead, they are generated by Class of Service logic as the entry is sent to the client. Each dynamic (and policy) entry is comprised of the following two entries in your Directory server:

  • CoS Definition Entry—the CoS definition entry identifies the type of CoS you are using.

  • Template Entry—The template entry contains a list of the shared attribute values. Changes to the template entry attribute values are automatically applied to all the entries sharing the attribute.

The CoS definition entry and template entry interact to provide attribute information to their target entries, which is any entry within the scope of the CoS.

Dynamic attributes in DSAME work in such a way that any subentry under o=sun, and all the way down the tree, if that entry is gotten directly (for example, if you do an LDAP search against the entry), you get back the attributes for that entry plus anything that is in the CoS template. This means that all the users are going to automatically get these values. For example, you might have your locale set by default. The top of your tree might be o=sun, and you might have two regions: east and west. For example, you could set the division attribute so that all users would get it. That way, if you move a user around, they automatically get the new attributes. With dynamic attributes (and for policy attributes also), you do not have to modify that user's entry. Or if you create a new user, you don't have to set those attributes; they automatically get those attributes by inheriting them from the organization level (because the attribute has been defined as a dynamic attribute, and assigned to that organization). It is also possible for users to inherit attributes from the role level.

Also, dynamic attributes save space in the DIT. For example, if you have 2 million users and you have 70 attributes, you would have to store that entry 70 times 2 million users. By putting this entry into a dynamic attribute, the Directory server only needs to take up the size of one entry. This typically applies at the organization or role level.

There are two important notes about dynamic (inheritable) attributes. They work at both the role and organization levels (that is, also at sub-organizations and organizational unit levels). In DSAME, organizations or sub-organizations (organizationalUnits) are viewed and handled similarly.


Roles and Dynamic Attributes

The following things apply to roles and dynamic attributes:

  • Multiple managed roles can be created for each organization or sub-organization.

  • A managed role can be enabled with any number of services with customized attributes and policy.

  • By adding a service to a role, any user with that role will inherit the service attributes and policy from that role.User can have any number of roles.

DSAME uses Classic CoS and role templates.


Conflicts with multiple organizations or roles

There is the possibility that a dynamic or policy attribute could be assigned to more than one role or organization, thus creating a possible conflict. When this happens, there are two possible behaviors—attribute aggregation or single value based on template priority. When the attribute is described in the service XML, the CoSqualifier attribute can be set to one of the following:

  • default

  • merge-schemes

    default—If CoSqualifier is set to "default" or is missing, then the template with the highest priority is returned. When a template is created for an organization or role in DSAME console, a priority can be set for the template.

    merge-schemes—tells Directory server that when the attribute appears in more than one organization or role, the values should all be aggregated and returned as a multi-valued attribute.


Conflicts and Dynamic (or Policy) Attributes

DSAME supports the CoS qualifiers "default" and "merge-schemes" settings. The qualifier can be specified in the service schema definition in the XML file when describing the attribute for the service that you want to be manageable from DSAME console.

If no CoS qualifier is specified, default is assumed.

DSAME out of the box has only one service with policy attributes—the URL Policy Agent. For example, the URL Policy Agent service in DSAME uses the CosQualifier merge-schemes setting to obtain aggregated values for the Allow, Deny and Not Enforced attributes. This means that all policies from multiple roles or organizations will be aggregated. For example, if the "Employee Role" says that you can access

*/employee.html

and the "HR Role" says you can access

*/hr.html

then when my access is returned to the URL Policy Agent, it will get both

*/employee.hml

*/hr.html

If the URL Policy Agent attributes were defined as priority, you would get the list of URLs from the named policy with the higher priority. See the advanced entry management sections in the Directory server 5.0 documentation for detailed information on CoS.


Roles

This section provides some information on how DSAME uses the Directory server 5.0 Roles and CoS features.

DSAME provides for the dynamic configuration and management of users, services and policy. The basic building blocks of DSAME are organizations, groups, roles, CoS, services, and users.

A service is comprised of attributes and policy (privilege attributes) described in XML and loaded into the Directory server using the amadmin tool. Service attributes can be tagged as either global, organization, dynamic, policy, or user. Global attributes are service configuration attributes that are only modifiable on a platform-wide basis. User attributes can only be set for a particular specified user. Dynamic and policy attributes can be set at the organization, sub-organization, and role levels and are inheritable by sub-entries based on the iDS CoS feature. Organization attributes can be set for a particular organization, for example, mail servers used by an organization, or an authentication service (such as LDAP or RADIUS). Each service is modeled as an auxiliary class with the attributes specified in the XML. Service metadata and default values taken from the XML are stored in a service config branch of the DIT—ou=services,<rootsuffix>; for example, ou=services,o=iplanet.com.


Organizations and CoS

Any number of services can be enabled for an organization or sub-organization. When a service is enabled, the attribute and policy values can then be customized specifically for that organization. By enabling a service for an organization, all entries in the sub-tree will inherit the service attributes (provided they are defined as "dynamic" attributes) unless overridden with a lower CoS priority. To accomplish this, DSAME uses classic CoS and role templates. There is a default filtered role with nsRoleFilter set to (objectClass=*) for each organization. DSAME uses the CoS template of that default filtered role to define default service attributes for all entries in the organization's sub tree.

The following is an example of an organization, its default CoS role and one service enabled.

Code Example 5-3    Organization Example with default CoS Role and One Service Enabled  
dn: o=iplanet.com,o=isp
objectClass: top
objectClass: organization
dn: cn=ContainerDefaultTemplateRole,o=iplanet.com,o=isp
objectClass: top
objectClass: nscomplexroledefinition
objectClass: nsfilteredroledefinition
objectClass: nsroledefinition
objectClass: ldapsubentry
nsRoleFilter: (objectclass=*)
cn: ContainerDefaultTemplateRole

dn: cn=iPlanetAMAuthService,o=iplanet.com,o=isp
CoSspecifier: nsrole
objectClass: CoSclassicdefinition
objectClass: top
objectClass: CoSsuperdefinition
objectClass: ldapsubentry
CoStemplatedn: cn=iPlanetAMAuthService,o=iplanet.com,o=isp
CoSAttribute: iplanet-am-auth-menu
CoSAttribute: iplanet-am-auth-profile-required
CoSAttribute: iplanet-am-auth-admin-module
CoSAttribute: iplanet-am-auth-authenticators
CoSAttribute: iplanet-am-auth-login-workers

dn: cn="cn=ContainerDefaultTemplateRole,o=iplanet.com,o=isp",cn=iPlanetAMAuthServi ce,o=iplanet.com,o=isp
cn: "cn=ContainerDefaultTemplateRole,o=iplanet.com,o=isp"
cn: cn=ContainerDefaultTemplateRole,o=iplanet.com,o=isp
objectClass: CoStemplate
objectClass: top
objectClass: extensibleObject
objectClass: ldapsubentry
iplanet-am-auth-menu: LDAP
iplanet-am-auth-profile-required: false
iplanet-am-auth-authenticators: com.iplanet.dpro.auth.module.ldap.LDAP
iplanet-am-auth-login-workers: com.iplanet.dpro.auth.server.HTMLLoginWorker


Roles and CoS

Any number of managed roles may be created for each organization or sub organization. A managed role may be enabled with any number of services with customized attributes and policy. By adding a service to a role any user with that role will inherit the service attributes and policy from that role. Users may have any number of roles. To accomplish this DSAME uses classic CoS and role templates. The following is an example of a role with the name eng, the authentication service enabled and customized for the eng role, and a user with the eng role.

Code Example 5-4    Example of Role "Eng" and User with the "Eng" Role  
dn: cn=eng,o=iplanet.com,o=isp
objectClass: nsmanagedroledefinition
objectClass: nssimpleroledefinition
objectClass: top
objectClass: nsroledefinition
objectClass: ldapsubentry

dn: cn="cn=eng,o=iplanet.com,o=isp",cn=iPlanetAMAuthService,o=iplanet.com,o=is
objectClass: CoStemplate
objectClass: top
objectClass: extensibleObject
CoSPriority: 10
preferredLocale: en_US
preferredTimezone: pacific

dn: uid=jamie,ou=People,o=iplanet.com,o=isp
cn: jamie nelson
sn: jamie
objectClass: iplanetPreferences
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetUser
objectClass: inetOrgPerson
nsRoleDN: cn=eng,o=iplanet.com,o=isp


Access to Directory server is through proxy authentication
All access to the directory is through proxy authentication. A proxy user is created at installation time and all access is through that user proxying as the requesting user.


Roles and ACIs

Note the following with regard to how roles and ACIs are used by DSAME:

  • Access control for DSAME is implemented using iDS roles.

  • Users in DSAME inherit the Directory access permissions using directory roles. ACIs are not created using the groupdn as the subject.

  • DSAME, when installed, creates eight (8) different admin role types.

  • New Admin roles can be dynamically created and modified using DSAME console.

  • Default ACIs for the roles are stored in a global configuration attribute in the iplanet-am-admin-console-default-acis attribute. This attribute is defined in the iPlanetAMAdminConsole service XML profile (amAdminConsole.xml).

  • Default ACIs can be modified.

Access control for DSAME is implemented using iDS roles. Before Directory server 5.x, access control would have typically used a similar design, but with groups instead of roles. Users would inherit directory access permissions based on group membership. Users in DSAME inherit the same types of directory access permissions using Directory server roles. DSAME does not create any ACIs using the groupdn as the subject.

When the iPlanet DSAME product is installed, nine administrator role types are created. Those types are Top Level Admin, Top Level Help Desk Admin, Org Admin, Org Help Desk Admin, OrgUnit Admin, OrgUnit Help Desk Admin, Group Admin, Group Help Desk Admin, and People Container Admin. These role types have a set of default ACIs that get set when each role is created by the DSAME SDK. The default ACIs are stored in a global configuration attribute—the iplanet-am-admin-console-default-acis attribute. This attribute is defined in the iPlanetAMAdminConsole service XML profile, and can be configured by an administrator or customization engineer by using the amadmin tool, ldapmodify or through the DSAME console service pages.

Because the default behavior of the product is to dynamically create the above administrator roles when the corresponding entry type is created, the DSAME SDK depends on these default role permissions to be present when creating the entries. For example, when an organization is created, the DSAME SDK creates an Org Admin role and an Org Help Desk Admin role. After creating these roles, the SDK gets the default permissions (ACIs) from the iplanet-am-admin-console-dynamic-aci-list attribute and sets them in the specified entries. This allows customers to modify the default permissions for the dynamic roles. It is important to note that these default permissions are not types, they are, in fact, just defaults.

After the role is created, the ACIs for that role are stored in the role itself, so changing the default permissions in the iplanet-am-admin-console-dynamic-aci-list attribute after the role is created will not affect that role, but only affect roles created after the modification has been made.

If a modification to any role permission is desired, you must modify the iplanet-am-role-aci-list attribute for the role through the DSAME console or through Directory server Console. (The iplanet-am-role-aci-list attribute holds all the ACIs in string format for that role.)

The iplanet-am-admin-console-role-default-acis attribute are the permissions (ACIs) displayed in the role's Create window of DSAME console. If you want to add more default permissions, add them to the iplanet-am-admin-console-role-default-acis attribute.

When a role is created in DSAME, it will have the auxiliary class iplanet-am-managed-role with the following attribute:

iplanet-am-role-type

This will be one of the following three values:

  • 1 for top level admin

  • 2 for general admin

  • 3 for user

This attribute is used only by the DSAME console for display purposes. After authentication, the DSAME console gets the user's roles and checks the types of each role. If a user has no administrator roles, the User profile page will displays. If they have any admin type of roles, the DSAME console will make an DPStoreConnection.getTopLevelContainers() SDK call and start the user at the top-most view in the entry hierarchy. There is a catchall attribute iplanet-am-user-start-dn that can be set to override the starting point for the administrator. This attribute is needed because an administrator's desired starting point in the DSAME console user interface might be something other than what is dictated by the ACIs. This attribute can be set in conjunction with a role.

For example, if a group administrator happens to have read access to the top level organization, he or she might still want their starting point in the DSAME console to be the group they are managing. If the console went by the entries returned by the SDK based on ACIs, the admin would start at the top-level organization.

iplanet-am-role-description—The text description for the role. An administrator or user enters the description is entered through the user interface when creating a new role. The description for the dynamically-created roles is based on the names in the localization files.

iplanet-am-role-aci-description—The text description for the access permissions. The intent of this description is to describe what the ACIs for this role provide in an easy to understand format. This attribute can be set when creating the role. There is also a default description for the default ACIs that is used when roles are dynamically created or when a predefined permission is selected in the role creation pages of the DSAME console.

iplanet-am-role-aci-list—The list of ACIs that will be set when a role with this permission name is created through the DSAME console or by the SDK. The format of this attribute is the following:

permissionName | ACI Description | DN:ACI ## DN:ACI ## DN:ACI

permissionName—The name of the default permission

ACI Description—The readable (by people) description of the access these ACIs allow. The creator of these entries should assume that the reader of this description does not understand ACIs or even Directory server concepts.

DN:ACI—There may be any number of DN:ACI separated by the "##". The SDK will set each ACI in the DN entry. This format also supports tags which will be dynamically substituted when the role is created. Without these tags, the DN and ACI would be hard-coded to specific organizations in the DIT which would make them unusable as defaults.

For example, if you have a default set of ACIs for every Org Admin, you would not want to hardcode the organization name in the default ACIs for the Org Admin. The supported tags are ROLENAME, ORGANIZATION, GROUPNAME, and PCNAME. These tags will be substituted with the DN of the entry in the SDK create method when the corresponding entry type is created.

If there are duplicate ACIs within the default permissions, the SDK will not fail, but it will print a debug message (not an error message). This will be a common occurrence when macro ACIs are used.



Defining Policy Attributes in a Service


Policy attributes are a special type of dynamic attribute. They behave and follow the same basic design as Dynamic attributes, and function internally the same as dynamic attributes.

Describing an attribute as policy allows the DSAME console to distinguish between policy and dynamic attributes. The main difference between them is that policy attributes from one service can be used to create named policies under an organization. The named policies can then be assigned to roles or organizations.

With dynamic attributes, you can directly assign attributes from a service to an organization or role. There are no named service objects. In the DSAME console, there is a separate pulldown for policy management. This is where the organization administrator can define the named policy objects which can be later assigned to organizations and roles under the user management pulldown pages. For example, an organization administrator might define the following named policies: "Admin URL Access", "HR URL Access", "Contractor URL Access", and "Employee Access".

In the user management pages, these named policies can be assigned to roles or organizations. The administrator might assign the "Employee Access" policy to the organization so that all employees in the organization inherit the policy. Then the administrator might assign the "HR URL Access" policy to the "HR Role". This way, all users in HR will get those policies along with any policies from the organization level.

There are no default values supported for named policy objects. This means that administrators must create named policies from scratch in the DSAME console. When a new named policy is created,there are no defaults as in the service management pages.


Policy Attributes

Policy attributes provide a way to control access to resources, and to determine users' privileges to resources.


Note

The policy component in DSAME uses the configuration definition section in a service XML, but it creates the configurations through SMS APIs, not through XML files.



Administrators can assign policies to organizations or roles in DSAME console

In the DSAME console there is a separate pull-down for policy management. This is where the organization administrator defines the named policy objects which can be assigned later to organizations and roles under the User Management pulldown pages. For example, an organization administrator might define named policies called "Admin URL Access", "HR URL Access", "Contractor URL Access", and "Employee Access". In the User Management pages, an administrator could assign these named policies to roles or organizations. The administrator might do the following:

  1. Assign the "Employee Access" policy to the organization so that all employees in that organization inherit the policy.

  2. Assign the "HR URL Access" to the "HR Role".

    This way all users in HR will get those policies along with any policies from the organization level. When an administrator creates a new named policy, there are no defaults as in the Service Management pages. (There are no default values supported for named policy objects.)


Policy Service XML

In DSAME 5.0, the policy schema and default values should be defined by service developers in a service XML file. A sample policy schema definition is provided in the sampleMailService.xml provided in the DSAME product in the <dsame_root>/SUNWam/samples/admin/cli/sampleMailService. (See Section "Description of sampleMailService Files" on page 160 for some information and an example of how policy schema would be defined in a service XML file.

In DSAME 5.0, the policy.xml and policy.dtd are not public, thus should not be used to define policy schema and configuration data for a service.


Roles and Policy (Aggregation)

There is also an option for aggregation. For example, you could have three roles: Eng_role, Manager_role, and Pubs_role. They could all have different policies. When users possess multiple roles, the roles' privileges must be aggregated and returned to the user who possesses all those roles, so that the user gets an aggregation of that role's privileges.

If an administrator goes to a role, and enables a service for the role, he or she could pick any one of the services, configure different values for the service's attributes, submit the new configuration, and then gets a CoS template. An administrator could create multiple services, and then assign a particular user a role or multiple roles. When DSAME gets this entry, the way CoS and roles works is that the Directory server finds the role, sees that it has a CoS entry, and adds that to the attributes that get returned to the user. If there are any priority conflicts, it will look at the priorities for each one, and gets the priorities based on the CoS attributes for the group.

The service template is a set of attributes. For instance, if the highest priority was a set that was assigned to your role, that group of attributes is what you would get.



Overview of User Management Module


The User Management module is one of three modules, or components, within Services Management in DSAME 5.0. It is contained, along with the Policy Management module, the Service Management Module, under a grouping of services called Services Management.

The User Management component of DSAME provides interfaces for creating and managing user-related objects in Directory server. All of the user objects that DSAME can read, get and store are:

  • Organization

  • Sub-Organization

  • Organization Unit

  • People Container

  • Group

  • Role

  • User

The generic management functions that can be performed are create, delete, get, add, modify, and remove attributes on these objects, in addition to object-specific operations.

For information on when and how you can customize the ums.xml configuration file, refer to the section Section "Cases where Service Developers must Modify the ums.xml Configuration File" on page 130, and to the section on installing against a legacy DIT in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.



Adding User Attributes to DSAME


Any attribute that can be in the User entry can be managed through the User page in DSAME. To do this, you need to add the new user attribute to the amUser.xml file. Following is an example how to add the nsaccountlock attribute to the User profile.
Note

You can take this same approach to set many attributes for the user. In this case, you could also group the attributes into a service. If you grouped attributes into a service, you would need to create a new XML service file. However, the simplest way to add an attribute is just to extend the amUser.xml file.


Following are steps to do this:

  1. Add the following to /opt/SUNWam/web-apps/services/WEB-INF/config/xml/amUser.xml

    under the <SubSchema name="User"> element, add the following attribute schema definition:

Code Example 5-5    Attribute Schema Definition to Add to amUser.xml File
<AttributeSchema name=nsaccountlock
   type="single_choice"   
   syntax="string"
   any="filter|display"
   <ChoiceValues>
      <Value>true</Value>
      <Value>false</Value>
   </ChoiceValues>
</AttributeSchema>

  1. In the User schema definition section, add the following:

    <AttributeValuePair>
       <Attribute name="nsaccountlock"/>
       <Value>false</Value>
    </AttributeValuePair>

    This will be the default value.

  2. Also update the following file

    /opt/SUNWam/web-apps/services/WEB-INF/classes/amUser.properties

    with the new i18n tag "u13".

    u13=User Account Locked

    or whatever text you want displayed on the User Properties page in DSAME console.

  3. Then go to the Directory Server Console and remove the following OrganizationalUnit entry:

    ou=iPlanetAMUserService,ou=services,dc=sun,dc=com

    and its subentries.


    Note

    In the DSAME 5.0 release, you can use the amadmin CLI tool to remove a service schema; you can also remove a service schema by using Directory Console.


  4. Delete the user service using the amadmin tool.

    amadmin --runasdn "uid=amadmin,ou=people,o=iplanet.com,dc=sun,dc=com" --password 11111111 --deleteservice amUser.xml

    Then reload the user schema using the --schema option of amadmin:

    amadmin --runasdn "uid=amadmin,ou=people,o=iplanet.com,dc=sun,dc=com" --password 11111111 --schema amUser.xml

  5. Restart the amserver.

    Now when you go to the User profile in DSAME console you will be able to set this attribute and lock the user out.



Defining User Attributes in a Service

User attributes are attributes that will only be part of the user entry. User attributes are not inherited from the role, organization, or sub-organization levels. A user attribute is any attribute that is typically different for every user or for which it does not make sense to put into a role or organization. If you define an attribute as type "User", it cannot be set in a role or organization and then inherited by the users who possess that role or who are in that organization.

Examples of user type attributes are:

  • userid

  • employee number

  • passwords

There are no global defaults for User attributes.


User is considered a Service in DSAME

DSAME has several services, one of which is a User service. The User service is a group of attributes that are defined for and pertain only to a specific user.

A user attribute is any attribute that will show up on the User profile page.

There are no global defaults for User attribute types.



Customizing User Pages


To customize user pages in DSAME console, you would need to modify the amUser.xml file. This file is where user attributes are described. This file describes the User Service for DSAME.


Note

Any service can describe an attribute that is for a user only. This file is just the default placeholder for user attributes that are not tied to a particular service.


When displaying a user's attributes, the DSAME console gets all attributes from all services that are of SubSchema type User and displays them. For example, a few attributes from the sun-user object class are added so that a new service need not be created. You can just modify (or extend) the amUser service.


Extending what DSAME displays on the User Page in DSAME console

The User page and what it displays will vary, depending on what the administrator wants the users to see. By default, you can see a list of several attributes, which are retrieved from the amUser.xml file. Every attribute in the amUser.xml file that has an i18N display tag and the any attribute is set to display (that is, any=display) would display in DSAME console.

For example, you could have a hundred attributes in your profile, but if you only have seven attributes defined in a service XML file that have the any attribute set to display (any=display), you'll see just those seven attributes displayed in DSAME console. What that means is that if somebody adds their own auxiliary classes to the User service XML (amUser.xml), and they want them to display in DSAME console, they would have to update that XML file (amUser.xml). This is one way to extend what DSAME displays in the DSAME console.

The second option is to show the User attributes. In every service XML that is defined, if the attribute is specified to be User, such as in the mail service, then what the DSAME console does is display the User profile. If two of the attributes are not specified to display on the Create pages (with the any=display setting in the service XML file), it will display the attributes that are in the User profile, plus it will display the ones that are in all the other user service attributes, or tags. This provides the administrator with several options.

The DSAME console has a list of all the services and all the meta-data. When it gets all the attributes from the user profile (because it's CoS-related, it's getting them all in one call); it matches them and then it puts them into service categories. These are the attributes that are in the User XML (amUser.xml), which are attributes defined just for the user.

You could group all your attributes and then add them to the user and say, "these are the ones I want to display in DSAME console."


How the "any" Attribute can be used in Service XML Files

The any attribute and how it can used in service XML files is described in this section.

As a service developer, you not want to have administrators and users have to fill in all the fields to create a user. To specify which attributes will display in the Create, Properties, and Search pages in DSAME console, the "any" attribute can be specified for each attribute in a service XML file. For example, currently, in LDAP, you have object classes. There are mandatory attributes with which to create objects in Directory server. You can specify when you create a class that certain attributes are required, that is, the administrator must enter a value for that attribute in DSAME console.

Specifying the "any" attribute in a service XML file is a way for the service developer to specify what he or she wants to display on the Create page (and Properties and Search pages) in DSAME console when a user is created. If you have 75 attributes in your entry, you might not want to type in all 75 attribute values. You may just want to enter username and password. So by adding this the "display" keyword to your attribute (any=display), when the Create window displays, this attribute will display. So—uid, password, fullname, last name—those have required attribute types. As long as they're defined in the schema, you can just put "required" and they'll display on the Create page.

The "any" attribute can be set to:

  • required—attribute displays on Create page, and is a required attribute

  • optional—attribute displays on Create page, but it is not a required attribute

  • filter—attribute will display in the Filter pages

  • display—attribute will display in the Create page

If the "any" attribute is set to a value of "required," then it shows up on the Create (user) page. For example, when you create a user, the Create page shows up with a number of fields to fill in. DSAME gets those fields (attributes) from the User XML (amUser.xml) file, and if the any attribute has a value or string, and "any = required," it displays on the Create page.

The any attribute is typically used in the any User type attribute, for example, in the amUser.xml or some other service XML file in a user schema definition. You typically would only see the any attribute in a User schema definition for any user service, for example, a mail service. See the Code Example 5-6 for an example of the any attribute setting.

Code Example 5-6    Excerpt defining the any attribute in the amUser.xml File
<Dynamic>

    <AttributeSchema name="preferredlanguage"

type="single"

syntax="string"

any="display"

i18nKey="d1">

       <DefaultValues>

<Value>en</Value>

       </DefaultValues>

      </AttributeSchema>

    <AttributeSchema name="preferredtimezone"

type="single"

syntax="string"

any="display"

i18nKey="d2">

      </AttributeSchema>


The any attribute has four possible values:

  • any=required|optional|display|filter

The required and display can be specified together with a pipe symbol separating the two keywords (any=required|display), and the optional and display keywords can be specified together (any=optional|display).

The required and optional settings relate to the Create pages in DSAME console. If the any attribute is set to either required or optional, then when a user entry or organization, for example, is created, DSAME displays that attribute on the Create page. If the any attribute is set to required (any=required), an asterisk will display in that attribute's field, and a value must be entered for the object to be created.

If the any attribute is set to optional (any=optional), it will display on the Create page, but users are not required to enter a value; it's optional.

If the any attribute is set to display (any=display), then when the properties are display for the Create page, this attribute is displayed.

If the any attribute is set to filter (any=filter), when you go to the User page, and click Search, the attributes display for the filter. The any=filter setting lets service developers specify if this attribute should appear on this page. For example, if a service developer wanted to add employee_name, or manager_name to the default Filter page for the user, he/she would specify that attribute in the user service or any User schema definition in any service XML file as "any=filter". Then this attribute would display on the Filter page.

The any=display attribute type simply indicates whether DSAME should display that attribute or not (any=display), and whether the user must enter a value for the attribute (required), or if it is an optional attribute (optional), or whether that attribute should appear on the Filter page in DSAME console (filter).

The any attribute gives service developers some control over which attributes to display in the DSAME console. It is not necessary to display every attribute in all of the service XMLs on the DSAME console. Also, depending on the level of permissions you have, or whether the level of administrator you have access to may not allow you to see certain attributes on certain pages.

If you had an attribute that you didn't want users to see in the DSAME console, but it was still in their profile, you could the any attribute for that attribute to any=display. Or you could make it blank or empty (" "), and no attribute would display on the Create page.

In summary, the any attribute is useful if you want to extend the User page with additional attributes. Any time a service developer adds a new or custom service, he/she might be adding some new or modified objectclasses and attributes. In this case, he/she would probably want some of these new or modified attributes to appear on the User page. Use the any attribute in the service XML files to do this.


Extending the amEntrySpecific.xml File

These same rules apply for the amEntrySpecific.xml file for any of the DSAME abstract types, such as organization, organizational unit (ou), group, etc. This is the only other place you will see the any attributes used. The any attribute is used for creation and filter purposes, and it applies to any attribute in a User schema definition, either in the amUser.xml file or some other User schema definition in a service XML file.


Adding attributes Common to all Users to the User Service in DSAME

One way you can customize the User service in DSAME, for example, is to add any additional object classes with attributes to all user entries in the Directory server. This can be done through ldapmodify or through Directory Console.

For example, you might have an auxiliary object class with 10 attributes common to all user entries in their Directory server. To manage these attributes through DSAME they must be described in a service within DSAME. One option would be to add them to the iPlanetAMUserService (amUser.xml) service. This is the service within DSAME that, by default, includes many common attributes from the inetOrgPerson and inetUser object classes. This User service can be extended to include the attributes in the customer's object class or, alternatively, the customer might choose to create a new service to manage these attributes. Whether an existing service is extended or a new service is created, the attributes, after being imported would be manageable through the DSAME console.

It is important to understand that adding a service to DSAME enables DSAME to manage the attribute values from the DSAME console. It does not implement any behavior behind those attributes or dynamically generate any code to interpret the attributes. This means that DSAME can set and get the values; however, it is up to an external application to interpret or use these values. Continuing with the example above, if attributes common to all users were added, an administrator would be able to get or set those values or add them to roles or organizations. For example, one of the applications that would use DSAME might be a phonebook application that is reading those values from the Directory server. An administrator might create users, and set those new attributes through the DSAME console, but the phonebook application would be reading those attributes when querying for specific users.

Take note that in the DSAME console under Service Management there are several DSAME (internal) services shipped with the product. These services are managed in the same way as external services; the difference is that DSAME provides code implementations that use the service attributes. A good example of this is the DSAME URL Policy Agent service. This service defines three attributes that are used by the URL Policy Agent service (web agents) to check user access to URLs. The DSAME console allows the administrator to configure these attribute values, but the web agent is the external DSAME application using those attributes. The core DSAME features are each described and managed as any external service would be managed. You can view the service XML file that describes each DSAME service in the XML directory under /SUNWam/web-apps/services/WEB-INF/config/xml. This is a good place to start when describing or adding a service to DSAME.



Customizing Organization Pages


If customization engineers or service developers wanted to customize the organization pages, or pages for any of the other DSAME abstract types (such as organization units, people containers, static groups, filter groups, assigning dynamic groups, they would need to make modifications to the Entry-Specific service (specified by amEntrySpecific.xml).

The attributes in the amEntrySpecific.xml file are for console display purposes. This service (defined in the amEntrySpecific.xml file) is used by the DSAME console when customizing the display for specific DSAME abstract types, which are:

  • organization

  • container (organizational units)

  • people container

  • Static Group

  • Filtered Group

  • Assignable Dynamic Group

The DSAME types are manageable entities which are identified by the existence of DSAME marker object classes in directory entries. The marker object classes allow DSAME to manage most directory structures, regardless of the object classes and naming attributes deployed. For example, a directory may use only organizationUnits for their first level structure. By adding the DSAME Organization marker object class to these organizationalUnits, DSAME will manage them as DSAME organizations. Or user entries in the directory may contain only customer-specific object classes. By adding the DSAME User marker object classes, DSAME can manage these users. For more detailed information on the DSAME entry types and their marker object classes, refer to information on DSAME entry types and markers in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.

Each DSAME entry type will appear on the DSAME console in three places where this service is used:

  • create page

  • properties page

  • search page

Each DSAME entry can have its own subSchema in the amEntrySpecific.xml file. If the DSAME type does not appear in the XML, the defaults will be used for the type. The default means that only the name of the entry will appear on the Properties display, the Create window, and the Filter window in the DSAME console. For example, the Organization type has the following XML subSchema.

Code Example 5-7    SubSchema for Organization entry type in amEntrySpecific.xml
   <SubSchema name="Organization">
<AttributeSchema name="inetdomainstatus"
type="single_choice"
syntax="string"
any="optional|filter"
i18nKey="o2">
<ChoiceValues>
<ChoiceValue>Active</ChoiceValue>
<ChoiceValue>Inactive</ChoiceValue>
</ChoiceValues>
</AttributeSchema>
</SubSchema>


Purpose of amEntrySpecific.xml File

When an object of one of the above (abstract) types is displayed in the DSAME console, the XML (amEntrySpecific.xml) describes which attributes will display on the Properties page, Create page, and Search page, if applicable.

If your DIT had customized the OrgUnit, Group, Role, or People Container user objects, you would have to add or modify their schemas also in the amEntrySpecific.xml file.

Note that the User is not configured here but in its own amUser.xml.

All the attributes listed in the schema are displayed when the organization pages (or pages for some other DSAME abstract entry such as organizational unit, static group, filtered group, managed group, people container, and role) are displayed. If the attribute is not listed in the schema definition in the amEntrySpecific.xml file, the DSAME console will not display the attribute.


any Attribute

The any attribute can have two of the four possible values:

  • display, and

  • required, or

  • optional, and/or

  • filter

For example, required | filter or optional | filter can be specified.

The required and optional values tell the DSAME console whether the attribute should be on the create page. If its keyword is required, it must have a value or the DSAME console will not allow the creation to occur. The filter tells the console whether to use this attribute in the search page or organizations. For example, if you wanted both attributes to be displayed on the Organization page, both are required for creation, and only the attribute will be used in the search page.

The filter keyword tells the DSAME console whether to use this attribute on the Search page or on the Organization pages. In the example above, it is desired to have both attributes display on the organization page. Both are required for creation, and only the attribute will be used on the Search page.


Type Attribute

The type attribute may be one of string, string list, single_choice, multiple_choice, or boolean. The type attribute specifies the format of values that this attribute can have. This can be one of the following types:

  • string

  • string list

  • single choice

  • multiple choice, or

  • boolean

For example if the sun-org-city attribute can only be one of Concord, San Francisco, or Palo Alto, you would make this attribute a single choice and the cities above would be the choices. The DSAME console would display this as a list with only those cities.

If multiple cities were allowed, the attribute could be a multiple choice.

The purpose of this file is to display DSAME abstract entries, such as Organization pages (or organization unit, group, role, or people container). Typically, a service developer would be customizing the organization pages, however.

The DSAME console uses the data in this file for display purposes. Each DSAME abstract entry can have a schema definition in this XML file. For this example, you only need to modify the Organization schema. If a service developer or customization engineer had customized the OrgUnit, Group, Role or People Container in the DIT, he/she would have had to add or modify their schemas also.

Note that User is not configured here but in its own amUser.xml.

All the attributes listed in the subschema are displayed when the organization is displayed. If the attribute is not listed the console will not display the attribute.



Cases where Service Developers must Modify the ums.xml Configuration File


The ums.xml configuration file contains all the user (and service and policy) objects that are stored in Directory server. The ums.xml is called the DAI service in Directory server. Generally speaking, service developers or customization engineers will not need to know about or modify the ums.xml configuration file; only service developers or customization engineers with a good understanding of this file should make any modifications to it. Information on when and how to modify the ums.xml configuration file is covered in the section on installing against a legacy DIT in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.

The only cases where customization engineers or service developers will need to know about and modify this file are:

  • when adding new objectclasses to users or organizations.

  • if service developers do not want the default organizations or roles, and want to change them.

  • if service developers want to change the naming attribute for an attribute.



What DSAME Supports in the Service Registration DTD

DSAME 5.0 only supports a limited subset of elements and attributes from the sms.dtd (Services Management Service Document Type Definition). The sms.dtd should not be modified, as the XML parser uses this file exactly as is; this file is meant to be used as a guide when writing service XML files. Additionally, the sms.dtd enforces certain rules when writing service XML files to be used by DSAME. This section lists the elements and attributes that DSAME 5.0 supports.

In DSAME, there are five support schema types:

  • global

  • organization

  • dynamic

  • policy

  • user

In your service XMLs, service developers must describe the service attributes to be one of these types. For each schema type, you must define an attribute or attributes. The schema for each attribute can define the following attributes and keywords defined in this section:

  • name

  • syntax—The syntax attribute specifies the syntax of the attribute value. Currently supported syntaxes are:

    • boolean

    • string

    • password

    • number

    • any

    • i18NKey

    • DefaultValues element

    • ChoiceValue element

Each service also has three global attributes that are defined:

  • i18NFileName

  • i18nKey

  • optionally may have service objectclasses;

Within each of the schema attribute types (global, org, dynamic, policy, and user), you will define your attribute schema, and one or more attributes. For each attribute, you need to define the type, syntax, i18Nkey, default values or choice values, if it's a type of single or multiple choice, and possibly the "any" attribute.

Globally for the service, you need to define the name of the service, and the version (which should be the same). The i18NFileName attribute is used to pick up the properties and all its indexes, or keys; then the key itself for the name of the service (i18Nkey for the name of the service). Optionally, a service developer could define one global attribute that describes the LDAP object class. (This LDAP objectclass would only need to be specified when the attribute is of the type dynamic or policy. If the attribute is global or organization, then specifying the LDAP objectclass is optional; this is because the global and organization attributes are private data, and are not stored in Directory server as LDAP attributes.)

Code Example 5-8    Excerpt from sampleMailService.xml showing global attribute definitions
<ServicesConfiguration>

<Service name="sampleMailService" version="1.0">

<Schema

i18nFileName="sampleMailService"

i18nKey="iplanet-am-sample-mail-service-description">

   <Global>

<AttributeSchema name="serviceObjectClasses"

type="list"

syntax="string"

i18nKey="">

<DefaultValues>

<Value>iplanet-am-sample-mail-service</Value>

</DefaultValues>

</AttributeSchema>


The rest of the sms.dtd elements and attributes are reserved for future use by DSAME.


Service Schema Definitions Supported by DSAME 5.0

This section provides brief definitions of the schema attributes and elements in the sms.dtd that are supported by DSAME 5.0. Services that require their configuration information to be managed through the interfaces provided by the DSAME SDK and the DSAME console must organize this information using the DTD (sms.dtd) described in this chapter.


Note

Only a small percentage of the elements and attributes in the sms.dtd are supported by DSAME 5.0. This chapter provides some information on the elements and attributes used by DSAME 5.0.


The following attributes and elements in the sms.dtd are supported and used by DSAME 5.0:

  • i18nFileName which gives the name of the .properties file (for example, dpAuth.properties).

  • i18nKey which gives the I18N index key that describes the service for a given locale.

The element AttributeSchema defines the schema of a configuration parameter. Using the AttributeSchema element, service developers can define the XML schema for configuration parameters by having multiple AttributeSchema elements. The service registration DTD (sms.dtd) provides several attributes to describe the schema for the attribute:

  • name: specifies the name for the attribute (for example, mailQuota).

  • type: specifies the format of values that this attribute can have. Currently- supported formats are:

    • single which specifies that the attribute can have only a single value;

    • list which specifies that the attribute can have multiple values;

    • single_choice which specifies that the attribute can have a single choice that must be selected from a choice list;

    • multiple_choice which specifies that the attribute can have multiple values from which one choice must be selected from the choice list. The default value for type is list.

  • syntax: specifies the syntax of the attribute value. Currently-supported syntaxes are:

    • boolean

    • string

    • password

    • number

  • any: has four possible settings—required, optional, display, and filter. Used to determine how to display a user entry or organization or some other type of entry on the Create, Properties, and Search pages in DSAME console.

In addition to the above attributes for the element AttributeSchema, it supports the following elements:

  • DefaultValues: provides the default values for the configuration parameter.

  • ChoiceValues: provides the possible choice values for the configuration parameter if its type is either single_choice or multiple_choice.


    Note

    Custom pluggable authentication services that you can write and plug into DSAME will typically only use global and organization service attributes in their service XML files. Service XML files only need to be written and imported for custom pluggable authentication services if you have attribute/value pairs that you want to be manageable from DSAME console; otherwise, it is not necessary to write and import a service XML file. (See Chapter 2 "Pluggable Authentication SPI for detailed information on writing a custom pluggable authentication service and integrating it into DSAME.)



    Note

    Default values specified in the service schema section of a service XML file will display for that attribute or configuration parameter in DSAME console, which the administrator can then change when creating a service template.



Attributes and Elements that DSAME Supports

This section lists the elements and attributes that DSAME 5.0 supports and uses. Note that in DSAME 5.0, only a subset of the elements and attributes in the sms.dtd are supported. The rest are reserved for future use. These are all the attributes and elements that service developers and customization engineers can use when defining service XMLs.


Purpose of an XML DTD

The purpose of a DTD is to define the legal building blocks of an XML document. It defines the document structure with a list of legal elements. A DTD can be declared inline in your XML document, or as an external reference.

XML attributes are normally used to describe XML elements, or to provide additional information about elements.

The Services Management Services DTD is designed specifically for use with DSAME product, and other Sun service management products. It should not be altered; otherwise, DSAME service attributes may not be read and written correctly by iPlanet Directory server.


Where you can find Further Information on XML and DTDs

Here are a couple of sites that have information on XML and DTDs:

http://www.xml101.com

Additionally, there are several books and web site sources on XML (Extensible Markup Language) which explain standard XML terms, such as elements, attributes, and other XML keywords such as CDATA and NMTOKEN. These can be found by using any standard search engine.


Description of sms.dtd Elements and Attributes

The sms.dtd is a Document Type Definition that defines a set of rules that all service XML (Extensible Markup Language) file in DSAME must follow. It explains data structures that are used by all services in DSAME (whether internal to DSAME, that is, services that exist when you install DSAME; or external, that is, those services or applications that customers would integrate into DSAME).

A DTD (Document Type Definition) defines schema that will be used by services to define their configuration data. In other words, it's a sort of "schema for schema". The sms.dtd defines the schema that will be used by services to define their configuration data, and is specific to DSAME.


ServicesConfiguration Element

ServicesConfiguration is the root node for all services' configuration parameters and tasks in the entire XML document. You can describe and register multiple services in a single XML file. Within the ServicesConfiguration element you can define service schema for one or more services.

Code Example 5-9    ServicesConfiguration Element
<!ELEMENT ServicesConfiguration ( Service )+ >
<!ATTLIST ServicesConfiguration
   version       NMTOKEN       "1.0"


Schema Element

Before describing each attribute type, a schema element definition should be included in the service XML.

Code Example 5-10    Schema Element definition
<!-- Schema defines the schema for the configuration parameters of the service. The sub-elements provide configuration parameters' schema for the respective parameter grouping. The attributes provide information for I18N, that is, properties file name and the URL of the jar file which contains the properties file. -->

<!ELEMENT Schema ( Global?, Organization?, Dynamic?, Policy?, User? ) >

<!ATTLIST Schema i18nJarURL CDATA #IMPLIED

   i18nFileName CDATA #IMPLIED

%i18nIndex; >



Service Element

The Service element defines a service-specific task, configuration parameters' schema, and/or configuration data. Examples of services (or components) are Authentication, Session, Logging, User, URL Policy Agent, etc. (The word service and component are used interchangeably.) The attribute name gives the name of the product (can be a service, component, application, etc.) and version specifies the version of the product.


Service Name and Version Attribute List

For the Service element definition, you can define one or more schema, and 0 or more configurations. The attribute list gives the service name, and version.

Note that when writing a custom service, you should define only one service per XML file.

Code Example 5-11    Service Element Definition
<!ELEMENT Service ( Schema?, Configuration? ) >
<!--Name and version of the service -->
<!ATTLIST Service name NMTOKEN #REQUIRED
   version NMTOKEN #REQUIRED >

The attribute list (ATTLIST) defines the Service name and version. (See the Service name and version definitions in the excerpt from the SampleMailService.xml file in Code Example 5-14.) It defines the service's name and version of that service.

Code Example 5-12    Service Element Definition from sampleMailService.xml
<ServicesConfiguration>
<Service name="sampleMailService" version="1.0">
<Schema

The version number does not need to correspond to the version number of the product. For example, the product version could be DSAME 5.0, and the Service name and version could be "DSAME" and "2.0", respectively, for example. The service version specified in the sms.dtd and the product version do not necessarily correspond to each other.


Service Name Attribute

This is a required attribute; you must define this in a service XML.

The "Service name" attribute for the Service element defines the name of the service being defined. For example, in the sampleMailService.xml file, the service name is "sampleMailService".


i18nFileName Attribute

This is a required attribute; you must define this in a service XML.

The i18nFileName attribute defines the localization filename to be used; the i18nFileName is also called the localization .properties filename. In the sampleMailService.xml file, the i18nFileName attribute is defined as "sampleMailService". In the case of the sampleMailService, the i18nFileName is defined as sampleMailService.properties.


i18nKey Attribute

This is a required attribute; you must define this in a service XML.

The i18nKey attribute defines the index key, or the "localization key" which displays the service name. In the sampleMailService.xml file, the i18nKey attribute defines the service name that will display in the DSAME console— "iplanet-am-sample-mail-service-description".

When looking at a service XML file, you can see that the service name is iPlanet logging service. When looking at the service schema definition section for the logging service, you can see that each attribute description of an i18n description key. These i18nkey attributes are localization keys (for example, "a1", "a2", "a3", etc.), and correspond to actual fields in each service's properties files. These fields are picked up and displayed by the DSAME console or some administrative application, based on the locale for that platform. Every attribute must be displayed in a particular locale for that platform language, for example, American English, Japanese, German, etc. In the resource bundle .properties file for every service (for example, amAuthLDAP.properties and amLogging.properties files). You can look at the services' .properties file to get the name of the actual attribute as it will display in DSAME console. This key corresponds to the actual attribute that needs to be changed on the server.


i18NKey Attribute and i18NFileName Attribute

The i18N key is a localization key, or index key, that maps to the localization file to be used. i18N is the localization file, for example, i18NFileName for the user, for example, i18nFileName="amUser". The DSAME console retrieves an i18N key, for example, "u1", and opens the file amUser.properties, for example. See Code Example 5-13 for a sample i18NKey definition. Also, when adding new attributes, you need to define an i18N key. If there is no description or a blank (that is, " "), that tells the DSAME console not to display the attribute.

Code Example 5-13    Excerpt showing the i18NKey Attribute Definitions in sampleMailService.xml
<Dynamic>

<AttributeSchema name="iplanet-am-sample-mail-service-status"

type="single_choice"

syntax="string"

i18nKey="a1">

<ChoiceValues>

<ChoiceValue>Active</ChoiceValue>

<ChoiceValue>Inactive</ChoiceValue>

<ChoiceValue>Deleted</ChoiceValue>

</ChoiceValues>

<DefaultValues>

<Value>Active</Value>

</DefaultValues>

</AttributeSchema>


Note that the values you specify for the i18Nkey attributes in service XMLs determine the order in which the fields are displayed on a service page in DSAME console. To cause the attributes to display in alphabetical order, give the i18NKey attribute values "a1", "a2", and "b1" and "b2", and so forth. For example, if you add a new attribute and you want it to display at the top of the services page, make sure you give the i18NKey a value of "a1".

The i18n attribute points to a Java.properties file. Calls are made to the resource bundle and Java classes. It is defined in the class path, and then DSAME loads it. Depending on what locale is passed to it, DSAME will look in the right directory. Depending on what locale the customization engineer has set, the correct resource bundle is passed to it.

See Code Example 5-14 for an example of the i18N key and i18FileName attribute definitions in the sampleMailService.xml file.

Code Example 5-14    i18NKey and i18FileName Attribute Definitions in sampleMailService.xml File  
<ServicesConfiguration>

<Service name="sampleMailService" version="1.0">

<Schema

i18nFileName="sampleMailService"

i18nKey="iplanet-am-sample-mail-service-description">

   <Global>

<AttributeSchema name="serviceObjectClasses"

type="list"

syntax="string"

i18nKey="">

<DefaultValues>

<Value>iplanet-am-sample-mail-service</Value>

</DefaultValues>

</AttributeSchema>

   </Global>



Global Attributes

A service developer typically must define the following global attribute types in a service XML file:

  • name of service

  • version of service

  • i18NFileName

  • i18NKey

  • service objectclasses (optional)

These are tagged as global attributes in the service XML, but it is important to note that these attribute definitions apply to and describe the service itself.

In the sampleMailService.xml file, there is a global attribute schema defined as "serviceObjectClasses". In , the service object classes specified under that attribute schema's values are given to any new user that gets created in DSAME (and Directory server). These are the object classes for the sampleMailService, which are given to any new user that is created, and the value of the global attribute is iplanet.am.sample.mail.service which will be added to all every user entry that inherits the service attributes for the sampleMailService.

For dynamic and policy and user attributes, the serviceObjectClasses attribute schema definition, if used, must correspond to Directory server attributes. Unlike global and organization attributes, you must have an objectclass definition for dynamic, policy, and user attributes. (Defining the serviceObjectClasses schema attribute for global and organization is optional.) This means that you must define the name of that objectclass under this attribute serviceObjectClass. The reason behind this is that when your service is registered for an organization, when you go to create a user underneath that node, those objectclasses are automatically put into that user object for you. The three attribute types dynamic, policy, and user map one to one to their attributes in Directory server.

If adding a new service, a customization engineer must update the Directory server schema with any new objectclasses and attributes that the new service has, if they are not already in Directory server. (This is typically done through Directory Console, or by loading in the schema definition in the form of an .ldif file that contains the new object classes and attributes.)

Also, note that you can define multiple values for the attribute schema name serviceObjectClasses in a service XML file; for example, you could define multiple objectclass values in addition to iplanet-am-sample-mail-service.

For example, after a new service has been added to DSAME and Directory server, any new users that are created in DSAME will automatically get those new objectclasses and attributes; however, you must modify the already-existing users in the DIT so that they can use the new objectclasses and attributes. It does not matter whether a user belongs to that service or not; the objectclass is added. The user can be created through DSAME console or through amadmin.

Code Example 5-15    A Global Attribute Schema Definition in sampleMailService.xml
   <Global>
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
</DefaultValues>
</AttributeSchema>
   </Global>

There can be more than one global attribute schema definition in a service XML file. A global attribute schema definition could define port number, cache size, number of threads, or any attribute that applies across an entire DSAME configuration or instance, thus to all services and users for that DSAME installation.

Note that global (and organization) attributes are internal to DSAME, and should not be used in any custom or external services in DSAME 5.0, except in custom pluggable authentication services. Global and organization attribute data are stored in Directory server as blobs of data, but cannot be retrieved through LDAP commands in DSAME 5.0. (Global and organization attributes can be used in DSAME 5.0 in custom pluggable authentication modules, however,


Organization Attributes

Different organizations in a web hosting environment, for example, "coke" and "pepsi" would have different configuration data defined for each organization. In this scenario, a service developer would need to define different configuration data for each of the organizations. A typical organization attribute could define the location for log files.

An example of a custom service where you would use organization attributes would be a custom pluggable authentication service. In DSAME 5.0, the only custom service that can use organization and global attributes is a custom pluggable authentication service.

For example, a service developer might specify an authentication module such as an LDAP authentication service or a RADIUS authentication service as an organization attribute type in a service XML. Something like an authentication service would typically apply at an organization level.

Organization attributes can only be used when writing custom pluggable authentication services; they cannot be used by external services in DSAME 5.0. Global and organization attribute data are privately stored in Directory server as blobs of data, and are not retrieveable using LDAP commands.

The only attribute types that are stored as LDAP objects in Directory server are dynamic and policy and user. The global and organization attribute types could also be stored in a flat file implementation, as they are not stored in Directory server as LDAP entries.)


Dynamic Attributes

The dynamic attribute type can be used for any attribute that should be assigned to roles or organizations, or inherited by users, that is, any attribute that is applicable to all user objects, with respect to the service. These attributes are usually implemented as Class of Service, which is functionality provided by iDS 5.0. Examples of dynamic attributes would be status attributes, mail address, etc.

Typical dynamic attributes would be session attributes; for example, a dynamic attribute defined in a mail service would get picked up by all users that use that mail service. And, based on the role that a particular user may possess, they would pick up these new attribute/values.

Dynamic attributes use the Directory Server CoS and roles feature. (See the Directory server 5.0 documentation on advanced entry management for details on how Class of Service works.)


Policy Elements

Policy element types are intended to provide a group of actions (or privileges) that are specific to the service. Examples of actions are canForwardEmailAddress, canChangeSalaryInformation, etc. The schema of the configuration parameters is provided by AttributeSchema. The element ResourceName specifies if the service has resources associated with it, for example, URLs in the case of URL Policy Agent service.

Code Example 5-16    Excerpt from amPolicy.xml defining a policy element
<ServicesConfiguration>

<Service name="iPlanetPolicyService" version="5.0">

   <Schema>

    <Organization>

      <SubSchema name="Policies">

       <SubSchema name="NamedPolicy"

         inheritance="multiple">

         <AttributeSchema

          name="xmlpolicy"

          type="single"

          syntax="string" />

       </SubSchema>

      </SubSchema>

      <SubSchema name="Resources">

       <SubSchema name="ServiceType"

         inheritance="multiple">

         <AttributeSchema

          name="xmlresources"

          type="single"

          syntax="string" />

       </SubSchema>

      </SubSchema>


You can create a policy, delete a policy, and assign a policy to roles by using the amadmin CLI tool. Policy schema definitions in sms.dtd use Class of Service (CoS).

Dynamic attributes are typically used for roles. All users belonging to a particular role will inherit all the attributes associated with that role. Every time DSAME goes to get a user object from the Directory server, if that user is part of a particular role defined as a "dynamic" attribute, that user inherits all the attributes associated with that role that he/she belongs to. By default, the user gets all these objectclasses and attributes.


User attributes

A user attribute type is for attributes that will be physically present in the user entry. User attributes are not inherited by roles or organizations. Examples of User attributes are password and employee ID.


Global Element, AttributeSchema and SubSchema Sub-elements

You can specify a Global element, which has two sub-element definitions— AttributeSchema and SubSchema, for which you can specify 0 or more definitions.

Code Example 5-17    Global Element Definition in sms.dtd
<!-- Global element provides grouping of configuration parameters that are globally applicable to all instances of its service. In the case of services that are grouped, these configuration parameters are global to that group. The schema of the configuration parameters is provided by AttributeSchema, and if there is any necessity to sub-group additional configuration parameters, they can be grouped using the SubSchema element. -->

<!ELEMENT Global ( AttributeSchema*, SubSchema* ) >



Attribute Schema Sub-Element

AttributeSchema sub-elements enable a service developer to define a specific attribute schema, or configuration parameter. See Code Example 5-18.

Code Example 5-18    AttributeSchema Element Definition (with Sub-Elements defined)
<!-- AttributeSchema defines a single configuration parameter for a service. The attribute name gives the name for the configurable parameter, type specifies whether the parameter is single-valued, multi-valued, single-valued choice or multi-valued choice type; syntax defines whether the parameter is boolean, string, numeric or dn; rangeStart and rangeEnd provide the starting and ending values for attribute syntax decimal_range and number range, respectively; and any provides means for service developers to add service-specific information. The elements IsOptional, IsServiceIdentifier, IsStatusAttribute represent whether the attribute is optional, a service identifier (CoS specifier) or status attribute, respectievely. The elements DefaultValues provides the default values for the parameter and ChoiceValues provides the possible values for the parameter if it is of choice type. The element Condition, if present, specifies boolean operations, which determine if the attribute is valid based on the current configuration data. If multiple Condition elements are present, it is sufficient if at least one of them satisfy the requirement (this provides OR implementation). -->

<!ELEMENT AttributeSchema (IsOptional?, IsServiceIdentifier?, IsStatusAttribute?,

   ChoiceValues?, BooleanValues?, DefaultValues?) >

<!ATTLIST AttributeSchema name NMTOKEN #REQUIRED

   type ( single | list | single_choice | multiple_choice ) "list"

   syntax ( boolean | string | password "string"

   CoSQualifier   ( default | override |

          | merge-schemes )      "default"

   rangeStart CDATA #IMPLIED

   rangeEnd CDATA #IMPLIED

   any CDATA #IMPLIED

   %i18nIndex; >

For the syntax attribute, the password type will encrypt and decrypt when stored or retrieved in Directory server. Because encryption is private in DSAME 5.0, the syntax attribute specified as password should only be used for DSAME internal services, and should not be used by external services. In DSAME 5.0, this syntax attribute keyword should only be used for custom pluggable authentication services.

Only the syntax types of boolean, string, and password are enforced in DSAME 5.0; all other syntax types (such as dn, email, url, numeric, percent, number, decimal_number, number_range, and decimal_range) are treated as strings. For example, if you put in a number as a string, DSAME will accept it.

Note that the CoSQualifier operationalal keyword is not supported in DSAME 5.0.


Service Sub-Schema Element

The service sub-schema element is only used in the amEntrySpecific.xml file in DSAME 5.0. This sub-schema element is private in DSAME 5.0, thus should not be used in any external service XML files in DSAME 5.0.

Service sub-schema can specify a subschema, for example, global information. It could define multiple sub-schemas, such as for a particular application that is defined. For example, logging for a Calendar application could be a separate sub-schema. Each application could therefore define its own way of logging. A netmail application could define a sub-schema, where there could be multiple instances of subschema, and define what attributes that sub-schema should use. For example, for different logging levels, a customization engineer could define choice values for different logging levels. For logging type, you could also define some choice values, for example, to specify output that goes to a file, JDBC, or some other LDAP output mechanism.

The attribute multiple_choice represents a list of choice values. The choice values could represent multiple values, so that if the attribute values do not contain multiple choice values, then the SMS parsing would fail.


AttributeSchema Element, ChoiceValues, BooleanValues, and DefaultValues Sub-elements

The fourth, fifth and sixth sub-elements are ChoiceValues, BooleanValues, and DefaultValues. These are elements for which specific attributes can have either a multiple choice list of values from which the user can choose several values, a Yes/No (boolean) list to choose from, and some default values from which to choose. The attributes and values specified generate actual values that will appear on the DSAME console. See the amAuth.xml file for examples of these element types defined in a DSAME service XML.


AttributeSchema Attribute, name Attribute

The attribute schema defines the attribute schema name, which is NMTOKEN. The AttributeSchema name attribute is required. This attribute schema name specifies the name of the attribute, for example, port_number or logfile_name, for the configuration data.

Code Example 5-19    Excerpt from sampleMailService.xml File showing AttributeSchema name specification
<AttributeSchema name="iplanet-am-sample-mail-service-status"

type="single_choice"

syntax="string"

i18nKey="a1">

<ChoiceValues>

<ChoiceValue>Active</ChoiceValue>

<ChoiceValue>Inactive</ChoiceValue>

<ChoiceValue>Deleted</ChoiceValue>

</ChoiceValues>

<DefaultValues>

<Value>Active</Value>

</DefaultValues>



AttributeSchema Element, Type Attribute

The attribute type can be a single attribute, a list of attributes, a single_choice attribute, or a multiple_choice list. In Code Example 5-19, note that type is specified as single_choice, and the choice values are specified as active, inactivate, and deleted. Given this service schema and configuration data specification in the service XML file, the administrator or user must then choose one of those values for the "iplanet-am-sample-mail-service-status" on the DSAME console.

If the attribute is of the type multiple_choice, then the administrator or user can pick multiple choices (more than one) on the DSAME console for that attribute.

For the type attribute, you can specify different keywords: single, which specifies that the user can only specify one value; specifying list lets the user choose from a list of values; single_choice allows the user to pick one choice from a list of values; multiple_choice allows the user to pick several choices from a multiple choice list.


AttributeSchema Element, Syntax Attribute

For the syntax attribute, if boolean is specified, users can pick between (true/false) for that attribute in the DSAME console.

The syntax attribute lets you specify from among a list of 12 keywords:


Syntax Attribute, boolean value

Specifies that user or administrator must select True/False for the attribute.

Code Example 5-20    Excerpt from sampleMailService.xml showing boolean syntax specification
<ActionSchema name="iplanet-am-sample-mail-can-save-address-book-on-server"
type="single"
syntax="boolean"
i18nKey="p3">
<DefaultValues>
<Value>false</Value>
</DefaultValues>
</ActionSchema>


Syntax Attribute, string value

Specifies that user can specify any string value for that attribute.

Code Example 5-21    Excerpt from sampleMailService.xml showing syntax attribute with string value  
<AttributeSchema name="iplanet-am-sample-mail-sentmessages-folder"

type="single"

syntax="string"

i18nKey="a3">

<DefaultValues>

<Value>MailSent</Value>

</DefaultValues>

</AttributeSchema>



AttributeSchema syntax Attribute, password value

Specifies that user must enter a password, which will be encrypted.

Code Example 5-22    amAuthLDAP.xml showing syntax attribute with value of password
<AttributeSchema name="iplanet-am-auth-ldap-bind-passwd"

type="single"

syntax="password"

i18nKey="a4">

       <DefaultValues>

<Value>AQAAKh7ai3zuzP8VryBzcPnXdRA9ukTY2gX6</Value>
       </DefaultValues>
</AttributeSchema>


AttributeSchema Element, ChoiceValues Sub-element

If the ChoiceValues sub-element is defined in the AttributeSchema, then it is valid, provided the type attribute is specified as either single_choice or multiple_choice. The administrator or user must choose either a single choice or from a multiple choice list for that attribute in the DSAME console.

Code Example 5-23    Excerpt from sampleMailService.xml showing type attribute with single_choice value
<AttributeSchema name="iplanet-am-sample-mail-service-status"

type="single_choice"

syntax="string"

i18nKey="a1">

<ChoiceValues>

<ChoiceValue>Active</ChoiceValue>

<ChoiceValue>Inactive</ChoiceValue>

<ChoiceValue>Deleted</ChoiceValue>

</ChoiceValues>



AttributeSchema Element, syntax Attribute, boolean value

If the syntax attribute is specified as boolean, then the administrator or user must select either True/False or Yes/No for that attribute in the DSAME console. In the Code Example 5-24, note that the syntax attribute is specified with a "boolean" value.

Code Example 5-24    Attribute Schema Element Specification with boolean syntax specified  
<AttributeSchema name="iplanet-am-auth-ldap-ssl-enabled"

type="single"

syntax="boolean"

i18nKey="a8">

       <DefaultValues>

<Value>false</Value>

       </DefaultValues>

Note that the default values specified in the AttributeSchema element definitions in the service XML files are the values that will display in the DSAME console for each attribute specified. In the Code Example 5-24, for example, on the LDAP Authentication service page, the "Enable SSL to LDAP Server" field (as specified in the corresponding localization .properties file (amAuthLDAP.properties) will give a default value of false. The administrator can change this value when creating a new service template with different values, if desired.


AttributeSchema Element, CoSQualifier Attribute

There are different values that a service developer can specify for CoSQualifier attributes:

  • default

  • override

  • merge-schemes

If the default value is specified, then the default value for the CoSQualifier attribute indicates that if there are two conflicting CoSQualifier attributes assigned to the same user object, the one with the lowest priority takes precedence. The lowest number, or 0, has the highest priority, or takes precedence.

If the override value is specified for the CoSQualifier attribute, then CoS overrides the user value. (The default behavior is for the user entry value to override the value for CoS.)

The operational value is not supported in DSAME 5.0.

If the merge-schemes value is specified, if there are two CoS templates assigned to the same user, then the CoS templates get merged so that the values get added together; then the user gets an aggregation of the CoS templates, or a union of them.

For example, if there is an attribute "A" with a value of "10" in one template, and another template "B" has a value of 20, the user would get both values 10 and 20 for the attribute "A".


AttributeSchema Element, any Attribute

Specifies a wildcard that can be used by services to declare additional configuration information. All the attributes listed in the subschema are displayed when the organization is displayed. If the attribute is not listed, the DSAME console will not display the attribute. For more information on the "any" attribute, see Section "How the "any" Attribute can be used in Service XML Files" on page 122.

The any attribute can have four possible values:

  • display, and

  • required, or

  • optional, and/or

  • filter

The required and optional keywords tell the console whether the attribute should be on the Create page. If its keyword is required, it must have a value or the DSAME console will not allow the create to occur. The filter keyword tells the DSAME console whether to use this attribute on the Search page or on the organization pages.


Organization Element

Organization element is used to specify configuration parameters for things like an organization's authentication. You can specify AttributeSchema and SubSchema elements.

Code Example 5-25    Organization Element in sms.dtd  
<!-- Organization element provides a grouping of configuration parameters that can be configured differently for various organizations. Examples are parameters like organization's authentication mechanisms, logging information, etc. The schema of the configuration parameters is provided by AttributeSchema and if there is any necessity to sub-group additional configuration parameters they can be grouped using the SubSchema element. -->

<!ELEMENT Organization ( AttributeSchema*, SubSchema* ) >



Dynamic Element

Lets service developer provide a grouping of configuration parameters that all users would inherit. Dynamic elements use CoS (Class of Service) as implemented by iDS 5.1. Examples of dynamic configuration parameters, or attributes, are status attributes or mail address, etc.

Code Example 5-26    amSession.xml File showing some attributes specified as Dynamic  
<Dynamic>

<AttributeSchema name="iplanet-am-session-max-session-time"

type="single"

syntax="number"

i18nKey="a1">

       <DefaultValues>

         <Value>120</Value>

       </DefaultValues>

</AttributeSchema>

<AttributeSchema name="iplanet-am-session-max-idle-time"

type="single"

syntax="number"

i18nKey="a2">

       <DefaultValues>

<Value>30</Value>

       </DefaultValues>



Policy Element

The Policy element lets service developer specify policy privileges or action names (with ActionSchema element). Examples of actions (or privileges) are canForwardEmailAddress, or can Change SalaryInformation. Privileges are get, post, and put. The element Resource Name specifies if the service has resources associated with it, for example, URLs in the case of the URL Policy Agent service.

Code Example 5-27    Policy element  
<!-- Policy element provides grouping of actions (or privileges) that are specific to the service. Examples of actions are canForwardEmailAddress, canChangeSalaryInformation, etc. The schema of the configuration parameters is provided by AttributeSchema. The element HasResourceNames specifies if the service has resources associated with it, for example, URLs in the case of Web Agent Service. -->

<!ELEMENT Policy ( ActionSchema* ) >


User Element

The User element lets service developer specify a group of configuration parameters that are applicable to user objects, only, with respect to the service. Examples are things specific only to a particular user, such as social security number, email address, etc. The User element uses the AttributeSchema sub-element, but does not use the SubSchema element.

Code Example 5-28    Excerpts from amUser.xml showing User Attributes specified  
<User>
<AttributeSchema name="uid"
type="single"
syntax="string"
any="required|filter"
i18nKey="u1">
      </AttributeSchema>
<AttributeSchema name="givenname"
type="single"
syntax="string"
any="optional|filter|display"
i18nKey="u2">
      </AttributeSchema>
.
.
.
       </DefaultValues>
</AttributeSchema>
</User>



Policy Management Module


The Policy Management module is one of three modules (along with User Management and Service Management module) that comprise the Management Services.


Overview of Some Policy Concepts and Terms in DSAME

Policy management deals with creating policies for services and how they are applied to a role or an organization.


Policy Schema

Policy schema is a set of all valid privileges and possibly optional default values for each of the privileges in the set. Policy schema can also contain information about the service itself. Each service that enforces policy must have a policy schema defined for it.


Named Policy and Assigned Policy

Policy constitutes a set of one or more pairs of {privileges, privilege settings}. For example, {mailboxQuota, 100MB} is a policy. {allowURLList, "*.red.iplanet.com, *.eng.sun.com"} is another policy. When a user or administrator creates a policy on the Policy page, that is called a "named policy".

Policy is the result of changing or setting the default values for privileges in the Policy schema. Administrators or service developers of DSAME use the policy schema to create policy for the relevant service by modifying any default values for the privileges in the policy schema and applying the resulting policy to a role, a user, an organization or an organizationalUnit. When a user or administrator takes that named policy, and assigns it to an organization or a role, then it can be called an "assigned policy".

Policies are unlike service schema; there are no named service objects. However, there are named policy objects.

From the same policy schema, the administrator can generate different policies to apply at different levels, such as role, user, organization, etc. Policy schemas can be viewed as metadata for the privileges of any given service. Using policy schemas, an administrator knows the valid set of privileges for any given service.

For example, you could compare the policy schema with the schemas in the XML, LDAP, and RDBMS worlds. Before you create an XML document, you define the XML schema. Before you create relational tables, you define the database schema. Before you create LDAP entries, you define the LDAP schema for DIT entries. Similarly, before you create policies, you need to create the Policy schema for the service.

For example, a Policy schema definition is shown in the amWebAgent.xml file in Code Example 5-29.

Code Example 5-29    Excerpt showing policy schema definition in amWebAgent.xml File
<Policy>
<ActionSchema name="permission"
type="single_choice"
cosQualifier="merge-schemes"
i18nKey="p1">
<ActionValue i18nKey="a1">
<Value>iplanet-am-web-agent-access-allow-list</Value>
<ResourceName/>
</ActionValue>
<ActionValue i18nKey="a2">
<Value>iplanet-am-web-agent-access-deny-list</Value>
<ResourceName/>
</ActionValue>
<ActionValue i18nKey="a3">
<Value>iplanet-am-web-agent-access-not-enforced-list</Value>
<ResourceName/>
</ActionValue>
</ActionSchema>
</Policy>
</Schema>
</Service>
</ServicesConfiguration>

The policy schema elements and attributes are not public in DSAME 5.0. However, note that in the DSAME 5.0 release, no external services can define and use policy schema definitions. So, an example from the amWebAgent.xml file is included here to provide some overview information on how to define policy schema.

Note that there is a difference between a Policy schema and a policy. Policy schema must declare all the valid privileges (or attributes) for the service. Policy need not declare all the valid privileges.


Scoping of Policies
Because policies for any service can be associated at the role, organizational Unit (ou) and/or organization levels, there could be cases when there will be conflicting policies for the specified service for a given user. Therefore, priority levels are associated with policies. Policies with higher priority take precedence over templates with lower priority. If conflicting policies have the same priority, the scoping results will be undefined.



Adding a Custom Service


After installing DSAME, you can add new, or custom, services to it later. However, you must add the new objectclasses and attributes manually to Directory server, by using ldapmodify or adding the new objectclasses and attributes through the Directory Console.

Note that in DSAME 5.0, you are limited to writing custom pluggable authentication services (which must use only the global and organization attributes in their schema definitions), and external services (other than custom pluggable authentication services) which must use only the dynamic and user attributes. LDAP can be used to retrieve data from the dynamic and user attributes in the user entry. In the case of the custom pluggable authentication service, there are methods in the pluggable authentication SPI that allow the retrieving of organization-based data.

So if you define a custom application or service (other than a pluggable authentication service) such as a phonebook application which has dynamic and user attributes defined in its schema, a service developer could import this custom service into DSAME using the amadmin CLI tool, configure the service in DSAME console, assign the service to an organization or a role, and then the phonebook application would use LDAP directly to read user attributes.

Following are some things to keep in mind when adding a new service:

  • If a customer wants to add a new service, he/she may need to modify a schema definition in the ums.xml file, and then may need to modify a couple of other files (amUser.xml and/or amEntrySpecific.xml file). If you want to add an additional service that was not there are installation time, then you need to just add the objectclasses and attributes to the ums.xml file to enable user creation. (Refer to the Section "Cases where Service Developers must Modify the ums.xml Configuration File" on page 130 for some information. Also see the iPlanet Directory Server Access Management Edition Installation and Configuration Guide for information on modifying the ums.xml configuration file when installing against a legacy DIT.

  • The User Management Services component in DSAME is considered a service. Default attribute/value pairs are provided for all of the user management services attributes in the ums.xml and umsCompliant.xml files. These are loaded into the Directory server when DSAME is installed.

  • Whenever a customer adds a new service or modifies an attribute, the ums.xml file must be modified and reloaded into Directory server.

  • When a customer installs the the DSAME product, the ums.xml schema and configuration data gets saved in the Directory server. If DSAME were to be un-installed, then the user management services schema and configuration information previously stored in Directory server would not get un-installed. If you were to reinstall DSAME, the user management services components would already be in the Directory server.

  • Whenever you reinstall the DSAME product, then the ums.xml file gets saved in the Directory server. The ums.xml file is saved in the Directory Server Console as the DAI service.

  • Once the ums.xml configuration file (called DAI service in the Directory server) has been loaded at installation time, it can only be modified using Directory server Console. You cannot reimport using the amadmin CLI tool.

  • When adding a service (such as sampleMailService.xml), you must update the DSAME console hierarchy service attribute to get it to display in the service tree. For information on updating the service hierarchy attribute, see Section "Add the sampleMailService to the Service Hierarchy" on page 206.)

If creating a custom service, a service developer or customization engineer would typically do the following:


High Level Flow for Creating and Registering Services

Following is a set of high level steps to create, register, and activate services:


Note

You can customize the existing internal DSAME services by adding new service attributes, modifying existing attributes, or you could create new services to work with DSAME.


  1. Write the custom service or application, for example, a Calendar application or an authentication service.

    (For specific information on creating custom pluggable authentication modules, see the Pluggable Authentication chapter. For specific information on creating a customized single sign-on solution to work with your existing services and applications, see the Single Sign-On chapter.)

  2. First create the service XML file for the service, which must conform to the DTD (sms.dtd). See Section "Attributes and Elements that DSAME Supports" on page 134 more information on the DSAME service management services DTD (sms.dtd).

  3. Update the amEntrySpecific.xml file, if necessary, for any abstract DSAME entries that you want to be displayed on the DSAME console's Create, Properties, or Search pages. (See Section "Attributes and Elements that DSAME Supports" on page 134 for information.)

  4. Update the amUser.xml file, if necessary. (See Section "Attributes and Elements that DSAME Supports" on page 134 for information.)

  5. Use Directory Console to add any new or modified schema (objectclasses or attributes) to Directory server so that DSAME can manage those new attributes. To do this, you could use either ldapmodify to update the Directory server schema, or modify the .ldif file directly.

  6. Make a copy of one of the resource bundle .properties files, for example, amAuthLDAP.properties, and modify it for your custom application or service. It should be located in the classes subdirectory. (See the Pluggable Authentication SPI or Single Sign-On chapters, respectively, for information on creating and integrating custom authentication and single sign-on solutions.)

  7. Copy the new or modified .properties file for your service into the following directory:

    dsame_root/web-apps/services/WEB-INF/classes

    (For more details on loading and registering services, see Section "Guidelines for Loading Services into DSAME" on page 198.)

  8. Import the service XML file into DSAME by using the amadmin CLI tool. After loading or importing a service XML into DSAME, all the services are loaded into a separate branch in iDS (under the ou=services branch).

  9. Update the DSAME service hierarchy attribute. (See Section "Add the sampleMailService to the Service Hierarchy" on page 206 for information on how to do this.)

  10. After you have imported or loaded the service(s) into DSAME, each organization can then register the service through the DSAME console. You can do this by going to the organization, selecting the service, clicking Add, then select the service that you want to register, then click Submit.

    The service is now registered in DSAME. Administrators can then create different service templates for role, sub-organizations, etc. through the DSAME console.

  11. Activate the service in DSAME console. (Alternatively, you can activate the service by importing the activateRequests.xml file by using the amadmin tool.)

For more detailed information on importing, registering, and activating service XML files into DSAME, see Chapter 6 "Using the Command Line Interface.


Some Things to Consider When Creating a New Service

For example, say you want to define a custom authentication service. You would need to define the service XML file for the custom authentication application or service per the sms.dtd. The things that the authentication service typically would need are logging, i18n information, and session information. Each one of these (logging, session, and authentication) is a service. They must define what each service will need, what all the attributes are, and what service configuration the application will need.

For example, logging contains a subset of these values, and could contain maximum log size file, location of log file, etc. The customer would need to define their schema based on schema format. One of the attributes they would need to define is where the log file will be stored, and similarly to define another service template for authentication. This information, when uploaded into DSAME, is passed to the SMS APIs, and the SMS APIs uploads the information into iDS.

The default values for each service attribute defined in the schema should be included within each schema definition. The default values, along with the schema definition, can also be referred to as the "configuration data".

At the customer site, an administrator could change the default values set in the XML files to new values, then create a new service template that uses those new values. For example, say you wanted to change your log file location to another location. An administrator or user could do this in the DSAME console, then save the new service template, and then assign it to an organization or role.

In DSAME 5.0, you cannot create Directory server schema dynamically through the amadmin CLI tool. You must always create or extend the Directory server (LDAP) schema by using the ldapmodify command for each service being created in DSAME (see the section on sampleMailService example), or by creating an .ldif file in the Configuration/Schema page in Directory Server Console.

After a service has been created, registered and activated for an organization, if a new user is added to that organization, it automatically inherits all the organization's CoS/template values for the global and policy attributes of the service (for example, through a role association).

The SDK adds the object class for the registered services to the user entry when it is created. The object class is defined in the service XML file. Note this only happens if the user is created through the SDK.

On the other hand, if a new service is instantiated, existing users for the organization do not inherit the attribute values for that service.

If services are added after the user is added, the user entries must be updated some other way (for example, through using the ldapmodify or by creating or modifying an .ldif file in Configuration/Schema page in Directory Server Console. The SDK will not update them if services are added after the user has been added.

The solution is to add the objectclass or attributes of the new service to each existing user through an ldapmodify command (as you would do when using the sampleMailService example), or by creating or modifying an.ldif file through the Config/Schema page in Directory Server Console. Alternatively, you could use the migration scripts provided in DSAME 5.0 to update the user objects in the DIT with the new objectclasses and attributes.) For information, see the section on migration scripts in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.)

You do not need to restart the LDAP server when extending the schema to add or modify users/services/organizations/roles, either directly through the .ldif file or Directory Server Console, or by using the amadmin CLI tool.

For new services being imported to DSAME, you need to restart the amserver to add any i18nKey resource bundles (if required) to its classpath.



Description of sampleMailService Files


This section provides a description of the following sample mail service files that are provided with the DSAME 5.0 product:

  • sampleMailService.ldif

  • sampleMailService.xml

  • sampleMailService.properties

The files are located in the <dsame_root>/samples/sampleMailService directory in the DSAME product. These sample files are provided so that you can use them as guidelines when creating your own custom services and applications.

There are several sampleMailServices files provided—an .ldif file to show some sample objectclasses and attributes to add to Directory server; an .xml file to show how a sample service could be written; and a sample .properties file to show how localization keys point to the the actual fields that display on DSAME console would be created.

In , the iplanet-am-sample-mail-service-status attribute is specified as a dynamic attribute, with a type of "single_choice", a syntax of "string", a list of choice values (Active, Inactive, and Deleted), and a default value of Active. On the DSAME console, after this service is loaded using amadmin, users and administrators will see this list of choice values for the iplanet-am-sample-mail-service-status attribute, and the default value of Active. The i18nKey value of "a1" points to an actual field defined in the resource bundle .properties file for the service. (In this example, the file would be sampleMailService.properties). The value for the "a1" definition in the sampleMailService.properties file is the actual field that displays for the iplanet-am-sample-mail-service-status attribute. In this case, the "a1" index key, or localization key, is "Mail Status", which is the field that displays for the iplanet-am-sample-mail-service-status attribute on the sampleMailService service page in DSAME console.

Excerpts of the sampleMailService sample files are given in this section.


sampleMailServiceSchema.ldif File

Typically, the customization engineer or deployment engineer will need to modify the necessary .ldif file or update the objectclasses and attributes in iDS Console directly before loading the modified or created service XML.

Following is the sampleMailServiceSchema.ldif file, which is located in the <dsame_root>/samples/cli/sampleMailService directory. It is provided so that you can use it as a sample, to create the LDAP schema for a service. You would typically need to extend the schema first by using the .ldif file as input to the ldapmodify command.


Note

If Directory server already knows about the objectclasses and attributes that are in your service, you do not need to update Directory server. If any of your service or application's objectclasses and attributes are not already up-to-date in Directory server, then you must extend the schema, either by modifying the .ldif file, or by updating the schema manually in Directory Console directory.


This is an example of an .ldif file, which a customization engineer could create, either manually, or by adding any new schema objects (objectclasses and attributes) by using Directory Console, then generating an .ldif file by using the db2ldif command. Another option is to load the .ldif file, with the new objectclasses and attributes (for a new service, or a modified service, for example) into DSAME and Directory server by using ldapmodify to modify the existing iDS schema.

Refer to the Directory server 5.0 documentation for specifics on using ldapmodify and how to add objectclasses and attributes to the Directory server.

Code Example 5-30    sampleMailServiceSchema.ldif File
dn: cn=schema
changetype:modify
add:attributeTypes
attributeTypes: ( iplanet-am-sample-mail-service-status-oid NAME 'iplanet-am-sample-mail-service-status' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-root-folder-oid NAME 'iplanet-am-sample-mail-root-folder' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-sentmessages-folder-oid NAME 'iplanet-am-sample-mail-sentmessages-folder' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-indent-prefix-oid NAME 'iplanet-am-sample-mail-indent-prefix' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-initial-headers-oid NAME 'iplanet-am-sample-mail-initial-headers' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-inactivity-interval-oid NAME 'iplanet-am-sample-mail-inactivity-interval' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-auto-load-oid NAME 'iplanet-am-sample-mail-auto-load' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-headers-perpage-oid NAME 'iplanet-am-sample-mail-headers-perpage' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-quota-oid NAME 'iplanet-am-sample-mail-quota' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-max-attach-len-oid NAME 'iplanet-am-sample-mail-max-attach-len' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )
attributeTypes: ( iplanet-am-sample-mail-can-save-address-book-on-server-oid NAME 'iplanet-am-sample-mail-can-save-address-book-on-server' DESC 'iPlanet SampleMailService Attribute' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 X-ORIGIN 'iPlanet Directory Pro' )

dn: cn=schema
changetype:modify
add:objectClasses
objectClasses: ( iplanet-am-sample-mail-service-oid NAME 'iplanet-am-sample-mail-service' DESC 'iPlanet dpro SampleMail Service' SUP top AUXILIARY MAY (iplanet-am-sample-mail-service-status $ iplanet-am-sample-mail-root-folder $ iplanet-am-sample-mail-sentmessages-folder $ iplanet-am-sample-mail-indent-prefix $ iplanet-am-sample-mail-initial-headers $ iplanet-am-sample-mail-inactivity-interval $ iplanet-am-sample-mail-auto-load $ iplanet-am-sample-mail-headers-perpage $ iplanet-am-sample-mail-quota $ iplanet-am-sample-mail-max-attach-len $ iplanet-am-sample-mail-can-save-address-book-on-server) X-ORIGIN 'iPlanet Directory Pro' )


sampleMailService.xml File

Following is the sampleMailService.xml file, which is located in the <dsame_root>/samples/cli/sampleMailService directory. See the Code Example 5-31 for an excerpt from the sampleMailService.xml file which defines some dynamic attributes.

This section gives some information on the sampleMailService.xml file. This file can be used as guidelines when creating a service XML file. Refer to the sampleMailService.xml file in the sampleMailService directory when reading information in this section.

The "iplanet-am-sample-mail-root-folder" attribute is also specified as a dynamic attribute. The attribute schema is specified with a type of "single", a syntax of "string", and a default value of "Mail", which is the default name for the iplanet-am-sample-mail-root-folder attribute. The i18nKey value is "a2", which maps to "Root Folder", which is the field that displays on the DSAME console for the "iplanet-am-sample-mail-root-folder" attribute. The syntax of "string" means that the user (or administrator) can enter whatever he/she wants to enter in the "Root Folder" field on the sampleMailService service page, in place of the default value of "Mail".

The "iplanet-am-sample-mail-inactivity-interval" attribute is specified as a dynamic attribute. The attribute schema is specified with a type of "single", syntax of "number", i18nKey value of "a6", and a default value of 5. This means that for the "iplanet-am-sample-mail-inactivity-interval" attribute on the sampleMailService service page, the localization field that displays is "Check New Mail Interval (minutes)" will display, and users and administrators will be able to enter a single, number value in this field when creating a modified or new service template.

Several other attributes in the sampleMailService.xml file are specified with attribute types of "single", syntax of "number, and given default values. For example, the "iplanet-am-sample-mail-headers-perpage" attribute is specified as a single type, default value of 10, and given an i18nKey value of "a8", which maps to the "Headers per page" field in the sampleMailService.properties file. This means that for the Headers page page field on the sampleMailService service page in DSAME console, users and administrators can specify any single number in place of the default value given, which is 10.


sampleMailService.properties File

Following is the sampleMailService.properties file, which is located in the <dsame_root>/samples/cli/sampleMailService directory.

Code Example 5-31    sampleMailService.properties File
#
# PROPRIETARY/CONFIDENTIAL/ Use of this product is subject
# to license terms. Copyright 2001 Sun Microsystems Inc.
# Some preexisting portions Copyright 2001 Netscape
# Communications Corp. All rights reserved.
#

iplanet-am-sample-mail-service-description=Sample Mail Service Profile
a1=Mail Status
a2=Root Folder
a3=Sent Messages Folder
a4=Reply Prefix
a5=Initial Headers to Load
a6=Check New Mail Interval (minutes)
a7=Automatic Message Load at Disconnect
a8=Headers Per Page
p1=Mail Quota
p2=Auto-download Maximum Attachment Length
p3=Save Address Book on Server

Every service that you register with DSAME must have a corresponding .properties file. All the .properties files for DSAME are located in the following directory:

<DSAME_root>/web-apps/services/WEB-INF/classes/*.properties

Each service in DSAME has a corresponding XML (.xml) file and a corresponding .properties file. The XML file defines the attributes for each service. For each attribute in the service's XML file, there is an `i18nKey" field, for which the value is used as a key to retrieve the actual display message from the service's corresponding .properties file. The DSAME console displays the attributes in alphabetical order according to the i18Nkey definitions in the service XML. For example, if you want two of the attributes to display at the top of the page in DSAME console, give the attributes' i18Nkey definitions values of "a1" and "a2", respectively, and then "b1" and "b2", and so forth, to order the attributes on the Services page. There is a one-to-one mapping between the i18nKey in the XML file and the key in the .properties file.

All the index keys listed in a .properties file (for example, "a1", "p1", etc.) are values for multiple descI18n index keys specified in the service's XML file. When you write a custom service XML and .properties file, you must provide files with all attributes and values that you want to display in DSAME console.

Each service must first be imported with the amadmin tool. Then the administrator or user can log into DSAME console and go to the organization he/she wants to register the service for. For each service you add, you must update the DSAME console service hierarchy attribute to get it to display in the service tree. (See Section "Add the sampleMailService to the Service Hierarchy" on page 206 for information on adding a service to the service hierarchy.) At that point, the administrator can log out, log back in, and the service displays for the organization. Then he/she can register and activate the service in DSAME console. (Alternatively, after importing the service, you could use the registerRequests.xml to register a service for an existing organization, then activate the service by importing an activateRequests.xml to activate the service for an existing organization.)

Below is an excerpt from the sampleMailService.properties file that shows the "a1" and "a2" index key values that are specified in the service's XML file.

Code Example 5-32    Excerpt from sampleMailService.properties File
iplanet-am-sample-mail-service-description=Sample Mail Service Profile
a1=Mail Status
a2=Root Folder

Every service imported into DSAME using amadmin must have a corresponding and .properties file for it. Also, the relevant .properties filename must be defined in the i18NFileName attribute in the sampleMailService.xml file. In the excerpt from the sampleMailService.xml file below, note that the i18nFileName attribute points to the `sampleMailService' file.

Code Example 5-33    Excerpt from sampleMailService.xml File
ServicesConfiguration>
<Service name="sampleMailService" version="1.0">
<Schema
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
   <Global>
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
</DefaultValues>
</AttributeSchema>
   </Global>

Also, note that each i18nKey for every attribute schema definition in the XML file points to, or is "equal to" a value such as "a1", "a2", or "p1" or "p2" and so forth. These i18nKey values are in the corresponding .properties file for the service (for example, the `sampleMailService.properties' file for the `sampleMailService.xml' file). Note that in the sampleMailService.properties file, there is a list of i18nKey fields (also called "localization keys" or "indexes" or "index keys"), which contain the field exactly as it will display on that service page in the DSAME console. For example, using the excerpted sample below, "a1" will display the field "Mail Status" and "a2" displays the field "Root Folder" on the Sample Mail Service Profile page in DSAME console.

Code Example 5-34    Excerpt showing dynamic attribute definitions in sampleMailService.xml File
<Dynamic>
<AttributeSchema name="iplanet-am-sample-mail-service-status"
type="single_choice"
syntax="string"
i18nKey="a1">
<ChoiceValues>
<ChoiceValue>Active</ChoiceValue>
<ChoiceValue>Inactive</ChoiceValue>
<ChoiceValue>Deleted</ChoiceValue>
</ChoiceValues>
<DefaultValues>
<Value>Active</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-root-folder"
type="single"
syntax="string"
i18nKey="a2">
<DefaultValues>
<Value>Mail</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-sentmessages-folder"
type="single"
syntax="string"
i18nKey="a3">
<DefaultValues>
<Value>MailSent</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-indent-prefix"
type="single"
syntax="string"
i18nKey="a4">
<DefaultValues>
<Value>|</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-initial-headers"
type="single"
syntax="number"
i18nKey="a5">
<DefaultValues>
<Value>10</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-inactivity-interval"
type="single"
syntax="number"
i18nKey="a6">
<DefaultValues>
<Value>5</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-auto-load"
type="single"
syntax="number"
i18nKey="a7">
<DefaultValues>
<Value>0</Value>
</DefaultValues>
</AttributeSchema>
<AttributeSchema name="iplanet-am-sample-mail-headers-perpage"
type="single"
syntax="number"
i18nKey="a8">
<DefaultValues>
<Value>10</Value>
</DefaultValues>
</AttributeSchema>
</Dynamic>


Explanation of Policy Schema Definitions in sampleMailService.xml

The sampleMailService.xml file gives a brief sample of some policy attributes.

See Section "Overview of Some Policy Concepts and Terms in DSAME" on page 153 and Section "Policy Management Module" on page 153 for information on policy concepts and terms. Section "Attributes and Elements that DSAME Supports" on page 134 for some information of the SMS elements and attributes that use policy (for example, Policy, ActionSchema, ActionValue and ResourceName elements) in the sms.dtd.

In Code Example 5-35, the Policy element defines a grouping of actions (or privileges) that are specific to the service. Examples of actions are canForwardEmailAddress, canChangeSalaryInformation, etc. These action names define a set of permissions, or privileges; for example,

The ActionSchema element defines a single action (or privilege) for a service. The attribute name in the first policy element definition is:

name="iplanet-am-sample-mail-quota"

The first ActionSchema element name "iplanet-am-sample-mail-quota" defines a single action or privilege for a service, in this case, it defines a mail quota for the sampleMailService of 1000000 kilobytes, or 1 MB, which is defined to be a type of single choice on the DSAME console, syntax of "number", which means that administrators or users must enter a number when creating a new service template, and the default value given for administrators is 1000000 (KB). The i18nKey="p1" definition means that the localization, or index, key points to the "p1" index or key in the sampleMailService.properties file, which maps to the field Mail Quota, which will display for the iplanet-am-sample-mail-quota attribute on the DSAME console services page.

The next ActionSchema element definition in the sampleMailService.xml file is:

ActionSchema name="iplanet-am-sample-mail-max-attach-len"

Similarly, the "iplanet-am-sample-mail-quota" Action name defines a set of permissions or privileges, which will appear as "single" type choice on the service page in DSAME console, which means that administrators and users can specify a single type value, which must have be a number. The i18nKey value maps to "p2", which maps to the Auto-download Maximum Attachment Length field, which is the exact field that will display for the "ipalent-am-sample-mail-max-attach-len" atttribute on the sampleMailService services page in DSAME console

p2=Auto-download Maximum Attachment Length

The "iplanet-am-sample-mail-max-attach-len" attribute is given a default value of 100000 which will display on the sampleMailServices page in DSAME console, which administrators can change, provided the value they enter matches the ActionSchema definition.


Note

DSAME 5.0 does not support default values for policy schema definitions.


Code Example 5-35    Excerpt from sampleMailService.xml defining Policy Schema
<Policy>
<ActionSchema name="iplanet-am-sample-mail-quota"
type="single"
syntax="number"
i18nKey="p1">
</ActionSchema>
<ActionSchema name="iplanet-am-sample-mail-max-attach-len"
type="single"
syntax="number"
i18nKey="p2">
</ActionSchema>
<ActionSchema name="iplanet-am-sample-mail-can-save-address-book-on-server"
type="single"
syntax="boolean"
i18nKey="p3">
</ActionSchema>
</Policy>
</Schema>
</Service>
</ServicesConfiguration>


Policy Schema must be defined before Policy Template can be Created in DSAME Console

It is important to note that you must add services (import the service using the amadmin tool) that have policy subschema defined for the organization before you can create a policy template. Once the service with policy schema defined has been imported into DSAME, then you can create a policy template within DSAME console.

If the DSAME console detects that an organization does not have any services defined for that organization, it will not create a policy template, and will give an error.



amAdmin.dtd Used when Performing Batch Updates to DIT


The amAdmin.dtd is the DTD that is used by DSAME when you perform batch operations on the DIT (such as creations, deletions, gets on user objects such as roles, organizations, users, people containers, and groups). When writing XML files that perform batch operations on the DIT, administrators or customization engineers must follow the document structure defined in this DTD.


Note

The XML files that define services use a different DTD—the sms.dtd. The XML files that perform batch updates on the Directory server use the amAdmin.dtd.



Batch Operations you can perform using the amAdmin.dtd

The purpose of the amAdmin.dtd is to enable you to perform the following command line operations on DSAME. Using the amadmin tool with the --data option enables an administrator or customization engineer to:

  • Create roles, users, organizations, groups, people containers and services.

  • Create users, suborganizations, roles, groups, sub-containers, people containers, sub-people containers, sub-groups.

  • Delete roles, users, organizations, groups, people containers and services.

  • Read roles, users, organizations, groups, people containers and services.

  • Get roles, people containers, and users.

  • Get the number of users for groups, people containers, and roles.

  • Import services.

  • Register a service for an existing organization.

  • Unregister a service from an existing organization.

  • Get registered service names from an existing organization.

  • Get activated service names from an existing organization.

  • Get the total number of registered and activated services for an existing organization.

  • Execute requests in multiple XML files together on the amadmin command line. (The order is important that the batch update XML files are imported is important. For example, you must register a service before it can be activated; similarly, a service must be deactivated before it can be unregistered.)


Files Used to perform Batch Updates to DIT

There are several sample files provided in the following directory, which enable you to perform the operations described in Section "Batch Operations you can perform using the amAdmin.dtd" on page 170:

<dsame_root>/samples/admin/cli/bulk-ops

The sample files provided for you to perform batch operations are:

  • createRequests.xml

  • activateRequests.xml

  • deactivateRequests.xml

  • deleteGroupRequests.xml

  • deleteOrgRequests.xml

  • deletePCRequests.xml

  • deletePolicyRequests.xml

  • getActivatedServices.xml

  • getNumOfServices.xml

  • getRegisteredServices.xml

  • getRequests.xml

  • registerRequests.xml

  • unregisterRequests.xml

See the Section "Sample File (createRequests.xml) to Perform batch Updates to DIT" on page 188 for a brief explanation of the createRequests.xml file, and refer to Chapter 6 "Using the Command Line Interface for information on how to import batch operations sample files into the DIT.



Description of amAdmin.dtd


This section provides some information on the amAdmin.dtd which defines some rules that must be adhered to, when writing and using batch operations XML files in DSAME.

The amAdmin.dtd uses standard XML (Extensible Markup Language) syntax, elements, and attributes. The amAdmin.dtd has been written specifically for use with the DSAME product, and the attributes are specific to DSAME and Directory server. For explanations of standard XML elements, syntax, and attributes, refer to any of the numerous XML books or web sites available, or go to the following URL:

http://xml101.com

The amAdmin.dtd reflects the structure of the DSAME SDK. The amAdmin.dtd follows a request-based paradigm. Neither the amAdmin.dtd nor the amadmin CLI tool are meant to fully duplicate the DSAME console (GUI) functionality available through the amadmin CLI tool.

The following sections provide brief explanations of the batch update tasks you can perform on the DIT, such as creating, deleting, and reading roles, users, organizations, groups, people containers, and services from the Directory server tree (DIT). The administrator or customization engineer must configure some sample batch update XML files per the rules defined in the amAdmin.dtd. Some sample batch operations XML files are located in the following directory:

<dsame_root>/samples/admin/cli/bulk-ops

Note that there are descriptions of the various amAdmin.dtd elements and attributes used when performing batch operations on the DIT is provided in the amAdmin.dtd file itself.


Note

You should not modify the amAdmin.dtd in any way. It contains rules and definitions that control the way batch operations are performed on the Directory Information Tree (DIT), and must not be modified; otherwise, errors could be introduced into your Directory server DIT, or the batch operations will not work correctly.



Requests Element

The Requests element is the root element of the input XML document to amadmin. It must contain at least on child element. The child elements are designe dto follow an object-oriented model where the actual requests are performed on the high level DSAME objects such as Organization, Container, People Container, Role, and Group. To enable batch processing, the root element can accept more than one set of requests.

The Requests element defines all the directory objects that can be performed on the Directory server DIT:

  • Organization

  • Container

  • People Container

  • Role

  • Group

See Code Example 5-36 for a sample Requests Element and Requests sub-element.

Code Example 5-36    Requests Element and Requests Sub-Elements
<!ELEMENT Requests (
OrganizationRequests |
ContainerRequests |
PeopleContainerRequests |
RoleRequests |
GroupRequests )+
>



OrganizationRequests Element

The OrganizationRequests element combines all the requests that are to be performed on Organization type objects. To enable batch processing, this element can have one or more child elements. The child elements, as suggested by their intuitive names, represent the various requests. Note that all the child elements perform their operations on the same instance of Organization object. If you want to manipulate different Organization objects, you can include different OrganizationRequests elements in the root element Requests.

All the organization requests are shown in the (for example, create suborganizations, get roles, unregsiter services, delete sub-organizations, etc.)

Code Example 5-37    OrganizationRequests Element
<!ELEMENT OrganizationRequests (
(CreateSubOrganization)*,
(CreatePeopleContainer)*,
(CreateRole)*,
(CreateGroup)*,
(CreatePolicy)?,
(GetSubOrganizations)?,
(GetPeopleContainers)?,
(GetRoles)?,
(GetGroups)?,
(GetUsers)?,
(RegisterServices)?,
(UnregisterServices)?,
(ActivateServices)?,
(DeactivateServices)?,
(GetActivatedServiceNames)?,
(GetRegisteredServiceNames)?,
(GetNumberOfServices)?,
(DeleteRoles)?,
(DeleteGroups)?,
(DeletePolicy)?,
(DeletePeopleContainers)?,
(DeleteSubOrganizations)? )
>

The DN attribute of the element OrganizationRequests specifies the DN (Distinguished Name, for example, "uid=amAdmin,ou=People,o=iplanet.com,o=isp") of the Organization element, on which all of the requests (specified by the child elements) will be performed.

Note that the DN attribute is a required attribute; the service developer or customization engineer must supply a DN on the amadmin command line when performing the batch operation.

Code Example 5-38    DN Attribute of OrganizationRequests Element
<!-- The DN attribute of the element, OrganizationRequests, specifies
the DN of the Organization object on which all of the requests
(specified by the child elements) shall be made.
-->

<!ATTLIST OrganizationRequests
DN CDATA #REQUIRED
>


CreateSubOrganization Element

The CreateSubOrganization element can have zero or more AttributeValuePairs.

The Attribute element must be all one word without spaces, thus, it is specified as NMTOKEN in the amAdmin.dtd. (See .)

Code Example 5-39    CreateSubOrganization Element
<!-- Note that CreateSubOrganization element can have zero or more
AttributeValuePairs.
-->

<!ELEMENT CreateSubOrganization (AttributeValuePair)* >
<!ATTLIST CreateSubOrganization
createDN CDATA #REQUIRED
>
<!ELEMENT AttributeValuePair (Attribute, (Value)+) >
<!ELEMENT Attribute EMPTY >

<!-- Attribute must be all one word without spaces. Hence, it is
indicated as NMTOKEN below.
-->

<!ATTLIST Attribute
name NMTOKEN #REQUIRED
>
<!ELEMENT Value (#PCDATA) >

CreatePeopleContainer Element

The CreatePeopleContainer element lets you create an attribute/value pair on the specified people container in the DIT. You must specify a "createDN" attribute.


CreateGroup Element

The CreateGroup Element lets you create a specified group in the DIT. You must specify a "createDN" attribute.


CreateRole Element

The CreateRole element lets you create a specified role in the DIT, and specify attribute/value pairs also. You must specify a "createDN" attribute. (See .)

Code Example 5-40    CreatePeopleContainer, CreateGroup, and CreateRole Elements

<!ELEMENT CreatePeopleContainer (AttributeValuePair)* >
<!ATTLIST CreatePeopleContainer
createDN CDATA #REQUIRED
>

<!-- __________________________________________________________________ -->

<!ELEMENT CreateGroup EMPTY >
<!ATTLIST CreateGroup
createDN CDATA #REQUIRED
>

<!-- __________________________________________________________________ -->

<!ELEMENT CreateRole (AttributeValuePair)* >
<!ATTLIST CreateRole
createDN CDATA #REQUIRED
>

<!-- __________________________________________________________________ -->


CreatePolicy Element

The CreatePolicy element lets you create one or more policy objects in the DIT. Policy is the root element that defines a named policy. The attribute "name" specifies the policy name. "serviceName" attribute identifies the service name to which the named policy applies.

The Policy element can have one or more rules specified for it (specified by Rule+).

Code Example 5-41    Create Policy Element
<!ELEMENT CreatePolicy (Policy)+ >
<!ATTLIST CreatePolicy
createDN CDATA #REQUIRED
>

<!-- Policy is the root element that defines a named policy.
The attribute "name" provides the policy name.
"serviceName" identifies the service name for which the policy is
applicable.
The policy element can have one or more rules (Rule).
-->

<!ELEMENT Policy ( Rule+ ) >
<!ATTLIST Policy
name CDATA #REQUIRED
serviceName NMTOKEN #IMPLIED
>


Rule Element with ServiceName, ResourceName?, and AttributeValuePair+ Sub-Elements

The Rule element defines a policy rule that contains a service name, resource name, and its action names and corresponding values. The "name" attribute provides a user-friendly name for the rule. The sub-element "ServiceName" gives the name of the service; the sub-element "ResourceName" gives the resource name, and the "AttributeValuePair" provides the action names and corresponding action values.

The sub-element "ServiceName" provides the name of the service for which a rule has been created. The attribute "name" provides the service name.

The sub-element "ResourceName" provides the name of the reource for which a rule has been created. If the service does not have a resource, this element will not be there for the rule. The "name" attribute provides the resource name. (See .)

Code Example 5-42    Rule Element with Sub-Elements
<!ELEMENT Rule ( ServiceName, ResourceName?,
AttributeValuePair+ ) >
<!ATTLIST Rule
name CDATA #REQUIRED
>

<!-- ServiceName provides the name of the service for which a
rule has been created. The attribute "name" provides the service
name.
-->

<!ELEMENT ServiceName EMPTY>
<!ATTLIST ServiceName
name CDATA #REQUIRED
>

<!-- ResourceName provides the name of the resource for which
a rule has been created. If the service does not have resource,
this element will not be there for the rule. The attribute "name"
provides the resource name.
-->

<!ELEMENT ResourceName EMPTY>
<!ATTLIST ResourceName
name CDATA #REQUIRED
>


GetSubOrganizations Element

For the GetSubOrganizations element, for those objects that have LDAP attributes, all get operations in the amAdmin.dtd follow the same design pattern. If the element has an XML attribute "DNsOnly" set to true, or does not have the "DNsOnly" attribute, only the DNs of the corresponding DSAME objects will be returned. If DNsOnly="false", the entire object (with the LDAP attribute value pairs) will be returned. However, the behavior of DNsOnly is valid ONLY if there are no child elements (DNs) specified; if the DNs are specified, the entire object will always be returned. (See .)

Code Example 5-43    GetSubOrganizations Element
<!ELEMENT GetSubOrganizations (DN)* >

<!-- For those objects that may have LDAP attributes, all get operations in
this DTD follow the same design pattern: If the element has an XML
attribute DNsOnly set to true or doesn't have that XML attribute, only
the DNs of the corresponding DSAME objects shall be
returned. If DNsOnly="false", the entire object (with the LDAP
attribute value pairs) shall be returned.
However, the behavior of DNsOnly is valid ONLY if there are no child
elements (DNs) specified; if the DNs are specified, the entire
object shall always be returned.
-->

<!ATTLIST GetSubOrganizations
DNsOnly (true | false) "true"
>


GetPeopleContainers, GetGroups, and GetRoles Elements

For the GetPeopleContainers element, if there are no child elements (no DNs) specified, then ALL PeopleContainers at all levels within the specified Organization will be returned.

For the GetGroups element, you must specify a "level" attribute, or node, for which you want to get the groups returned. You can specify "ONE_LEVEL" to get just the groups at that node level, or you can specify a "SUB-TREE" attribute, which gets all the groups for at that node's level and all the nodes underneath that node.

For the GetRoles element, you must specify a "level" attribute, or node, for which you want to get the roles returned. You can specify "ONE_LEVEL" to get just the roles at that node level, or you can specify a "SUB-TREE" attribute, which gets all the roles for at that node's level and all the nodes underneath that node.

Code Example 5-44    GetPeopleContainers, GetGroups, and GetRoles Elements
<!ELEMENT GetPeopleContainers (DN)* >
<!ATTLIST GetPeopleContainers
DNsOnly (true | false) "true"
>

<!-- __________________________________________________________________ -->

<!ELEMENT GetGroups EMPTY >
<!ATTLIST GetGroups
level (ONE_LEVEL | SUB_TREE) "SUB_TREE"
>

<!-- __________________________________________________________________ -->

<!ELEMENT GetRoles EMPTY >
<!ATTLIST GetRoles
level (ONE_LEVEL | SUB_TREE) "SUB_TREE"
>


GetUsers Element

For the GetUsers element, if there are no child elements (no DNs) specified, then ALL users at all levels within this object are returned. You must specify a true or false value for the GetUser element; the default is true.

Code Example 5-45    GetUsers Element
<!ELEMENT GetUsers (DN)* >
<!ATTLIST GetUsers
DNsOnly (true | false) "true"
>


RegisterServices and UnregisterServices Elements

For the RegisterServices element, the service schema for the service must have been loaded by using the amadmin CLI tool before a service can be registered. Multiple services can be registered using this tag. One or more Service_Name sub-elements can be specified on which to register services.

For the UnregisterServices element, it can be ued to unregister a previously-registered service. If the service was not previously registered, the request is simply ignored for that service. Multiple services can be unregistered using this tag. If no Service_Name tag is specified, then no registered service will be unregistered, the request is simply ignored.

Code Example 5-46    RegisterServices and UnregisterServices Elements
<!-- Before a service is registered, the service schema for the service must
have been loaded using the CLI. Multiple services can be registered using this
tag.
-->

<!ELEMENT RegisterServices (Service_Name)+ >
<!ELEMENT Service_Name (#PCDATA) >

<!-- __________________________________________________________________ -->

<!-- Unregister a previously registered service. If the service was not
previously registered, the request is simply ignored for that service. Multiple
services can be unregistered using this tag. If no Service_Name tag is
specified, then no registered service will be unregistered, the request is
simply ignored.
-->

<!ELEMENT UnregisterServices (Service_Name)* >


ActivateServices and DeactivateServices Elements

For the ActivateServices element, a service must have been registered before it can be activated. Before a service is registered, the service schema must have been loaded using the amadmin CLI tool. If no Service_Name tag is specified, then no registered service will be activated, the request is simply ignored.

For the DeactivateServices element, a service must have been registered and activated before it can be deactivated. Before a service is registered, the service schema must have been loaded using the amadmin CLI tool. If the service was not previously registered and/or activated, the request is ignored for that service. Multiple services can be deactivated using this tag. If no Service_Name tag is specified, then no registered service will be deactivated, the request is simply ignored.

Code Example 5-47    ActivateServices and DeactivateServices Elements
<!ELEMENT ActivateServices (Service_Name)* >

<!-- __________________________________________________________________ -->

<!-- A service must have been registered and activated before it can be
deactivated. Before a service is registered, the service schema must have been
loaded using the CLI. If the service was not previously registered and/or
activated, the request is simply ignored for that service. Multiple services
can be deactivated using this tag. If no Service_Name tag is specified, then
no registered service will be deactivated, the request is simply ignored.
-->

<!ELEMENT DeactivateServices (Service_Name)* >

<!-- __________________________________________________________________ -->

<!-- ALL activated services within this object are returned.
-->


GetActivatedServiceNames, GetRegisteredServiceNames, and GetNumberofServices Elements

For the GetActivatedServiceNames element, all activated services within this object are returned.

For the GetRegisteredServiceNames element, all registered services within this object are returned.

For the GetNumberOfServices element, the total number of services within this object are returned.

Code Example 5-48    GetActivatedServiceNames, GetRegisteredServicesNames, and Get GetNumberOfServices Elements
<!-- ALL activated services within this object are returned.
-->

<!ELEMENT GetActivatedServiceNames EMPTY >

<!-- __________________________________________________________________ -->

<!-- ALL registered services within this object are returned.
-->

<!ELEMENT GetRegisteredServiceNames EMPTY >

<!-- __________________________________________________________________ -->


<!-- Total number of services within this object are returned.
-->

<!ELEMENT GetNumberOfServices EMPTY >


DeleteSubOrganizations Element

For those objects that have children objects (such as containers, organizations, people containers), all delete operations in the amAdmin.dtd follow the same design pattern: If deleteRecursively="false", then accidental deleting entire subtrees is avoided. It could be disastrous if deleteRecursively="true". To avoid accidental and unintentional deletions, the default value is "false".

Code Example 5-49    DeleteSubOrganizations Element
<!ELEMENT DeleteSubOrganizations (DN)+ >
<!ATTLIST DeleteSubOrganizations
deleteRecursively (true | false) "false"
>


DeletePeopleContainers Element

For those objects that have children objects (such as containers, organizations, people containers), all delete operations in this DTD follow the same design pattern: If deleteRecursively="false", then accidentally deleting entire subtrees is avoided.

Code Example 5-50    DeletePeopleContainers Element
<!ELEMENT DeletePeopleContainers (DN)+ >
<!ATTLIST DeletePeopleContainers
deleteRecursively (true | false) "false"
>


DeleteGroups Element

For those objects that might have children objects (such as containers, organizations, people containers), all delete operations in this DTD follow the same design pattern: If deleteRecursively="false", then accidentally deleting entire subtrees is avoided. It can be disastrous if deleteRecursively="true". The default value is `false' to avoid accidental and unintentional deletions.

Code Example 5-51    DeleteGroups Element
<!ELEMENT DeleteGroups (DN)+ >
<!ATTLIST DeleteGroups
deleteRecursively (true | false) "false"
>


DeleteRoles Element

The DeleteRoles element deletes roles, based on the DN.

Code Example 5-52    DeleteRoles element
<!ELEMENT DeleteRoles (DN)+ >



DeletePolicy Element

The DeletePolicy element deletes the policy applicable to a service, given the DN.

Code Example 5-53    DeletePolicy Element
<!ELEMENT DeletePolicy (PolicyName)+ >
<!ATTLIST DeletePolicy
deleteDN CDATA #REQUIRED
>


PolicyName Element

The PolicyName element gives the name of the policy applicable to a service.

Code Example 5-54    PolicyName Element
<!ELEMENT PolicyName EMPTY>
<!ATTLIST PolicyName
name CDATA #REQUIRED
>


ContainerRequests Element

The ContainerRequests element aggregates all the requests that are to be performed on Container type objects. To enable batch processing, this element can have one or more child elements. The child elements, as suggested by their intuitive names, represent the various requests. Note that all the child elements operate on the same instance of Container object. If different Container objects are to be manipulated, different ContainerRequests elements can be included in the root element Requests.

See Code Example 5-55 for a list of the types of container requests you can perform on the DIT in a batch operation; for exame, you can create roles, groups, policies, activate and deactivate services, delete roles and groups, and other requests on objects in the DIT.

Note that you can when you create roles in the DIT, you can specify attribute/value pairs. You can create sub-containers with attribute/value pairs, create sub-people-containers with attribute/value pairs, and create users with attribute/value pairs.

Code Example 5-55    ContainerRequests Element
<!ELEMENT ContainerRequests (
(CreateSubContainer)*,
(CreatePeopleContainer)*,
(CreateRole)*,
(CreateGroup)*,
(CreatePolicy)?,
(GetSubContainers)?,
(GetPeopleContainers)?,
(GetRoles)?,
(GetGroups)?,
(GetUsers)?,
(RegisterServices)?,
(UnregisterServices)?,
(ActivateServices)?,
(DeactivateServices)?,
(GetActivatedServiceNames)?,
(GetRegisteredServiceNames)?,
(GetNumberOfServices)?,
(DeleteRoles)?,
(DeleteGroups)?,
(DeletePolicy)?,
(DeletePeopleContainers)?,
(DeleteSubContainers)? )
>

<!-- The DN attribute of the element, ContainerRequests, specifies
the DN of the Container object on which all of the requests
(specified by the child elements) shall be made.
-->

<!ATTLIST ContainerRequests
DN CDATA #REQUIRED
>

<!-- __________________________________________________________________ -->

<!-- Note that CreateSubContainer element can have zero or more
AttributeValuePairs.
-->

<!ELEMENT CreateSubContainer (AttributeValuePair)* >
<!ATTLIST CreateSubContainer
createDN CDATA #REQUIRED
>

<!-- __________________________________________________________________ -->

<!-- If there are no child elements (no DNs) specified, then ALL
subContainers at all levels within this Container are returned.
-->

<!ELEMENT GetSubContainers (DN)* >

<!-- For those objects that may have LDAP attributes, all get operations in
this DTD follow the same design pattern: If the element has an XML
attribute DNsOnly set to true or doesn't have that XML attribute, only
the DNs of the corresponding DSAME objects shall be
returned. If DNsOnly="false", the entire object (with the LDAP
attribute value pairs) shall be returned.
However, the behavior of DNsOnly is valid ONLY if there are no child
elements (DNs) specified; if the DNs are specified, the entire
object shall always be returned.
-->

<!ATTLIST GetSubContainers
DNsOnly (true | false) "true"
>

<!-- __________________________________________________________________ -->

<!-- For those objects that may have children objects (such as containers,
organizations, people containers), all delete operations
in this DTD follow the same design pattern: If deleteRecursively="false",
then accidental deletion of entire subtrees is avoided.
It can be disastrous if deleteRecursively="true". The default value is 'false'
to avoid accidental and unintentional deletions.
-->

<!ELEMENT DeleteSubContainers (DN)+ >
<!ATTLIST DeleteSubContainers
deleteRecursively (true | false) "false"
>

<!-- ======================== PeopleContainerRequests =================== -->

<!ELEMENT PeopleContainerRequests (
(CreateSubPeopleContainer)*,
(CreateUser)*,
(GetNumberOfUsers)?,
(GetUsers)?,
(GetSubPeopleContainers)?,
(DeleteUsers)?,
(DeleteSubPeopleContainers)? )
>

<!-- The DN attribute of the element, PeopleContainerRequests, specifies
the DN of the PeopleContainerRequests object on which all of the requests
(specified by the child elements) shall be made.
-->

<!ATTLIST PeopleContainerRequests
DN CDATA #REQUIRED
>

<!ELEMENT CreateSubPeopleContainer (AttributeValuePair)* >
<!ATTLIST CreateSubPeopleContainer
createDN CDATA #REQUIRED
>

<!ELEMENT CreateUser (AttributeValuePair)* >
<!ATTLIST CreateUser
createDN CDATA #REQUIRED
>

<!-- For those objects that may have children objects (such as containers,
organizations, people containers), all delete operations
in this DTD follow the same design pattern: If deleteRecursively="false",
then accidental deletion of entire subtrees is avoided.
It can be disastrous if deleteRecursively="true". The default value is 'false'
to avoid accidental and unintentional deletions.
-->

<!ELEMENT DeleteSubPeopleContainers (DN)+ >
<!ATTLIST DeleteSubPeopleContainers
deleteRecursively (true | false) "false"
>

<!ELEMENT DeleteUsers (DN)+ >

<!ELEMENT GetSubPeopleContainers (DN)* >
<!ATTLIST GetSubPeopleContainers
level (ONE_LEVEL | SUB_TREE) "SUB_TREE"
DNsOnly (true | false) "true"
>

<!-- ======================== RoleRequests =================== -->

<!ELEMENT RoleRequests (
(GetNumberOfUsers)?,
(GetUsers)?,
(AddUsers)?
)
>

<!-- The DN attribute of the element, RoleRequests, specifies
the DN of the RoleRequests object on which all of the requests
(specified by the child elements) shall be made.
-->

<!ATTLIST RoleRequests
DN CDATA #REQUIRED
>

<!ELEMENT GetNumberOfUsers EMPTY >

<!ELEMENT AddUsers (DN)+ >
<!ELEMENT DN (#PCDATA) >

<!-- ======================== GroupRequests =================== -->

<!ELEMENT GroupRequests (
(CreateSubGroup)*,
(GetSubGroups)?,
(GetNumberOfUsers)?,
(GetUsers)?,
(AddUsers)?,
(DeleteSubGroups)? )
>

<!-- The DN attribute of the element, GroupRequests, specifies
the DN of the GroupRequests object on which all of the requests
(specified by the child elements) shall be made.
-->

<!ATTLIST GroupRequests
DN CDATA #REQUIRED
>

<!ELEMENT GetSubGroups (DN)* >
<!ATTLIST GetSubGroups
level (ONE_LEVEL | SUB_TREE) "SUB_TREE"
DNsOnly (true | false) "true"
>

<!ELEMENT CreateSubGroup (AttributeValuePair)* >
<!ATTLIST CreateSubGroup
createDN CDATA #REQUIRED
>

<!-- For those objects that may have children objects (such as containers,
organizations, people containers), all delete operations
in this DTD follow the same design pattern: If deleteRecursively="false",
then accidental deletion of entire subtrees is avoided.
It can be disastrous if deleteRecursively="true". The default value is 'false'
to avoid accidental and unintentional deletions.
-->

<!ELEMENT DeleteSubGroups (DN)+ >
<!ATTLIST DeleteSubGroups
deleteRecursively (true | false) "false"
>



Sample File (createRequests.xml) to Perform batch Updates to DIT

Below is one of the sample XML files provided in the <dsame_install_dir/SUNWam/samples/admin/cli/bulk-ops directory. For example, you would use the createRequests.xml file to create various objects such as users, roles, people containers, groups, etc. in the DIT.

Code Example 5-56    createRequests.xml File  
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Requests
PUBLIC "-//iPlanet//DSAME 5.0 Admin CLI DTD//EN"
"file:/opt/SUNWam/web-apps/services/dtd/amAdmin.dtd"
>

<!-- CREATE REQUESTS -->

<Requests>
<OrganizationRequests DN="o=isp">

<CreateSubOrganization createDN="sun.com"/>

<CreatePeopleContainer createDN="People1,o=sun.com"/>

<CreateRole createDN="ManagerRole,o=sun.com"/>

<CreateRole createDN="EmployeeRole,o=sun.com"/>

<CreateGroup createDN="ContractorsGroup,o=sun.com"/>

<CreateGroup createDN="EmployeesGroup,o=sun.com"/>

<CreatePolicy createDN="o=sun.com,o=isp">
<Policy name="ManagerPolicy"
serviceName="sampleMailService">
<Rule name="Manager Rule">
<ServiceName name="sampleMailService"/>
<ResourceName name="sampleMailService"/>
       <AttributeValuePair>
        <Attribute name="iplanet-am-sample-mail-quota"/>
        <Value>1000000</Value>
       </AttributeValuePair>         
       <AttributeValuePair>
        <Attribute name="iplanet-am-sample-mail-max-attach-len"/>
        <Value>100000</Value>
       </AttributeValuePair>         
       <AttributeValuePair>
        <Attribute name="iplanet-am-sample-mail-can-save-address-book-on-server"/>
        <Value>false</Value>
       </AttributeValuePair>         
</Rule>
</Policy>
</CreatePolicy>



</OrganizationRequests>

<PeopleContainerRequests DN="ou=People1,o=sun.com,o=isp">
   
   <CreateSubPeopleContainer createDN="SubPeople1">
      <AttributeValuePair>
          <Attribute name="description"/>
          <Value>SubPeople description</Value>
      </AttributeValuePair>         
   </CreateSubPeopleContainer>
   
   <CreateUser createDN="amUser">
    <AttributeValuePair>
    <Attribute name="cn"/>
    <Value>amUser</Value>
    </AttributeValuePair>
    <AttributeValuePair>
    <Attribute name="sn"/>
    <Value>amUser </Value>
    </AttributeValuePair>
    <AttributeValuePair>
    <Attribute name="userPassword"/>
    <Value>12345678</Value>
    </AttributeValuePair>
   </CreateUser>    
   
</PeopleContainerRequests>

<RoleRequests DN="cn=ManagerRole,o=sun.com,o=isp">
   
   <AddUsers>
    <DN>uid=amUser,ou=People1,o=sun.com,o=isp</DN>
   </AddUsers>   
   
</RoleRequests>

<GroupRequests DN="cn=ContractorsGroup,o=sun.com,o=isp">
   
   <CreateSubGroup createDN="SubContractorsGroup">
      <AttributeValuePair>
         <Attribute name="uniquemember"/>
         <Value>uid=amUser,ou=People1,o=sun.com,o=isp</Value>
      </AttributeValuePair>      
   </CreateSubGroup>
   
   <AddUsers>
    <DN>uid=amUser,ou=People1,o=sun.com,o=isp</DN>
   </AddUsers>
   
   
</GroupRequests>


Previous     Contents     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated December 05, 2001