Policy Definition Type Document

Once a policy is created and configured, it is stored in Directory Server in XML. In Directory Server, the XML-encoded data is stored in one place. Although policy is defined and configured using the amAdmin.dtd (or the console), it is actually stored in Directory Server as XML that is based on the policy.dtd . The policy.dtd contains the policy element tags extracted from the amAdmin.dtd (without the policy creation tags). So, when the Policy Service loads policies from Directory Server, it parses the XML based on the policy.dtd. The amAdmin.dtd is only used when creating policy with the command line. This section describes the structure of policy.dtd. The policy.dtd exists in the following location:

AccessManager-base/SUNWam/dtd (Solairs)
AccessManager-base/identity/dtd (Linux)

Throughout the rest of this chapter, only the Solaris directory information will be given. Please note that the directory structure for Linux is different.

Policy Element

Policy is the root element that defines the permissions or rules of a policy and to whom/what the rule applies or the subject. It also defines whether or not the policy is a referral (delegated) policy and whether there are any restrictions (or conditions) to the policy. It may contain one or more of the following sub-elements: Rule, Conditions, Subjects,Referrals, or response providers. The required XML attribute is name which specifies the name of the policy. The referralPolicy attribute identifies whether or not the policy is a referral policy; it defaults to a normal policy if not defined. Optional XML attributes include name and description.

When tagging a policy as referral, subjects and conditions are ignored during policy evaluation. Conversely, when tagging a policy as normal, any Referrals are ignored during policy evaluation.

Rule Element

The Rule element defines the specifics of the policy and can take three sub-elements: ServiceName, ResourceName , or AttributeValuePair. It defines the type of service or application for which the policy has been created as well as the resource name and the actions which are performed on it. A rule can be defined without any actions; for example, a referral policy rule doesn’t have any actions.

It is acceptable to have a defined policy that does not include a defined ResourceName element.

ServiceName Element

The ServiceName element defines the name of the service to which the policy applies. This element represents the service type. It contains no other elements. The value is exactly as that defined in the service’s XML file (based on the sms.dtd). The XML service attribute for the ServiceName element is the name of the service (which takes a string value).

ResourceName Element

The ResourceName element defines the object that will be acted upon. The policy has been specifically configured to protect this object. It contains no other elements. The XML service attribute for the ResourceName element is the name of the object. Examples of a ResourceName might be http://www.sunone.com:8080/images on a web server or ldap://sunone.com:389/dc=example,dc=com on a directory server. A more specific resource might be salary://uid=jsmith,ou=people,dc=example,dc=com where the object being acted upon is the salary information of John Smith.

AttributeValuePair Element

The AttributeValuePair element defines an action and its values. It is used as a sub-element to Subject Element, Referral Element and Condition Element. It contains both the Attribute and Value elements and no XML service attributes.

Attribute Element

The Attribute element defines the name of the action. An action is an operation or event that is performed on a resource. POST or GET are actions performed on web server resources, READ or SEARCH are actions performed on directory server resources. The Attribute element must be paired with a Value element. The Attribute element itself contains no other elements. The XML service attribute for the Attribute element is the name of the action.

Value Element

The Value element defines the action values. Allow/deny or yes/no are examples of action values. Other action values can be either boolean, numeric, or strings. The values are defined in the service’s XML file (based on the sms.dtd). The Value element contains no other elements and it contains no XML service attributes.

Deny rules always take precedence over allow rules. For example, if one policy denies access and another allows it, the result is a deny (provided all other conditions for both policies are met). It is recommended that deny policies be used with extreme caution as they can lead to potential conflicts. If explicit deny rules are used, policies assigned to a user through different subjects (such as role and/or group membership) may result in denied access. Typically, the policy definition process should only use allow rules. The default deny may be used when no other policies apply.

Subjects Element

The Subjects sub-element identifies a collection of principals to which the policy applies; this collection is chosen based on membership in a group, ownership of a role or individual users. It takes the Subject sub-element. The XML attributes that can be defined are:

name. This defines a name for the collection.

description. This defines a description of the subject

includeType. This is not currently used.

Subject Element

The Subject sub-element identifies a collection of principals to which the policy applies; this collection pinpoints more specific objects from the collection defined by the Subjects element. Membership can be based on roles, group membership or simply a listing of individual users. It contains a sub-element, the AttributeValuePair Element. The required XML attribute is type, which identifies a generic collection of objects from which the specifically defined subjects are taken. Other XML attributes include name which defines a name for the collection and includeType which defines whether the collection is as defined, or whether the policy applies to users who are NOT members of the subject.

When multiple subjects are defined, at least one of the subjects should apply to the user for the policy to apply. When a subject is defined with includeType set to false, the user should not be a member of that subject for the policy to apply.

Referrals Element

The Referrals sub-element identifies a collection of policy referrals. It takes the Referral sub-element. The XML attributes it can be defined with are name which defines a name for the collection and description which takes a description.

Referral Element

The Referral sub-element identifies a specific policy referral. It takes as a sub-element the AttributeValuePair Element. It’s required XML attribute is type which identifies a generic collection of assignments from which the specifically defined referrals are taken. It can also include the name attribute which defines a name for the collection.

Conditions Element

The Conditions sub-element identifies a collection of policy restrictions (time range, authentication level, and so forth). It must contain one or more of the Condition sub-element. The XML attributes it can be defined with are name which defines a name for the collection and description which takes a description.

The conditions element is an optional element in a policy.

Condition Element

The Condition sub-element identifies a specific policy restriction (time range, authentication level, and sor forth). It takes as a sub-element the AttributeValuePair Element. Its required XML attribute is type which identifies a generic collection of restrictions from which the specifically defined conditions are taken. It can also include the name attribute which defines a name for the collection.