Directory Services

Creating a Control Access Right

To add a control access right to Active Directory, create a controlAccessRight object in the Extended-Rights container of the Configuration partition. For a code example, see Example Code for Creating a controlAccessRight Object in the Extended Rights Container. To use the control access right, you must do a few more things depending on whether the control access right is for a special operation or a property set.

If you define a control access right for a property set, you must use the rightsGUID of the controlAccessRight object to identify the properties in the set. Every property is defined by an attributeSchema object in the Active Directory schema. The attributeSecurityGUID property of an attributeSchema object identifies the property set, if any, that the property belongs to. Be aware that the attributeSchema property is single-valued and stores the GUID in binary format (octet string syntax).

If you define a control access right to place restrictions on access to a particular operation, your application must perform the access check when a user attempts the operation.

To set up access check

  1. Create a control access right that defines the type of access to the application or service. For more information, see the following code example.
  2. Create an Active Directory object that represents the application, service, or resource that you are protecting.
  3. Add object ACEs to the DACL in the object's security descriptor to allow or deny users or groups the control access right on that object. For more information, see Setting a Control Access Right ACE in an Object's ACL.
  4. When a user attempts to perform the operation, check the user's rights by passing the object's security descriptor and the user's access token to the AccessCheckByTypeResultList function. For more information, see Checking a Control Access Right in an Object's ACL.

Based on the result of the access check on the object, the application or service can allow or deny the user access to the application or service.

When you create a controlAccessRight object, set the following attributes to make the object a legal control access right that is recognized by Active Directory and the Windows NT/Windows 2000 security system.

Attribute Description
cn A single-valued property that is the object's relative distinguished name (RDN) in the Extended-Rights container. The cn is the name of the access control right in Active Directory.
appliesTo A multi-valued property that lists the object classes that the access control right applies to. For example, the Send-As access control right lists the user and computer object classes in its appliesTo property.

In the list, each object class is identified by the schemaIDGUID of its classSchema object. The GUIDs are stored as strings of the form produced by the StringFromGUID2 function in the COM library—but without the starting and terminating braces ({ }). For example, the following GUID is the schemaIDGUID for the computer class:

bf967a86-0de6-11d0-a285-00aa003049e2

Be aware that the schemaIDGUID property of a classSchema object is stored as a binary GUID using the octet string syntax. To convert this octet string format to the string format used in the appliesTo property, use the StringFromGUID2 function and remove the braces from the returned string.

For more information about the schemaIDGUID property of one of the predefined object classes, such as user or computer, see the class reference page in the Active Directory Schema Reference in the Active Directory Reference. For more information and a code example that retrieves a schemaIDGUID from a classSchema object, see Reading attributeSchema and classSchema Objects.
displayName The string used to display the access control right in user interfaces such as the Security property page and other places in the Active Directory Users and Computers.
rightsGUID A GUID that identifies the control access right in an ACE. The GUID is stored as a string of the form produced by the StringFromGUID2 function, but without the starting and terminating braces. Use Uuidgen.exe for some other utility to generate a GUID for the control access right.

If you define a new property set, you use the rightsGUID of the controlAccessRight object to identify the properties in the set. For each property in the property set, set the property's attributeSecurityGUID value to the value of the property set's rightsGUID. A property's attributeSecurityGUID value is stored in the property's attributeSchema definition in the Active Directory schema. The attributeSecurityGUID property is single-valued and stores the GUID in binary format (octet string syntax).
objectClass This attribute specifies controlAccessRight as the object class.
validAccesses For property sets, set this attribute to 0x30 (ADS_RIGHT_DS_READ_PROP | ADS_RIGHT_DS_WRITE_PROP). For control access rights, set this attribute to 0x100 (ADS_RIGHT_DS_CONTROL_ACCESS). The security property page recognizes control access rights only if the validAccesses attribute is set to the appropriate value. If zero, the control access right is ignored or not displayed by the security property page.

Be aware that the predefined schema classes use the localizationDisplayId attribute of a controlAccessRight object to specify a message identifier used to retrieve a localized display name from Dssec.dll. Do not set the localizationDisplayId attribute if you define a new controlAccessRight object.