Sun ONE logo     Previous     Contents     Index     Next     
Sun ONE Identity Server Programmer's Guide



Chapter 6   Service Management


Sun™ One Identity Server uses eXtensible Markup Language (XML) files and Java™ interfaces for the integration and management of services into the Identity Server configuration. This chapter provides information on the structure of the XML files and the service management application programming interfaces (API). It contains the following sections:



Overview

A service is a group of attributes, defined in an XML file, that are managed together by the Identity Server console. The attributes can be the configuration parameters of a software module or they might just be related information with no connection to a software configuration. As an example of the first scenario, after creating a payroll module, a developer defines an XML service file that might include attributes to define an employee name, an hourly pay rate and a tax percentage. This file is imported into the Sun ONE Directory Server so the attributes and their values can be stored. When the service is registered to an organization, the attributes can be managed using the Identity Server console.

Identity Server provides the mechanisms for administrators to define, integrate and manage groups of attributes as an Identity Server service. Preparing a service for management involves creating an XML service file, configuring an LDAP Data Interchange Format (LDIF) file with any new object classes and importing both, the XML service file and the new LDIF schema, into the Directory Server. Administrators can then register the service to identity objects using the Identity Server console. Once registered, the attributes can be managed and customized.


Note

Throughout this chapter, the term attribute is used for two concepts. An Identity Server or service attribute refers to the configuration parameters of a defined service. An XML attribute refers to the parameters that qualify an XML element in the XML files.



XML Service Files

XML service files enable Identity Server to manage attributes that are stored in Directory Server. Identity Server does not implement any behavior or dynamically generate any code to interpret the attributes; it can only set or get the attribute values. Out-of-the-box, Identity Server loads a number of services to manage the attributes of its own features. For example, the Logging attributes are displayed and managed in the Identity Server console, while code implementations within the Identity Server use these configured attributes to record the operations of the application. All XML service files are located in <identity_server_root>/ SUNWam/config/xml. For more specific information on XML service files, see "XML Files".


Note

Any application with LDAP attributes can have this data managed using the Identity Server console by configuring a custom XML service file and loading it into the Directory Server. For more information, see "Service Definition".



Document Type Definition Structure Files

The format of an XML file in Identity Server is based on a structure defined in a DTD file. In general, a DTD file defines the elements and qualifying attributes needed to write a well-formed and valid XML document. Identity Server exposes the DTD files that are used to define the structure for different types of XML files. The DTDs are located in <identity_server_root>/SUNWam/dtd. Additional information on them can be found in "DTD Files".


Note

Knowledge of XML is necessary to understand DTD elements and how they are integrated into Identity Server. When creating an XML file, it might be helpful to print out the relevant DTD and a corresponding sample XML file.



Service Management SDK

Identity Server also provides a service management SDK that provides application developers with interfaces to register and un-register services as well as manage their schema and configuration information. These interfaces are bundled in a package called com.sun.identity.sm. More information on the SDK can be found in "Service Management SDK".



Service Definition


To define a service for registration and management with the Identity Server the service developer must create an XML service file as well as configure an LDIF file with any object classes. Both, the XML service file and the new LDIF schema, must them be imported into the Directory Server. Once imported, the service can be registered by an administrator and its attributes managed and customized. The following sections describe the procedures to define and register a service.


Defining A Service

The following procedures must be completed in order to define a service and use the Identity Server to integrate and manage it.

  1. Create an XML service file for the component.

    This XML file must conform to the sms.dtd. A simple way to create a new XML service file would be to copy and modify an existing one. More information on creating an XML service file can be found in "Creating A Service File". The DTD syntax can be found in "The sms.dtd Structure".

  2. Extend the LDAP schema in the Directory Server using ldapmodify, if necessary.

    Loading an LDIF file into the Directory Server will add any new or modified object classes and attributes to the DIT. This step is only necessary when defining dynamic, policy and user attributes. (Global and organization attributes are stored in the Directory Server as XML, not LDAP.) Instructions on extending the LDAP schema can be found in "Extending The Directory Server Schema". See the Sun ONE Directory Server documentation for additional information.

  3. Import the XML service file into Directory Server using amadmin using the --schema or -S option.

    Information on importing an XML service file can be found in "Importing the XML Service File".

  4. Configure a localization properties file and copy it into the <identity_server_root>/SUNWam/locale directory.

    The localization properties file must be created with accurate i18nKey fields that map to names defined in the XML service file. If no localization properties file exists, Identity Server will display the actual attribute names. More information on the localization properties file can be found in "Configuring Localization Properties".

  5. Update the amEntrySpecific.xml or amUser.xml files, if necessary.

    The amEntrySpecific.xml file defines the attributes that will display on the Create, Properties and Search pages specific to each of the Identity Server abstract objects. The amUser.xml file can be modified to add User attributes to the User Service. (Alternately, User attributes can be defined in the actual XML service file in which case, amUser.xml would not need to be modified.) Information on updating amEntrySpecific.xml can be found in Chapter 5 "Identity Management." Information on modifying amUser.xml can be found in "Modifying A Default XML Service File".

  6. Register the service.

    After importing the service into Directory Server, it can be registered and the attributes managed through the Identity Server console. Information on how this can be done is in the Sun ONE Identity Server Administration Guide. Information on how to register using the command line can be found in "Registering The Service".


Creating A Service File

The information in this section corresponds to Step 1, creating an XML service file. The XML service file defines the attributes of an Identity Server service. It must follow the structure defined in the sms.dtd which enforces the service developer to combine attributes into one of five groups, allowing the developer to differentiate between those attributes applicable to, for example, a service instance or a user.


Service File Naming Conventions

When creating a new XML service file, there are some naming conventions that must be followed.

  • The name of a service (other than an authentication module service) as defined in the XML service file can be any string as long as it is unique.

  • The name of an authentication module service as defined in the XML service file must be in the form iPlanetAMAuth<module_name>Service.

  • Any defined authentication level attribute must be configured as iplanet-am-auth-<module_name>-auth-level.


Service Attributes

The sms.dtd requires the service developer to define attributes into one of five groups. These groups differentiate between those attributes applicable to, for example, the Identity Server deployment, a service or a user.


Global Attributes
Global attributes are defined for the entire Identity Server installation and are common to all data trees, service instances and integrated applications within the configuration. Global attributes can not be applied to users, roles or organizations as their purpose is to configure the Identity Server itself. Server names, port numbers, service plug-ins, cache size, and maximum number of threads are examples of global attributes that are configured with one value. For example, when Identity Server performs logging functions, the log files are written into a directory. The location of this directory is defined as a global attribute in the Logging Service and all Identity Server logs, independent of their purpose, are written to it. Identity Server administrators can modify these default values using the Identity Server console. Global attributes are stored in the Directory Server as an XML blob within an attribute of an LDAP object. Therefore, the LDAP schema does not need to be extended to add a new global attribute.


Note

If a service has only global attributes, it can not be registered to an organization nor can a service template be created.



Organization Attributes
Organization attributes are defined and assigned at the organization level. Attributes for an Authentication Service are a good example. When the Authentication Service is registered, attributes are configured depending on the organization to which it is registered. The LDAP Server and the DN To Start User Search would be defined at the organization level as this information would be different depending on the address of an organization's LDAP server and the structure of their DIT, respectively. Organization attributes are stored as an XML blob within an attribute of an LDAP object. Therefore, the LDAP schema does not need to be extended to add a new global attribute.


Note

Organization attributes are not inherited by sub-organizations. Only dynamic and policy attributes can be inherited. For additional information, see "Attribute Inheritance".



Dynamic Attributes
Dynamic attributes are inheritable attributes that work at the role and organization levels as well as the sub-organization and organizational unit levels. Services are assigned to organizations; roles have access to any service assigned to its parent organization. The dynamic attributes are then inherited by users that possess the role or belong to the organization. Because the attributes are assigned to roles or organizations instead of set in a user entry, they are virtual attributes inherited by users using the concept of Class of Service (CoS). When these attributes change, the administrator only has to change them once, in the role or organization, instead of a multitude of times in each user entry.


Note

Dynamic attributes are modeled using class of service (CoS) and roles, both features of the Sun ONE Directory Server. For information on these features, see Appendix B "Directory Server Concepts" or refer to the Sun ONE Directory Server documentation.


An example of a dynamic attribute might be the address of a common mail server. Typically, an entire building might have one mail server so each user would have a mail server attribute in their entry. If the mail server changed, every mail server attribute would have to be updated. If the attribute was in a role that each user in the building possessed, only the attribute in the role would need to be updated. Another example might be the organization's address. Dynamic attributes are stored within the Directory Server as LDAP objects, making it feasible to use traditional LDAP tools to manage them. A Directory Server LDAP schema needs to be defined for these attributes.


Policy Attributes
Policy attributes are a special type of dynamic attribute. The main difference is that policy attributes provide a way to control resource access by defining a user's permissions. These defined permission attributes are then used to create named policy. For example, allowURLList is a named policy that defines a list of URLs a user is allowed to access; *.red.iplanet.com, *.eng.sun.com are the permitted URLs defined as policy attributes. Named policies are assigned to roles or organizations; once assigned, the policy attribute is available in the user entry as an LDAP attribute, making it feasible to use traditional LDAP tools to manage them. (Named policies are not stored within the Directory Server as LDAP objects.) A Directory Server LDAP schema needs to be defined for these attributes.


Note

Currently, Identity Server has only two services that use policy attributes: URL Policy Agent and URL Domain Access.



User Attributes
User attributes belong specifically to a single user. User attributes are not inherited from the role, organization, or sub-organization levels. They are typically different for each user, and any changes to them would affect only the particular user. Examples of user attributes could be an office telephone number, a password or an employee ID. The values of these attributes would be set in the user entry and not in a role or organization. User attributes can be a part of any service but, for convenience, Identity Server has grouped a number of the most widely-used attributes into a service defined by the amUser.xml service file. User attributes are stored within the Directory Server as LDAP objects, making it feasible to use traditional LDAP tools to manage them. A Directory Server LDAP schema needs to be defined for these attributes.


Note

When defining user attributes in an XML service file other than amUser.xml, the service must be explicitly assigned to the user in order to display them on the User's Profile page. In addition, the User Profile Display Option in the Administration Service) must be set to Combined. For more information, see the Sun ONE Identity Server Administration Guide.



Attribute Inheritance

After creating and loading an XML service file, an administrator can assign the service's organization, dynamic and policy attributes by registering it to an identity object and creating a service template. (Any number of services can be assigned to these objects.) Then when a user possesses a role or belongs to an organization which possesses a service, the user inherits the dynamic and policy attributes or the organization, dynamic and policy attributes, respectively. Inheritance only occurs, though, if the service possessed is also explicitly assigned to the user. A user can inherit attributes from multiple roles or parent organizations.


Note

Attributes defined as User have no inheritance; they are set and modified in each User entry. For example, if 70 attributes are defined as User and an organization has two million users, each attribute is stored two million times.



ContainerDefaultTemplateRole Attribute
Dynamic and policy attributes are used in an XML service file if an administrator wants to define a service in which all identity objects, with the specified service assigned to them, would inherit those attributes. After uploading the XML service file and assigning the service to an organization or role, all users in the sub-trees, with the specified service assigned to them, will inherit the dynamic and policy attributes. To accomplish this, Identity Server uses classic CoS (as described in Appendix B "Directory Server Concepts") and role templates. ContainerDefaultTemplateRole is a default filtered role configured for each organization. The filter is objectClass=iplanet-am-managed-person. Since every identity object in Identity Server carries this attribute, every identity in the organization possesses this role. Identity Server then creates a separate CoS template for each registered service which points to the service's default attributes. Any identity who has the role will then get all the dynamic and policy attributes.


Extending The Directory Server Schema

The information in this section corresponds to Step 2, extending the LDAP schema in the Directory Server. When configuring an XML service file for Identity Server, it might also be necessary to modify the Directory Server schema. First, any customized dynamic, policy or user attributes defined in an Identity Server service that are not already defined in the Directory Server schema need to be associated with an LDAP object class. Then the attribute(s) and object class(es) need to be added to the LDAP schema using ldapmodify and an LDIF file as input; thus, the Directory Server can store the data.


Note

The order in which the LDAP schema is extended or the XML service file is loaded into Directory Server is not important.


  1. Create an LDIF file to define any new or modified LDAP object classes and attributes.

  2. Change to the Identity Server bin directory.

    cd <identity_server_root>/SUNWam/bin

  3. Run ldapmodify using the LDIF file as input. The syntax is ldapmodify -D <userid_of_DSmanager> -w <password> -f <path_to_LDIF_file>

    By default, <userid_of_DSmanager> is cn=Directory Manager. If the LDIF was created correctly, the result of this command would be to modify the entry cn=schema.


    Note

    After extending the schema using ldapmodify, it is not necessary to restart the Directory Server but, as ldapmodify is server-specific, the schema needs to be extended on all configured servers. Information on how this is done can be found in the Sun ONE Directory Server documentation.


  4. Run ldapsearch to ensure that the schema has been created. The syntax is ldapsearch -b "cn=schema "-s base -D <userid_of_DSmanager> -w <password> "(objectclass=*)" | grep -i "servicename"

    If the LDIF was created correctly, the result of this command would be a listing of the object classes as illustrated in Code Example 6-1 below.


    Code Example 6-1    Sample LDIF Listing For Mail Service
    objectClasses: ( 1.2.NEW
    NAME 'iplanet-am-sample-mail-service'
    DESC 'iPlanet 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 'user defined' )
    attributeTypes: ( 11.24.1.996.1
    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 'user defined' )


Adding Object Classes To Existing Users

If a new service is created and the service's users already exist, the object classes need to be added to the user entries. In order to do this, Identity Server provides migration scripts for performing batch updates to user entries in the DIT. No LDIF file need be created when using them. These scripts are described in the Sun ONE Identity Server Installation and Configuration Guide. Alternatively, registered services can be added to the user by selecting the service from their Properties page.


Note

To modify user entries using ldapmodify, an LDIF file needs to be created. For information, see the Sun ONE Directory Server documentation. (It is not recommended to use ldapmodify to create entries for Identity Server.)



Verifying The Directory Server Modification

To verify that the Directory Server has been populated correctly, an administrator can use ldapsearch or the following:

  1. Change to the Directory Server install directory:

    cd /<directory_server_root>/slapd-<directory_server_hostname>

  2. Export the Directory Server contents into an LDIF file using

    db2ldif -s <orgnamingattribute=top_level_org_name>

    This command results in the name of a LDIF schema file stored under <directory_server_root>/slapd-slapd-<directory_server_hostname>/ldif which can be viewed to ensure that the new object classes have been created.


Importing the XML Service File

The information in this section corresponds to Step 3, importing an XML service file into the Identity Server.

  1. Change to the Identity Server install directory:

    cd <identity_server_root>/SUNWam/bin

  2. Run following command line application: ./amadmin --runasdn <DN_of_directory_server_administrator> --password <password_directory_server_administrator> --verbose --schema <xml_service_file_path.>

    More information on the amadmin command line tool can be found in the Sun ONE Identity Server Administration Guide.


    Note

    If changing an existing service, the original XML service file needs to be deleted before importing the modified XML service file.



Configuring Localization Properties

The information in this section corresponds to Step 4, configuring a localization properties file. A localization properties file specifies the locale-specific screen text and messages that an administrator or user will see when directed to a service's attribute configuration page. The files are located in the <identity_server_root>/SUNWam/locale/ directory. Code Example 6-2 is the localization properties file for Identity Server's sample mail service.


Code Example 6-2    Sample Mail Service Localization Properties File
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

The localization properties files consist of a series of key/value pairs. The value of each pair will be displayed on the service's Properties page in the Identity Server console. The keys (a1, a2, etc.) map to the i18nKey attribute fields defined for a service in the XML service file. The keys also determine the order in which the fields are displayed on screen, taken in alphabetical and then numerical order (a1, a2 is followed by b1, b2 and so forth). Note that the keys are strings, so a10 comes before a2.


Note

If modifying a localization properties file, Identity Server needs to be restarted. If importing a localization properties file, Identity Server does not need to be restarted.



Identifying The Localization Properties File

Identity Server needs to be able to locate the localization properties file so it is located in the default <identity_server_root>/SUNWam/locale directory. If the file is kept in another directory, the jvm.classpath= entry in the jvm12.conf file needs to be modified to include the new directory path name.


Note

If the jvm12.conf file is modified, the Identity Server server needs to be restarted.



Updating Files For Abstract Objects

For information corresponding to Step 5, updating the amEntrySpecific.xml, see Chapter 5 "Identity Management." For information corresponding to Step 5, updating the amUser.xml, see "XML Files".


Registering The Service

The information in this section corresponds to Step 6, registering a new service to an identity object. The preferred way to register a service is to use the Identity Server console. Information on how this is done can be found in the Sun ONE Identity Server Administration Guide. Alternately, services can be registered using the amadmin command line executable.

  1. Change to the Identity Server install directory:

    cd <identity_server_root>/SUNWam/bin

  2. Run following command line application ./amadmin --runasdn <DN_of_identity_server_administrator> --password <password_identity_server_administrator> --schema <xml_service_file_path.>

    More information on the amadmin command line tool can be found in the Sun ONE Identity Server Administration Guide.



DTD Files

Identity Server contains DTD files which are used to define the structure for XML files used within the Identity Server configuration. The DTDs are located in <identity_server_root>/SUNWam/dtd and include:

  • sms.dtd—which defines the structure for XML service files. Information on this document can be found in "The sms.dtd Structure".

  • amAdmin.dtd—which defines the structure for XML files used to perform batch LDAP operations on the directory tree using the command line tool amAdmin. Information on this document can be found in "The amAdmin.dtd Structure".

  • policy.dtd—defines the structure for XML files used to define policies for servers and services. Information on this document can be found in Chapter 7 "Policy Service."

  • Auth_Module_Properties.dtd—defines the structure for XML files used by each authentication module to specify the properties for the Authentication Service interface. Information on this document can be found in Chapter 3 "Authentication Service."

  • server-config.dtd—defines the structure for serverconfig.xml which details ID, host and port information for all server and user types. Information on this document can be found in "The amAdmin.dtd Structure".


    Caution

    None of these DTD files should be modified in any way. They contain rules and definitions that control how certain operations are performed and any alterations might hinder these operations.



The sms.dtd Structure

The sms.dtd defines the data structure for all XML service files. It is located in the <identity_server_root>/SUNWam/dtd directory. The sms.dtd enforces the developer to define each attributes as one of five schema types which are then stored and managed differently. For instance, some of the attributes are applicable to an entire Identity Server installation (such as a port number or server name), while others are applicable only to individual users (such as a password). The attribute types are:

  • Global

  • Organization

  • Dynamic

  • User

  • Policy

An explanation of the elements defined by the sms.dtd follows. Each element includes a number of XML attributes which are also explained. Identity Server currently supports only about 20% of the elements contained in sms.dtd; this section discusses only those elements.


Note

Customized attribute names in XML service files should be written in lower case as Identity Server converts all attribute names to lower case when reading from the Directory Server.



ServicesConfiguration Element

ServicesConfiguration is the root element of the XML service file. It's immediate sub-element is Service. Code Example 6-3 illustrates the ServicesConfiguration element as defined in a file named sampleMailService.xml.


Code Example 6-3    ServicesConfiguration and Service Element
<ServicesConfiguration>
<Service name="sampleMailService" version="1.0">
<Schema...>
...


Service Element

The Service element defines the schema for a given service. Multiple services can be defined in a single XML file with this element, but it is recommended that only one be defined per XML service file. Currently, Identity Server supports the sub-element Schema which, in turn, defines Identity Server attributes as either Global, Organization, Dynamic, User or Policy. The required XML service attributes for the Service element are the name of the service, such as iPlanetAMLoggingService, and the version number of the XML service file itself. Code Example 6-3 also illustrates the Service element and its attributes.


Schema Element

The Schema element is the parent of the elements that define the service's specific Identity Server attributes (global, organization, dynamic, user or policy) and their default values. The sub-elements can be Global, Organization, Dynamic, User or Policy. The required XML attributes of the Schema element include serviceHierarchy which defines where the service will be displayed in the Identity Server console, i18nFileName which defines the name of the localization properties file, and i18nKey which defines the attribute in the localization properties file from which this particular defined value will be taken.


Note

The Schema element is required in all XML service files.



serviceHierarchy Attribute
When adding a service, this attribute must be defined in order to display the service in the Identity Server console. When a new service is registered, it is dynamically displayed based on this value. The value is a "/" separated string. Code Example 6-4 illustrates the serviceHierarchy attribute as defined in the file named sampleMailService.xml. The name sampleMailService is used to find the localization properties file which defines what will be displayed below the Other Configuration header in the Identity Server console.


Code Example 6-4    i18nFileName, i18nKey and serviceHierarchy Attributes
...
<Schema
serviceHierarchy="/other.configuration/sampleMailService"
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
...


i18nFileName And i18nKey Attributes
These two XML attributes both refer to the localization properties files. The i18nFileName attribute takes a value equal to the name of the localization properties file for the defined service (minus the .properties file extension). The i18nKey is a text string that maps to a property value defined in the localization properties file (specified, as discussed, in the i18nFileName attribute.) For example, Code Example 6-4 defines the name of the properties file as sampleMailservice and the text-based value of the i18nKey maps to its final value as defined in sampleMailservice.properties. The final value is the name of the service as it will be displayed in the Identity Server console; in this case, Sample Mail Service Profile is the name defined in sampleMailservice.properties. More information on the localization properties file can be found in Authentication API For Java ApplicationsAuthentication API For Java ApplicationsChapter 3 "Authentication Service."


Schema Sub-Elements

The next five elements are sub-elements of Schema; they are the declarations of the service's Identity Server attributes. When defining a service, each attribute must be defined as one of these types: Global, Organization, Dynamic, Policy and User. Any configuration (all or none) of these elements can be used depending on the service. Each Identity Server attribute defined within these elements is itself defined by the sub-element AttributeSchema.


Global Element
The Global element defines Identity Server attributes that are modifiable on a platform-wide basis and applicable to all instances of the service in which they are defined. They can define information such as port number, cache size, or number of threads, but Global elements also define a service's LDAP object classes. For additional information, see "Service File Naming Conventions".

serviceObjectClasses Attribute. The serviceObjectClasses attribute is a global attribute in each XML service file that contains dynamic or policy attributes. This optional attribute is used by the SDK to set the object class for the service in the user entries. When an organization registers a service with the serviceObjectClasses attribute defined, the service's dynamic or policy attributes, if any exist, are automatically assigned to any user object which has been assigned the service.


Caution

If the serviceObjectClasses attribute is not specified and the service has defined dynamic or policy attributes, an object class violation is called when an administrator tries to create a user under that organization.


Multiple values can be defined for the serviceObjectClasses attribute. For example, if a service is created with two attributes each from three different object classes, the serviceObjectClasses attribute would need to list all three object classes as DefaultValues. Code Example 6-5 illustrates a serviceObjectClasses attribute with two defined object classes.


Code Example 6-5    serviceObjectClass Defined As Global Element
<AttributeSchema name="serviceObjectClasses"
type="list"
syntax="string"
i18nKey="">
<DefaultValues>
<Value>iplanet-am-sample-mail-service</Value>
<Value>iplanet-am-other-sample-service</Value>
</DefaultValues>
</AttributeSchema>
</Global>
...


Organization Element
The Organization element defines Identity Server attributes that are modifiable per organization or sub-organization. For example, a web hosting environment using Identity Server would have different configuration data defined for each organization it hosts. A service developer would define different values for each organization attribute per organization. These attributes are only accessible using the Identity Server SDK. For additional information, see "Organization Attributes".


Dynamic Element
The Dynamic element defines Identity Server attributes that can be inherited by all user objects. Examples of Dynamic elements would be user-specific session attributes, a building number, or a company mailing address. Dynamic attributes always use the Directory Server features, CoS (Class Of Service) and Roles. For additional information, see "Dynamic Attributes".


User Element
The User element defines Identity Server attributes that exist physically in the user entry. User attributes are not inherited by roles or organizations. Examples include password and employee identification number. They are applied to a specific user only. For additional information, see "User Attributes".


Policy Element
The Policy element defines Identity Server attributes intended to provide privileges. This is the only attribute element that uses the ActionSchema element to define its parameters as opposed to the AttributeSchema element. Generally, privileges are get, post, and put; examples include canChangeSalaryInformation and canForwardEmailAddress. See Code Example 6-7 for an example of a Policy schema definition from the sampleMailService.xml file. For additional information, see "Policy Attributes".


SubSchema Element

The SubSchema element can specify multiple sub-schemas of global information for different defined applications. For example, logging for a calendar application could be separated from logging for a mail service application. The required XML attributes of the SubSchema element include name which defines the name of the sub-schema, inheritance which defines whether this schema can be inherited by one or more nodes on the DIT and maintainPriority which defines whether priority is to be honored among its peer elements.


Note

The SubSchema element is used only in the amEntrySpecific.xml file. It should not be used in any external XML service files.



AttributeSchema Element

The AttributeSchema element is a sub-element of the five schema elements discussed in "Schema Sub-Elements" as well as the SubSchema element described in "SubSchema Element". It defines the structure of each attribute. The sub-elements that qualify the AttributeSchema can include IsOptional?, IsServiceIdentifier?, IsResourceNameAllowed?, IsStatusAttribute?, ChoiceValues?, BooleanValues?, DefaultValues?, or Condition. The XML attributes that define each portion of the attribute value are name, type, uitype, syntax, cosQualifier, rangeStart, rangeEnd, minValue, maxValue, validator, any, and %i18nIndex. Code Example 6-6 illustrates the AttributeSchema element, its attributes and their corresponding values. Note that this example attribute is a Dynamic attribute.


Code Example 6-6    AttributeSchema Element With Attributes 
...

<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>

...



name Attribute
This required XML attribute defines the LDAP name for the attribute. Any string format can be used but attribute names must be in lower-case. Code Example 6-6 defines it with a value of iplanet-am-sample-mail-service-status.


type Attribute
This attribute specifies the kind of value the attribute will take. The default value for type is list but it can be defined as one of the following:

  • single specifies that the user can define one value.

  • list specifies that the user can define a list of values.

  • single_choice specifies that the user can chose a single value from a list of options.

  • multiple_choice specifies that the user can chose multiple values from a list of options.

ChoiceValues Sub-Element. If the type attribute is specified as either single_choice or multiple_choice, the ChoiceValues sub-element must also be defined in the AttributeSchema element. Depending on the type specified, the administrator or user would choose either one or more values from the choices defined. The possible choices are defined in the ChoiceValue element. Code Example 6-6 defines the attribute type as single_choice so the ChoiceValues attribute defines the list of options as Active, Inactive and Deleted.


syntax Attribute
The syntax attribute defines the format of the value. The default value for syntax is string but, it can be defined as one of the following:

  • boolean specifies that the value is either true or false.

  • string specifies that the value can be any string.

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

  • dn specifies that the value is a LDAP Distinguish Name.

  • email specifies that the value is an email address.

  • url specifies that the value is a URL address.

  • numeric specifies that the value is a number.

  • percent specifies that the value is a .

  • number specifies that the value is a number.

  • decimal_number specifies that the value is a number with a decimal point.

  • number_range specifies that the value is a range of numbers.

  • decimal_range specifies that the value is a range of numbers that might include a decimal figure.

DefaultValues Sub-Element. Defining any of these syntax values also necessitates defining a value for the DefaultValue sub-element. A default value will then be displayed in the Identity Server console; this default value can be changed for each organization when creating a new template for the service. For example, all instances of the LDAP Authentication Service use the port attribute so a default value of 389 could be defined in the XML service file. Once registered, this value can be modified for each organization using the Identity Server console. (The default value is also used by integrated applications when a service template has not been registered to an organization.) In the Code Example 6-7, for example, the Save Address Book On Server field will display a default value of false. The user has the option to change the value to true, if desired. (The default value for password would be an encrypted password, generally the same as the one used for Identity Server.)


Code Example 6-7    sms.dtd: ActionSchema Element With Boolean Syntax
...
<AttributeSchema name="iplanet-am-sample-mail-can-save-address-book-on-server"
type="single"
syntax="boolean"
i18nKey="p3">
<DefaultValues>
<Value>false</Value>
</DefaultValues>
</ActionSchema>
...


cosQualifier Attribute
This attribute defines how Identity Server will resolve conflicting cosQualifier attributes assigned to the same user object. This value will appear as a qualifier to the cosAttribute in the LDAP entry of the CoS definition. It can be defined as:

  • default indicates that if there are two conflicting cosQualifier attributes assigned to the same user object, the one with the lowest priority number (0) takes precedence. (The priority level is set in the cosPriority attribute when a new CoS template entry is created for an organization or role. For more information, see "Conflicts and CoS" of ".")

  • override indicates that the CoS template value overrides any value already present in the user entry; that is, CoS takes precedence over the user entry value.

  • merge-schemes indicates that if there are two CoS templates assigned to the same user, then they are merged so that the values are combined and the user gets an aggregation of the CoS templates.


    Note

    The URL Policy Agent service uses merge-schemes to obtain aggregated values for the Allow and Deny attributes. For example, if the Employee Role allows access to */employee.html and the HR Role allows access to */hr.html, a user possessing both of these roles is allowed access to both.


If this attribute is not defined, the default behavior is for the user entry value to override the CoS value in the organization or role. The default value is default. (The operational value is reserved for future use.)


any Attribute
The any attribute specifies whether the attribute for which it is defined will display in the Identity Server console. It has six possible values that can be multiply defined using the "|" (pipe) construct:

  • display specifies that the attribute will display on the user profile page. The attribute is read/write for administrators and regular users.

  • adminDisplay specifies that the attribute will display on the user profile page. It will not appear on an end user page; the attribute is read/write for administrators only.

  • userReadOnly specifies that the attribute is read/write for administrators but is read only for regular users. It is displayed on the user profile pages as a non-editable label for regular users.

  • required specifies that a value for the attribute is required in order for the object to be created. The attribute will display on the Create page with an asterisk.

  • optional specifies that a value for the attribute is not required in order for the object to be created.

  • filter specifies that the attribute will display on the Search page.

The required or optional keywords and the filter and display keyword can be specified with a pipe symbol separating the options (any=required|display or any=optional|display|filter). If the any attribute is set to display, the qualified attribute will display in Identity Server console when the properties for the Create page are displayed. If the any attribute is set to required, an asterisk will display in that attribute's field, thus the administrator or user is required to enter a value for the object to be created in Identity Server console. If the any attribute is set to optional, it will display on the Create page, but users are not required to enter a value in order for the object to be created. If the any attribute is set to filter, the qualified attribute will display as a criteria attribute when Search is clicked from the User page.


%i18nIndex Attribute (i18nKey)
The i18nKey attribute, as defined in "i18nFileName And i18nKey Attributes", is referenced as an entity in the sms.dtd.


Note

If the i18nKey value is blank (that is, " "), the Identity Server console will not display the attribute.



The amAdmin.dtd Structure

The amAdmin.dtd defines the data structure for all XML files which will be used to perform batch LDAP operations on the DIT using amAdmin. It is located in the <identity_server_root>/SUNWam/dtd directory. The command line operations include reads and gets on the attributes as well as creations and deletions of user objects (roles, organizations, users, people containers, and groups). The following sections discuss the elements and attributes of the amAdmin.dtd as well as the sample XML templates installed with Identity Server that use this structure. These samples can be found in <identity_server_root>/SUNWam/samples/ admin/cli/bulk-ops and will be used to illustrate these sections.


Requests Element

The Requests element is the root element of the batch processing XML file. It must contain at least one child element which defines the Identity Server identity objects (Organization, Container, People Container, Role and Group) onto which the actual requests are performed. To enable batch processing, the root element can take more than one set of requests. The Requests element must contain at least one of the following sub-elements:

  • OrganizationRequests

  • ContainerRequests

  • PeopleContainerRequests

  • RoleRequests

  • GroupRequests

  • SchemaRequests

  • ServiceConfigurationRequests

Based on the defined request, the corresponding Identity Server API will be called to perform the operation.


OrganizationRequests Element

The OrganizationRequests element consists of all requests that can be performed on Organization objects. The required XML attribute for this element is the LDAP Distinguished Name (DN) of the organization on which all of the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the defined instance of the Organization object. (Different OrganizationRequests elements can be defined in one document to modify more than one Organization DN.) Code Example 6-8 defines a myriad of objects to be created from the top level organization, o=isp. The sub-elements of OrganizationRequests are:

  • CreateSubOrganization

  • CreatePeopleContainer

  • CreateRole

  • CreateGroup

  • CreatePolicy

  • AssignPolicy

  • UnAssignPolicy

  • CreateServiceTemplate

  • ModifySubOrganization

  • ModifyServiceTemplate

  • DeleteServiceTemplate

  • ModifyPeopleContainer

  • ModifyRole

  • ModifyGroup

  • ModifyPolicy

  • GetSubOrganizations

  • GetPeopleContainers

  • GetRoles

  • GetGroups

  • GetUsers

  • RegisterServices

  • UnregisterServices

  • GetRegisteredServiceNames

  • GetNumberOfServices

  • DeleteRoles

  • DeleteGroups

  • DeletePolicy

  • DeletePeopleContainers

  • DeleteSubOrganizations


ContainerRequests Element

The ContainerRequests element consists of all requests that can be performed on Container objects. The required XML attribute for this element is the DN of the container on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the container. (Different ContainerRequests elements can be defined in one document to modify more than one Container DN.) Code Example 6-8 illustrates how this element can be modeled. The sub-elements of ContainerRequests are:

  • CreateSubContainer

  • CreatePeopleContainer

  • CreateRole

  • CreateGroup

  • CreatePolicy

  • AssignPolicy

  • UnAssignPolicy

  • CreateServiceTemplate

  • ModifyServiceTemplate

  • ModifySubContainer

  • ModifyPeopleContainer

  • ModifyRole

  • GetSubContainers

  • GetPeopleContainers

  • GetRoles

  • GetGroups

  • GetUsers

  • RegisterServices

  • UnregisterServices

  • GetRegisteredServiceNames

  • GetNumberOfServices

  • DeleteRoles

  • DeleteGroups

  • DeletePolicy

  • DeletePeopleContainers

  • DeleteSubContainers


PeopleContainerRequests Element

The PeopleContainerRequests element consists of all requests that can be performed on People Container objects. The required XML attribute for this element is the DN of the container on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the people container. (Different PeopleContainerRequests elements can be defined in one document to modify more than one People Container DN.) Code Example 6-8 illustrates how this element can be modeled. The sub-elements of PeopleContainerRequests are:

  • CreateSubPeopleContainer

  • ModifyPeopleContainer

  • CreateUser

  • ModifyUser

  • GetNumberOfUsers

  • GetUsers

  • GetSubPeopleContainers

  • DeleteUsers

  • DeleteSubPeopleContainers


RoleRequests Element

The RoleRequests element consists of all requests that can be performed on roles. The required XML attribute for this element is the DN of the role on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the role. (Different RoleRequests elements can be defined in one document to modify more than one Role DN.) Code Example 6-8 illustrates how this element can be modeled. The sub-elements of RoleRequests are:

  • CreateServiceTemplate

  • ModifyServiceTemplate

  • AssignPolicy

  • UnAssignPolicy

  • GetNumberOfUsers

  • GetUsers

  • AddUsers


GroupRequests Element

The GroupRequests element consists of all requests that can be performed on group objects. The required XML attribute for this element is the DN of the group on which the sub-element requests will be performed. This element can have one or more sub-elements which perform their operations on the same instance of the group. (Different GroupRequests elements can be defined in one document to modify more than one Group DN.) Code Example 6-8 illustrates how this element can be modeled. The sub-elements of GroupRequests are:

  • CreateSubGroup

  • GetSubGroups

  • GetNumberOfUsers

  • GetUsers

  • AddUsers

  • DeleteSubGroups


AttributeValuePair Element

The AttributeValuePair element can be a sub-element of many of the following batch processing requests. It can have two sub-elements, neither of which can themselves have sub-elements. The Attribute sub-element must be empty while the Value sub-element takes a default value to display in the Identity Server console. The Attribute sub-element takes a required XML attribute called name. The value of name is the attribute name which is equal to one string without spaces; no sub-elements are allowed. Code Example 6-13 illustrates how an attribute/value pair would be added to a sub-organization.


Create<Object> Elements

The CreateSubOrganization, CreateUser, CreateGroup, CreateSubContainer, CreatePeopleContainer, CreateSubGroup, CreateSubPeopleContainer and CreateRole elements create a sub-organization, user, group, sub-container, people container, sub-group, sub-people container and role, respectively. The object is created in the DN that is defined in the second-level <Object>Requests element under which the Create<Object> element is defined. AttributeValuePair may be defined as a sub-element (or not). The required XML attribute for each element is createDN; it takes the DN of the object to be created. Code Example 6-8 illustrates an example of some of these elements.


Code Example 6-8    Portion of Batch Processing File createRequests.xml
<Requests>
<OrganizationRequests DN="dc=example,dc=com">

<CreateSubOrganization createDN="o=suborg,dc=example,dc=com"/>
<CreatePeopleContainer createDN="ou=People,dc=example,dc=com"/>
<CreateRole createDN="cn=ManagerRole,dc=example,dc=com"/>
<CreateRole createDN="cn=EmployeeRole,dc=example,dc=com"/>
<CreateGroup createDN="ou=ContractorsGroup,dc=example,dc=com"/>
<CreateGroup createDN="ou=EmployeesGroup,dc=example,dc=com"/>

</Requests>   
...


CreatePolicy Element
The CreatePolicy element creates one or more policy attributes. The Policy sub-element defines the named policy. The required XML attribute is createDN which takes the DN of the organization where the policy will be created. This and the following nested elements are all illustrated in Code Example 6-9.

Policy Element. The Policy sub-element defines the permissions or rules of the policy. It can take one or more of the Rule sub-elements. The required XML attribute is name which specifies the name of the policy. The serviceName attribute, which identifies the service to which the named policy applies, is an optional XML attribute.

Rule Element. The Rule sub-element defines a specific permission of the policy. Rule can take three sub-elements. The required XML attribute is name which defines a name for the rule. The three sub-elements are:

  • ServiceName Element

    The ServiceName sub-element defines the service for which a rule has been created. There are no sub-elements; the ServiceName element itself must be empty. The required XML attribute is name which takes a string value.

  • ResourceName Element

    The ResourceName sub-element defines the domain for which this permission is being defined. There are no sub-elements; the ResourceName element itself must be empty. The required XML attribute is name which takes a string value.

  • AttributeValuePair Element

    The AttributeValuePair sub-element defines the action names and corresponding action values of the rule. For additional information, see "Delete<Object> Elements".


    Code Example 6-9    Portion of Batch Processing File createPolicyOrg.xml  
    ...
    <Requests>
    <OrganizationRequests DN="o=isp">

    <CreatePolicy createDN="o=example.com,o=isp">
    <Policy name="urlpolicy" serviceName="iPlanetAMWebAgentService">
    <Rule name="Manager Rule">
    <ServiceName name="iPlanetAMWebAgentService"/>
    <ResourceName name="*.example.com"/>
    <AttributeValuePair>
    <Attribute name="permission"/>
    <Value>iplanet-am-web-agent-access-allow-list</Value>
    </AttributeValuePair>
    </Rule>
    <Rule name="engManager Rule">
    <ServiceName name="iPlanetAMWebAgentService"/>
    <ResourceName name="*.example.com"/>
    <AttributeValuePair>
    <Attribute name="permission"/>
    <Value>iplanet-am-web-agent-access-allow-list</Value>
    </AttributeValuePair>
    </Rule>
    </Policy>
    </CreatePolicy>
    </OrganizationRequests>
    </Requests>
    ...


CreateServiceTemplate Element
The CreateServiceTemplate element creates a service template for the organization defined in the second-level Requests element. There are no sub-elements; the CreateServiceTemplate element itself must be empty. The required XML attribute is serviceName which takes a string value. Code Example 6-10 illustrates a service template being created for sun.com.


Code Example 6-10    Portion of Batch Processing File createServiceTemplates.xml
<Requests>
<OrganizationRequests DN="o=example.com,o=isp">

<CreateServiceTemplate serviceName="sampleMailService"/>

</OrganizationRequests>
</Requests>   
...


Delete<Object> Elements

The DeleteSubOrganizations, DeleteUsers, DeleteGroups, DeleteSubContainers, DeletePeopleContainers, DeleteSubGroups, DeleteSubPeopleContainers, and DeleteRoles elements delete a sub-organization, user, group, sub-container, people container, sub-group, sub-people container and role, respectively. The object is deleted from the DN that is defined in the second-level <Object>Requests element under which the Delete<Object> element is defined. DeleteSubOrganizations, DeleteUsers, DeleteGroups, DeleteSubContainers, DeletePeopleContainers, DeleteSubGroups, DeleteSubPeopleContainers and DeleteRoles take a sub-element DN; only six of the listed elements have the XML attribute deleteRecursively. (DeleteUsers and DeleteRoles do not have this option; they have no qualifying XML attribute.) If deleteRecursively is set to false, accidental deletion of all sub-trees can be avoided; it's default value is false. The DN sub-element takes a character value equal to the DN of the object to be deleted. Code Example 6-11 illustrates an example of some of these elements.


Code Example 6-11    Portion of Batch Processing File deleteOrgRequests.xml
<OrganizationRequests DN="o=isp">

<DeleteRoles>
<DN>cn=ManagerRole,o=example.com,o=isp</DN>
<DN>cn=EmployeeRole,o=example.com,o=isp</DN>
</DeleteRoles>

<DeleteGroups deleteRecursively="true">
<DN>cn=EmployeesGroup,o=example.com,o=isp</DN>
<DN>cn=ContractorsGroup,o=example.com,o=isp</DN>
</DeleteGroups>

<DeletePeopleContainers deleteRecursively="true">
<DN>ou=People1,o=example.com,o=isp</DN>
</DeletePeopleContainers>

<DeleteSubOrganizations deleteRecursively="true">
<DN>o=example.com,o=isp</DN>
</DeleteSubOrganizations>

</OrganizationRequests>
</Requests>   
...


DeletePolicy Element
The DeletePolicy element takes the sub-element PolicyName. The PolicyName element has no sub-elements; it must be empty. It has a required XML attribute name which takes a character value equal to the name of the policy. The DeletePolicy element itself takes a required XML attribute: deleteDN. It takes a value equal to the DN of the policy to be deleted.


DeleteServiceTemplate Element
The DeleteServiceTemplate element deletes the specified service template. There are no sub-elements; the DeleteServiceTemplate element itself must be empty. The required XML attributes are serviceName which takes a string value and schemaType which defines the attribute group (Global, Organization, Dynamic, User or Policy). Code Example 6-12 illustrates how this element is formatted.


Code Example 6-12    Portion of Batch Processing File deleteServiceTemplates.xml
<OrganizationRequests DN="o=example.com,o=isp">
<DeleteServiceTemplate serviceName="iPlanetAMAuthLDAPService"
schemaType="organization">

</DeleteServiceTemplate>
</OrganizationRequests>
</Requests>   


Modify<Object> Elements

The ModifyPeopleContainer, ModifySubContainer, ModifySubOrganization and ModifyRole, ModifyGroup elements change the specified object. AttributeValuePair can be defined as a sub-element of the first four listed elements. (The ModifyGroup element can have no sub-elements; it must be empty.) The required XML attribute is modifyDN which takes the DN of the object to be modified. Code Example 6-13 illustrates how these elements can be modeled.


Code Example 6-13    Portion of Batch Processing File modifyRequests1.xml 
<Requests>
<OrganizationRequests DN="o=isp">

<ModifySubOrganization modifyDN="o=sun.com,o=isp">
<AttributeValuePair>
<Attribute name="Description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifySubOrganization>

<ModifyPeopleContainer modifyDN="ou=People,o=example.com">
<AttributeValuePair>
<Attribute name="Description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifyPeopleContainer>

<ModifyRole modifyDN="cn=ManagerRole,o=example.com">
<AttributeValuePair>
<Attribute name="iplanet-am-role-description"/>
<Value>DSAME Modify</Value>
</AttributeValuePair>
</ModifyRole>

</OrganizationRequests>
</Requests>   


ModifyServiceTemplate Element
The ModifyServiceTemplate element changes a specified service template. AttributeValuePair must be defined as a sub-element of ModifyServiceTemplate to change the values. The required XML attribute is serviceName which takes a string value and schemaType. Code Example 6-14 illustrates this element.


Code Example 6-14    Portion of Batch Processing File modifyServiceTemplates.xml
...
<Requests>
<OrganizationRequests DN="o=example.com,o=isp">

<ModifyServiceTemplate serviceName="sampleMailService">
<AttributeValuePair>
<Attribute name="iplanet-am-sample-mail-sentmessages-folder"/>
<Value>Hello Mail Sent</Value>
</AttributeValuePair>
</ModifyServiceTemplate>
</OrganizationRequests>
</Requests>   


Get<Object> Elements

The GetSubOrganizations, GetUsers, GetGroups, GetSubContainers, GetPeopleContainers and GetRoles elements get the specified object. A DN may be defined as a sub-element (or not). If none is specified, ALL of the specified objects at all levels within the organization defined in the second-level Requests element will be returned. The required XML attribute for all but GetGroups and GetRoles is DNsOnly and takes a true or false value. The required XML attribute of GetGroups and GetRoles is level which takes a value of either ONE_LEVEL or SUB_TREE. ONE_LEVEL will retrieve just the groups at that node level; SUB-TREE gets groups at the node level and all those underneath it. Code Example 6-15 illustrates how these elements can be modeled.


DNs Only Attribute
For all objects using the DNsOnly attribute, the Get elements work as stated below:

  • If the element has the required XML attribute DNsOnly set to true and no sub-element DN is specified, only the DNs of the objects asked for will be returned.

  • If the element has the required XML attribute DNsOnly set to false and no sub-element DN is specified, the entire object (a DN with attribute/value pairs) will be returned.

  • If sub-element DNs are specified, the entire object will always be returned whether the required XML attribute DNsOnly is set to true or false.


    Code Example 6-15    Portion of Batch Processing File getRequests.xml

    <OrganizationRequests DN="o=isp">
       
       <GetSubOrganizations DNsOnly="false">
        <DN>o=example1.com,o=isp</DN>
        <DN>o=example2.com,o=isp</DN>
       </GetSubOrganizations>
       
       <GetPeopleContainers DNsOnly="false">
        <DN>ou=People,o=example1.com,o=isp</DN>
        <DN>ou=People,o=example2.com,o=isp</DN>
       </GetPeopleContainers>
       
       <GetRoles level="SUB_TREE"/>
       
       <GetGroups level="SUB_TREE"/>
       
       <GetUsers DNsOnly="false">
        <DN>cn=puser,ou=People,o=example1.com,o=isp</DN>
       </GetUsers>
       
    </OrganizationRequests>
    ...


GetService Elements

The GetRegisteredServiceNames and GetNumberOfServices elements retrieve registered services and total number of registered services, respectively. The organization from which this information is retrieved is specified in the OrganizationRequests element. All three elements have no sub-elements or attributes; the elements themselves must be empty. Code Example 6-16 illustrates how the GetRegisteredServiceNames element is modeled.


Code Example 6-16    Batch Processing File getRegisteredServiceNames.xml

<OrganizationRequests DN="o=example.com,o=isp">
<GetRegisteredServiceNames/>
</OrganizationRequests>

</Requests>   


ActionServices Elements

The RegisterServices and UnregisterServices elements perform the requested action on the service defined in the OrganizationRequests element. All elements take a sub-element Service_Name but have no XML attribute. The Service_Name element takes a character value equal to the name of the service. One or more Service_Name sub-elements can be specified.


Service Action Caveats

  • The XML service file for the service must be loaded using the command line interface amadmin before a service can be acted upon.

  • If no Service_Name element is specified or, in the case of UnregisterServices, the service was not previously registered, the request is ignored.

  • If no Service_Name element is specified, the request will be ignored.

Code Example 6-17 illustrates how these elements can be modeled.


Code Example 6-17    Portion of Batch Processing File registerRequests.xml
<OrganizationRequests DN="o=example.com,o=isp">

<RegisterServices>
<Service_Name>sampleMailService</Service_Name>
</RegisterServices>

</OrganizationRequests>
</Requests>   


AssignPolicy and UnAssignPolicy Elements

The AssignPolicy and UnAssignPolicy elements take the sub-element PolicyName. The PolicyName element has no sub-elements; it must be empty. It has a required XML attribute name which takes a character value equal to the name of the policy. The required XML attribute of AssignPolicy and UnAssignPolicy is policyDN which takes a value equal to the DN of the policy to be acted upon.


SchemaRequests Element

The SchemaRequests element consists of all requests that can be performed on the default values of the DSAME schema. It has two required XML attributes: serviceName and SchemaType. serviceName takes a value equal to the name of the service where the schema lives and SchemaType defines the attribute group (Global, Organization, Dynamic, User or Policy). This element can have zero or more sub-elements. The sub-elements of SchemaRequests are:

  • RemoveDefaultValues Element

  • ModifyDefaultValues Element

  • AddDefaultValues Element

  • GetServiceDefaultValues


RemoveDefaultValues Element
The RemoveDefaultValues element removes the default values from the schema specified in the parent SchemaRequests element. It takes a sub-element of Attribute which specifies the name of the attribute to be removed. The Attribute sub-element itself must be empty; it takes no sub-element. There is no required XML attribute.


Code Example 6-18    Portion of Batch Processing File removeschemaRequests.xml
<SchemaRequests serviceName="iPlanetAMUserService"
    SchemaType="dynamic">
<RemoveDefaultValues>
<Attribute name="preferredlanguage"/>
</RemoveDefaultValues>
</SchemaRequests>
</Requests>   


AddDefaultValues and ModifyDefaultValues Elements
The AddDefaultValues and ModifyDefaultValues elements add or change the default values from the specified schema, respectively. They take a sub-element of AttributeValuePair which specifies the name of the attribute and the new default value; one or more attribute/value pairs can be defined. Code Example 6-19 illustrates how this element can be modeled.


Code Example 6-19    Portion of Batch Processing File addschemaRequests.xml
<SchemaRequests serviceName="iPlanetAMUserService"
    SchemaType="dynamic">
<AddDefaultValues>

<AttributeValuePair>
<Attribute name="iplanet-am-user-auth-modules"/>
<Value>Cert</Value>
</AttributeValuePair>

</AddDefaultValues>
</SchemaRequests>
</Requests>   


GetServiceDefaultValues Element
The GetServiceDefaultValues element retrieves the default values from the schema specified in the parent SchemaRequests element. There are no sub-elements; the GetServiceDefaultValues element itself must be empty. There is also no required XML attribute.


ServiceConfigurationRequests Element

The ServiceConfigurationRequests element is reserved for future use.



XML Files


Identity Server uses XML files to manage service attributes as well as perform service operations on service attributes. It does not implement any behavior or dynamically generate any code to interpret the attributes; it can only set or get attribute values. In addition to XML files that define service attributes, Identity Server also includes XML templates that can be used for batch processing. This section contains information on these types of XML files.


Default XML Service Files

Identity Server installs services that manage the attributes of its internal software components. The Identity Server console manages the attributes for these services; in addition, Identity Server provides code implementations to use them. These default XML service files are based on the sms.dtd and are located in <identity_server_root>/SUNWam/config/xml. They include:

  • amAdminConsole.xml—Defines attributes for the Administration service.

  • amAuth.xml—Defines attributes for the Core Authentication service.

  • amAuthAnonymous.xml—Defines attributes for the Anonymous Authentication service.

  • amAuthCert.xml—Defines attributes for the Certificate-based Authentication service.

  • amAuthLDAP.xml—Defines attributes for the LDAP Authentication service.

  • amAuthRadius.xml—Defines attributes for the Radius Authentication service.

  • amAuthSafeWord.xml—Defines attributes for the SafeWord Authentication service.

  • amAuthSecurID.xml—Defines attributes for the SecurID Authentication service.

  • amAuthUnix.xml—Defines attributes for the Unix Authentication service.

  • amClientDetection.xml—Defines attributes for the Client Detection service.

  • amDomainURLAccess.xml—Defines attributes for the URL Access Policy service.

  • amDSS.xml—Defines attributes for the Certificate Security service.

  • amEntrySpecific.xml—Defines attributes for the displaying attributes on the Create, Properties and Search pages for a custom service.

  • amLogging.xml—Defines attributes for the Logging service.

  • amMembership.xml—Defines attributes for the Membership Authentication service.

  • amNaming.xml—Defines attributes for the Naming service.

  • amPlatform.xml—Defines attributes for the Platform service.

  • amPolicy.xml—Defines attributes for the Policy service.

  • amSAML.xml—Defines attributes for the SAML service.

  • amSession.xml—Defines attributes for the Session service.

  • amUser.xml—Defines attributes for the User service.

  • amWebAgent.xml—Defines attributes for the web agents.


Modifying A Default XML Service File

Administrators can display and manage any attribute in the Identity Server console using XML service files. The new attribute(s) would need to be added to an existing XML service file. Alternately, they can be grouped into a new service by creating a new XML service file although the simplest way to add an attribute is just to extend an existing XML service file. For example, an administrator wants to manage the nsaccountlock attribute which will give users the option of locking the account it defines. To manage it through Identity Server, nsaccountlock must be described in a service. One option would be to add it to the amUser.xml service, iPlanetAMUserService. This is the service that, by default, includes many common attributes from the inetOrgPerson and inetUser object classes. Following is an example of how to add the nsaccountlock attribute to the amUser.xml service file.

  1. Add the following code to the SubSchema name=User element in <identity_server_root>/SUNWam/config/xml/amUser.xml.


    Code Example 6-20    nsaccountlock Example Attribute  
    <AttributeSchema name="nsaccountlock"
    type="single_choice"
    syntax="string"
    any="filter"
    isChangeableByUser="yes"
    i18nKey="u13">
    <ChoiceValues>
    <Value>true</Value>
    <Value>false</Value>
    </ChoiceValues>
    <DefaultValues>
    <Value>false</Value>
    </DefaultValues>
    </AttributeSchema>
    ...

  2. Update the <identity_server_root>/SUNWam/locale/en_US/ amUser.properties file with the new i18nKey tag u13 including the text to be used for display.


    Code Example 6-21    User Account Locked Example i18nKey

  3. Remove the service ou=iPlanetAMUserService,ou=services,dc=sun,dc=com using the command line tool amadmin.

    For information on the amadmin command line syntax, see Sun ONE Identity Server Administration Guide.

  4. Reload the user service, amUser.xml, using the command line tool amadmin.

    For information on the amadmin command line syntax, see Sun ONE Identity Server Administration Guide.


    Note

    When modifying a default XML service file, be sure to also modify the Directory Server by extending the LDAP schema, if necessary. For more information, see "Service Definition".



Batch Processing XML Files

The --data or -t option of amadmin is used to perform batch processing using the command line. Batch processing XML templates have been installed and can be used to help an administrator to:

  • Create, delete and 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, register and un-register services.

  • Get registered service names or the total number of registered services for an existing organization.

  • Execute requests in multiple XML files.

The preferred way to perform most of these functions singularly is to use the Identity Server console. The batch processing templates have been provided for ease of use with bulk updates although they can also be used for single configuration updates. This section provides an overview of the batch processing templates which can be modified to perform batch updates on user objects (groups, users, roles, people containers, etc.) in the Directory Server.


Note

Only XML files can be used as input for the amadmin tool. If an administrator wants to populate the DIT with user objects, or perform batch reads (gets) or deletes on the DIT, then the necessary XML input files, based on the amadmin.dtd or sms.dtd, must be written.



Batch Processing XML Templates

All of the batch processing XML files perform operations on the DIT; they create, delete, or get attribute information on user objects. The batch processing XML templates provided with Identity Server include:

  • ContCreateServiceTemplate.xml—Creates a service template for a specific container object.

  • ContModifyRequests1.xml—Adds new attributes for a sub-container object.

  • ContModifyRequests2.xml—Adds new attributes for a people container object.

  • ContModifyRequests3.xml—Adds new attributes for a sub-container object.

  • ContModifyRequests4.xml—Adds new attributes to a role object.

  • ContassignPolicyRequests.xml—Assigns policy to a specific container object.

  • ContunassignPolicyRequests.xml—Removes an assigned policy from a specific container object.

  • PCModifyRequests1.xml—Adds new attributes to a people container object.

  • PCModifyUserRequests.xml—Adds new attributes to users in a people container object.

  • RoleCreateServiceTemplates.xml—Creates a service template for a role object.

  • RoleassignPolicyRequests.xml—Assigns policy to a role object.

  • RolemodifyServiceTemplates.xml—Adds new attributes to a service template for a specific role object.

  • RoleunassignPolicyRequests.xml—Removes policy from a specific role object.

  • addChoiceValuesRequest.xml—Adds a selection of values the user can chose from to an existing service attribute.

  • addschemaRequests.xml—Adds a default value to an existing service attribute.

  • addserviceConfigurationRequests.xml—This is reserved for future use.

  • createPolicyOrg.xml—Creates policy for an organization object.

  • createRequests.xml—Creates a multitude of objects in the DS.

  • createServiceTemplates.xml—Creates a service template for an organization object.

  • deleteGroupRequests.xml—Deletes all objects under a specific group container.

  • deleteOrgRequests.xml—Deletes a multitude of objects under a specific organization.

  • deletePCRequests.xml—Deletes a multitude of objects under a specific people container.

  • deleteServiceTemplates.xml—Deletes a service template under a specific organization.

  • deleteserviceConfigurationRequests.xml—This is reserved for future use.

  • getNumOfServices.xml—Passes a listing of an organization's total number of registered services.

  • getRegisteredServices.xml—Passes a listing of an organization's registered services.

  • getRequests.xml—Passes information about a multitude of objects in a specific organization.

  • modifyRequests1.xml—Adds new attributes to a number of objects in a specific organization.

  • modifyRequests2.xml—Adds new attributes to a people container object in a specific organization.

  • modifyRequests3.xml—Adds new attributes to a role object in a specific organization.

  • modifyServiceTemplates.xml—Modifies existing attributes in a service registered to a specific organization.

  • modifyschemaRequests.xml—Adds new attributes to a number of objects in a specific organization.

  • registerRequests.xml—Registers a service to an existing organization. (This service must have been previously imported.)

  • removeChoiceValueRequests.xml—Removes the values a user can choose from in an existing attribute in a specific service.

  • removeschemaRequests.xml—Removes the default value of an existing attribute in a specific service.

  • unassignPolicyRequests.xml—Removes an assigned policy from a specific organization.

  • unregisterRequests.xml—Unregisters a service from an existing organization. (This service must have been previously imported and registered.)

These XML templates follow the structure defined by the amAdmin.dtd. They are located in <identity_server_root>/SUNWam/samples/admin/cli/bulk-ops.


Modifying A Batch Processing XML Template

Any of the templates discussed above can be modified to best suit the desired operation. Choose the file that performs the request, modify the elements and attributes according to the service and use the amadmin executable to upload the changes to the Directory Server.


Note

Be aware that creations of roles, groups, and organizations is a time-intensive operation.



Customizing User Pages

The User profile page and what attributes it displays will vary, depending on what the service developer defines. By default, every attribute in the amUser.xml file that has an i18nKey attribute specified and the any attribute set to display (any=display) will display in the Identity Server console. Alternately, if an attribute is specified to be of type User in another XML service file, the Identity Server console will also display it if the service is assigned to the user. Thus, User display pages in the Identity Server console can be modified to add new attributes in either of two ways:

  • The User attribute schema definition in the specific XML service file can be modified.

  • A new User schema attribute definition can be added to the User service (the amUser.xml service file).

For information on modifying XML service files, see "Modifying A Default XML Service File".


Note

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




Service Management SDK


The Identity Server provides a Java API for service management. These interfaces can be used by developers to register services and applications, and manage their configuration data.


Note The Identity Server Javadocs can be accessed from any browser by copying the complete <identity_server_root>/SUNWam/docs/ directory into the <identity_server_root>/SUNWam/public_html directory and pointing the browser to http://<server_name.domain_name>:<port>/docs/index.html.



Previous     Contents     Index     Next     
Copyright 2002   Sun Microsystems, Inc. All rights reserved.

Last Updated December 02, 2002