Use the GetPolicy procedure of the Managed Active Directory namespace to obtain the permissions and other policy elements for an object.
When system objects such as organizational units, groups, users, and Web sites are created, it is usually necessary to apply appropriate security permissions to the newly created object. In addition, it is often necessary to create additional objects that belong to the newly created object, and apply security settings to these additional child objects.
The GetPolicy procedure defines:
Organizational units can be nested to any depth.
<request> <procedure> <execute namespace="Managed Active Directory" procedure="GetPolicy"> <executeData> <policyName>reseller</policyName> <containerPath>LDAP://ou=Reseller,ou=Hosting,dc=contoso,dc=com</containerPath> <objectName>ResellerGuy</objectName> <objectType>user</objectType> </executeData> </execute> </procedure> </request>
The following input is valid for this request:
Use the <policyName> element to specify the type of organization for this policy. Possible types are:
If you do not include this element, the request uses the default value. The default value does little except to create the requested object. When calling GetPolicy with <objectType> equal to the organization, <policyName> specifies the type of organizational unit being created. For other <objectType> values, then <policyName> refers to the type of the owner organization specified by <containerPath>.
Use the <containerPath> element when creating the hosting organizational unit to specify the Lightweight Directory Access Protocol (LDAP) path of the domain in which Hosting is to be created. In all other cases, use <containerPath> to specify the LDAP path that refers to an organizational unit created by CreateOrganization. This parameter tells GetPolicy what the parent of the newly created object should be. In the case of Web sites, services, and directories, the <containerPath> refers to an owner relationship rather than an Active Directory container relationship.
Use the <objectName> element to specify the name of the object on which to get the policy.
Use the <objectType> element to specify the type of object on which to get the policy. The object type can be user, org, group, webService, webSite, or webDir. The user, org, and group types refer to Active Directory object types. The webService type refers to the W3SVC and MSFTPSVC metabase objects, for which GetPolicy specifies security settings. The webSite type refers to a Web site or File Transfer Protocol (FTP) site metabase object. The webDir type refers to a file system directory on the hard disk of the server.
Use the <objectPath> element to specify the LDAP path as an alternative way of providing the <containerPath> and <objectName> parameters. If this parameter is specified, the <objectName> is taken from the first component of the LDAP path, and the remaining components compose the <containerPath>.
The following topics provide additional information about how GetPolicy is implemented.
How to read the GetPolicy procedure
A tag named <policies> within the <procedureData> inside of GetPolicy contains all of the essential policy information. When a call is made to GetPolicy, the system looks in <policies> for a <policy> tag whose policyName attribute matches the <policyName> that was passed in as a parameter. The system then looks within that <policy> element for a tag whose name is the same as the <objectType> passed in as a parameter.
If there is more than one such element, as is the case with the <webDir> elements in the hosting policy, all of them are returned. There will be at least one attribute ("type" in the case of <webDir>) that differs among the returned elements.
After one or more elements that match the provided <policyName> and <objectType> have been identified, GetPolicy performs two more operations before returning the data. The first operation is name expansion. The second operation is expansion of any <trusteeGroupNameGrant> and <trusteeWebGroupNameGrant> elements. The third operation is calculating and assigning a "path" attribute to each org, group, and user element.
Every call to GetPolicy provides an <objectName> and a <containerPath>, although these items can be optionally provided in the form of a single <objectPath> which implies both <objectName> and <containerPath>.
The <containerPath> is further converted by GetPolicy into three component pieces: the name of the parent, the distinguished name (also known as DN) of the parent (which is the LDAP path minus the "LDAP://" portion). To use the supplied pieces, everywhere in the selected policy element that a name in square brackets appears, the square brackets and the text within are replaced as follows:
The following excerpt shows how this works for a <user> object created within a reseller:
<policy policyName="reseller"> ... <user name="[self]"> <memberOfGroup name= "LDAP://cn=AllUsers@[parent],ou=Services,[parentDN]" /> </user>
Using the parameters shown in the previous section, Typical Usage, the excerpt will be returned as:
<policy policyName="reseller"> ... <user name="Reseller Guy"> <memberOfGroup name= "LDAP://cn=AllUsers@Reseller,ou=Services,ou=Hosting,dc=contoso,dc=com" /> </user>
Elements named <trusteeGroupNameGrant> and <trusteeWebGroupNameGrant> are used within access control entry (<ace>) elements as macros for longer, but repetitive entries. The following element:
<trusteeGroupNameGrant name="LDAP://cn=AllUsers@[self],ou=Services,ou=[self],[parentDN]" />
<trustee>LDAP://cn=AllUsers@Reseller,ou=Services,ou=Reseller,ou=Hosting,dc=contoso,dc=com </trustee> <trusteeType>TRUSTEE_IS_GROUP</trusteeType> <trusteeForm>TRUSTEE_IS_SID</trusteeForm> <mode>GRANT_ACCESS</mode>
where the extra tags are some commonly used <ace> entries.
The <trusteeWebGroupNameGrant> expands in similar fashion, except that the extra <ace> tags have a different format to suit the Web settings:
<trustee>LDAP://cn=AllUsers@Reseller,ou=Services,ou=Reseller,ou=Hosting,dc=contoso,dc=com </trustee> <trusteeNameType>1</trusteeNameType> <aceType>0</aceType> <trusteeForm>1</trusteeForm>
The LDAP path of each org, group, and user element is calculated and added to the element as an attribute named "path". This is a convenience function for the benefit of the caller, but is not of much interest for reading or modifying GetPolicy.
This procedure returns as extensive response; the details will vary depending on your particular deployment.