Active Directory Provider::Update ACL

  • Article

Updates the security descriptor for an Active Directory directory service object. The security descriptor consists of the discretionary access control list (DACL) that sets permissions and the system access control list (SACL) that sets auditing. Used by Microsoft Provisioning Framework (MPF).

Update ACL is a wrapper for the Win32 API functions GetNamedSecurityInfo, SetEntriesInAcl and SetNamedSecurityInfo.

Each ace element specifies access control or audit control information for a specified trustee. A trustee can be a user, group, or other security identifier (SID) value, such as a logon identifier or logon type (for instance, a Win32 service or batch job). You can use a name, LDAP path, or a SID to identify a trustee.

You can use Update ACL to modify the list of ACEs in a DACL or a SACL. A DACL controls access to an object, and a SACL controls the system's auditing of attempts to access to an object. Note that Update ACL does not prevent you from mixing access control and audit control information in the same ACL; however, the resulting ACL will contain meaningless entries.

In the new DACL or SACL, Update ACL places new access-denied ACEs at the beginning of the list and new access-allowed ACEs before existing access-allowed ACEs.

To remove an ACE, use "<mode>REVOKE_ACCESS</mode>" and make sure the trustee, permission and inheritance elements match the ACE you want to remove. If a matching ACE is not found, no error occurs. When a new ACE with a generic permission is added to an ACL, the permission is converted to specific permissions, so removing it will require knowing what the specific permissions are. This is explained in Microsoft knowledgebase article Q254665. An attempt to revoke an ACE inherited from the parent will be ignored.

Arguments

The following table describes the XML schema elements and attributes. Unless otherwise indicated, the data type is string.

Element Description, relationships, and attributes

ace

Description:
Access control elements (ACEs) for the discretionary access control list (DACL) or system access control list (SACL).

Parents:
dacl, sacl

Children:
inheritance (minOccurs="0" maxOccurs="*")
inheritedObjectTypeName (minOccurs="0" maxOccurs="1")
mode (minOccurs="1" maxOccurs="1")
objectTypeName (minOccurs="0" maxOccurs="1")
permission (minOccurs="1" maxOccurs="*")
trustee (minOccurs="1" maxOccurs="1")
trusteeForm (minOccurs="1" maxOccurs="1")
trusteeType (minOccurs="0" maxOccurs="1")

dacl

Description:
DACL for the specified object.

Parent:
executeData

Child:
ace

executeData

Description:
Encapsulates the procedure's input data.

Children:
dacl (minOccurs="0" maxOccurs="1")
name (minOccurs="1" maxOccurs="1")
objectType (minOccurs="1" maxOccurs="1")
sacl (minOccurs="0" maxOccurs="1")

inheritance

Description:
Set of bit flags that determines whether other containers or objects can inherit the ACE from the primary object to which the DACL or SACL is attached. This value can be either a number or an AceFlags string. (See the AceFlags table following the sample code.)

The value for this element corresponds to the inheritance portion (low-order byte) of the AceFlags member of the ACE_HEADER structure. This parameter can be NO_INHERITANCE to indicate that the ACE is not inheritable, or it can be a combination of the values from the AceFlags table following the sample code. An ace parent can have multiple inheritance elements whose values are concatenated by a bitwise OR to build a single inheritance value.

The following example creates an ACE with an inheritance value of 3.

<ace> 
  <inheritance>SUB_OBJECTS_ONLY_INHERIT</inheritance> 
  <inheritance>2</inheritance> 
</ace>

AceFlags values:

0x0NO_INHERITANCEDefault. This ACE will not be inherited by other objects.
0x1SUB_OBJECTS_ONLY_INHERITNon-container objects contained by the primary object inherit the ACE.
0x2SUB_CONTAINERS_ONLY_INHERITOther containers contained by the primary object inherit the ACE.
0x3SUB_CONTAINERS_AND_OBJECTS_INHERITBoth containers and non-container objects contained by the primary object inherit the ACE.
0x4INHERIT_NO_PROPAGATEThe SUB_OBJECTS_ONLY_INHERIT and SUB_CONTAINERS_ONLY_INHERIT flags are not propagated to an inherited ACE.
0x8INHERIT_ONLYThe ACE does not apply to the primary object to which the DACL or SACL is attached, but objects contained by the primary object inherit the ACE.

Parent:
ace

inheritedObjectTypeName

Description:
Identifies the type of objects that can inherit the ACE. If the value for the trusteeForm node is TRUSTEE_IS_OBJECTS_AND_NAME, inheritedObjectTypeName must be a valid lightweight directory access protocol (LDAP) display name in the Active Directory schema. For TRUSTEE_IS_OBJECTS_AND_SID, this must be an LDAP path or a globally unique identifier (GUID) of an extended right. If it begins with "LDAP://", the procedure gets the object and stores the "rightsGUID" of the object. Otherwise, the string must be a GUID string such as "{12345678-1234-1234-1234-123456789abc}".

There is no default value. The procedure will fail if this element exists and trusteeForm is not TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

Parent:
ace

mode

Description:
Specifies a value from the ACCESS_MODE enumeration. For a DACL, mode indicates whether the DACL allows or denies the specified access rights. For a SACL, mode indicates whether the SACL generates audit messages for successful attempts to use the specified access rights, or failed attempts, or both.

ACCESS_MODE values for a DACL:

1GRANT_ACCESSThe new ACE combines the specified rights with any existing allowed or denied rights of the trustee.
2SET_ACCESSOn input, this flag discards any matching access-control information for the trustee and adds the new ACE. See REVOKE_ACCESS for limitations on what is discarded.
3DENY_ACCESSOn input, this flag denies the specified rights in addition to any currently denied rights of the trustee. It also modifies or deletes any existing access-control information for the trustee that allows the specified rights.
4REVOKE_ACCESSAn input flag that removes matching access-control information for the trustee. When modifying an existing DACL, specify REVOKE_ACCESS to remove any existing ACEs for the specified trustee. However, note that the operating system typically converts generic permissions to specific ones. Use to generate a list of all specific permissions, then Update ACL to revoke individual permissions. The ace element will be ignored if the ACE does not exist or it is inherited from the parent.

ACCESS_MODE values for a SACL:

4REVOKE_ACCESSInput flag that removes matching access-control information for the trustee. The ace element will be ignored if the ACE does not exist or it is inherited from the parent.
5SET_AUDIT_SUCCESS

Indicates a SYSTEM_AUDIT_ACE that generates audit messages for successful attempts to use the specified access rights. You can combine this value with SET_AUDIT_FAILURE. On input, this flag combines the specified rights with any existing audited access rights for the trustee.
6SET_AUDIT_FAILURE

Indicates a SYSTEM_AUDIT_ACE that generates audit messages for failed attempts to use the specified access rights. You can combine this value with SET_AUDIT_SUCCESS. On input, this flag combines the specified rights with any existing audited access rights for the trustee.

Parent:
ace

name

Description:
Name of the object to update the DACL or SACL for. For Active Directory objects, this would be the LDAP path.

Parent:
executeData

objectType

Description:
One of the object types listed in the following SE_OBJECT_TYPE table. For Active Directory objects, this should be SE_DS_OBJECT.

0SE_UNKNOWN_OBJECT_TYPEUnknown object type.
1SE_FILE_OBJECTA file or directory. The name string that identifies a file or directory object can be one of the following.
  • A relative path such as Abc.dat or ..\Abc.dat.

  • An absolute path such as \Abc.dat, C:\Dir1\Abc.dat, or G:\Remotedir\Abc.dat.

  • A UNC name such as \\Machinename\Sharename\Abc.dat.

  • A local file system root such as \\\\.\\C:. Security set on a file system root does not persist when the system is restarted.

2SE_SERVICEA Win32 service. A service object can be a local service, such as servicename; or a remote service, such as \\machinename\servicename.
3SE_PRINTERA printer. A printer object can be a local printer, such as printername; or a remote printer, such as \\machinename\printername.
4SE_REGISTRY_KEYA registry key. A registry key object can be in the local registry, such as CLASSES_ROOT\somepath; or in a remote registry, such as \\machinename\CLASSES_ROOT\somepath. The names of registry keys must use the following literal strings to identify the predefined registry keys: CLASSES_ROOT, CURRENT_USER, MACHINE, and USERS.
5SE_LMSHAREA network share. A share object can be local, such as sharename; or remote, such as \\machinename\sharename.
6SE_KERNEL_OBJECT

A local kernel object. The GetSecurityInfo and SetSecurityInfo functions support all types of kernel objects. The GetNamedSecurityInfo and SetNamedSecurityInfo functions work only with the following kernel objects: semaphore, event, mutex, waitable timer, and file mapping.
7SE_WINDOW_OBJECTA window station or desktop object on the local machine. You cannot use GetNamedSecurityInfo and SetNamedSecurityInfo with these objects because the names of window stations or desktops are not unique.
8SE_DS_OBJECTMicrosoft Windows 2000: A directory service (DS) object, or a property set or property of a directory service object. The name string for a DS object can be a UNC name such as \\domain.microsoft.com\ou1\ou2\someobject. The name string can also be in X.500 form, such as CN=someobject,OU=ou2,OU=ou1,DC=domain,DC=microsoft,DC=com,O=internet.
9SE_DS_OBJECT_ALLWindows 2000: A directory service object and all of its property sets and properties.
10SE_PROVIDER_DEFINED_OBJECTWindows 2000: A provider-defined object.
11SE_WMIGUID_OBJECTWindows 2000: A Windows Management Instrumentation (WMI) object.

Parent:
executeData

objectTypeName

Description:
String that identifies the type of object, property set, or property protected by the ACE. If this ACE is inherited, it identifies the type of object, property set, or property protected by the inherited ACE. If the trusteeForm node is TRUSTEE_IS_OBJECTS_AND_NAME, objectTypeName must be a valid LDAP display name in the Active Directory schema. For TRUSTEE_IS_OBJECTS_AND_SID, this must be an LDAP path or GUID of an extended right. If it begins with "LDAP://", the procedure gets the object and stores the "rightsGUID" of the object. Otherwise, the string must be a GUID string such as {12345678-1234-1234-1234-123456789abc}. The permission element should be ADS_RIGHT_DS_CONTROL_ACCESS when setting an extended right. There can be at most one of these elements. There is no default value. The procedure will fail if this element exists and trusteeForm is not TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

Parent:
ace

permission

Description:
Value containing standard, specific, and generic rights. These rights are used in ACEs and are the primary means of specifying the requested or granted access to an object. This value can be either a number or string from any of the following tables. Multiple permission elements can be concatenated by a bitwise OR to create a single value.

Standard and generic permissions (ACCESS_MASK):

0x00010000LDELETEDelete access
0x00020000LREAD_CONTROLRead access to the owner, group, and discretionary access control list (DACL) of the security descriptor
0x00040000LWRITE_DACWrite access to the DACL
0x00080000LWRITE_OWNERWrite access to owner
0x00100000LSYNCHRONIZEMicrosoft Windows NT and Windows 2000: Synchronize access
0x01000000LACCESS_SYSTEM_SECURITYAccess system security (ACCESS_SYSTEM_SECURITY). This flag is not a typical access type. It is used to indicate access to a SACL This type of access requires the calling process to SE_SECURITY_NAME (Manage auditing and security log) privilege. If this flag is set in the access mask of an audit access ACE (successful or unsuccessful access), the SACL access will be audited.
0x02000000LMAXIMUM_ALLOWEDMaximum allowed
0x10000000LGENERIC_ALLGeneric all
0x20000000LGENERIC_EXECUTEGeneric execute
0x40000000LGENERIC_WRITEGeneric write
0x80000000LGENERIC_READGeneric read

Active Directory permissions (ADS_RIGHTS_ENUM):

0x1ADS_RIGHT_DS_CREATE_CHILDThe right to create children of the object. The ObjectType member of an ACE can contain a GUID that identifies the type of child object whose creation is being controlled. If ObjectType does not contain a GUID, the ACE controls the creation of all child object types.
0x2ADS_RIGHT_DS_DELETE_CHILDThe right to delete children of the object. The ObjectType member of an ACE can contain a GUID that identifies a type of child object whose deletion is being controlled. If ObjectType does not contain a GUID, the ACE controls the deletion of all child object types.
0x4ADS_RIGHT_ACTRL_DS_LISTThe right to list children of this object.
0x8ADS_RIGHT_DS_SELFThe right to modify the group membership of a group object.
0x10ADS_RIGHT_DS_READ_PROPThe right to read properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to read all of the object's properties.
0x20ADS_RIGHT_DS_WRITE_PROPThe right to write properties of the object. The ObjectType member of an ACE can contain a GUID that identifies a property set or property. If ObjectType does not contain a GUID, the ACE controls the right to write all of the object's properties.
0x40ADS_RIGHT_DS_DELETE_TREEThe right to delete all children of this object, regardless of the permission on the children.
0x80ADS_RIGHT_DS_LIST_OBJECTThe right to list an object. If the user is not granted such a right, the object is hidden from the user.
0x100ADS_RIGHT_DS_CONTROL_ACCESSThe right to perform an operation controlled by an extended access right. The ObjectType member of an ACE can contain a GUID that identifies the extended right. If ObjectType does not contain a GUID, the ACE controls the right to perform all extended right operations associated with the object.
0x10000ADS_RIGHT_DELETEThe right to delete the object.
0x20000ADS_RIGHT_READ_CONTROLThe right to read information from the security descriptor of the object, not including the information in the SACL.
0x40000ADS_RIGHT_WRITE_DACThe right to modify the DACL in the object's security descriptor.
0x80000ADS_RIGHT_WRITE_OWNERThe right to assume ownership of the object. The user must be a trustee of the object. The user cannot transfer the ownership to other users.
0x100000ADS_RIGHT_SYNCHRONIZEThe right to use the object for synchronization. This enables a thread to wait until the object is in the signaled state.
0x1000000ADS_RIGHT_ACCESS_SYSTEM_SECURITYThe right to get or set the SACL in the object's security descriptor.
0x10000000ADS_RIGHT_GENERIC_ALLThe right to create or delete children, delete a subtree, read and write properties, examine children and the object itself, add and remove the object from the directory, and read or write with an extended right.
0x20000000ADS_RIGHT_GENERIC_EXECUTEThe right to list children of this object.
0x40000000ADS_RIGHT_GENERIC_WRITEThe right to write all the properties and write to the DACL. The user can add and remove the object to and from the directory.
0x80000000ADS_RIGHT_GENERIC_READThe right to read from the security descriptor, examine the object as well as its children, and read all properties.

Registry permissions:

0x0001KEY_QUERY_VALUEPermission to query subkey data.
0x0002KEY_SET_VALUEPermission to set subkey data.
0x0004KEY_CREATE_SUB_KEYPermission to create subkeys.
0x0008KEY_ENUMERATE_SUB_KEYSPermission to enumerate subkeys.
0x0010KEY_NOTIFYPermission for change notification.
0x0020KEY_CREATE_LINKPermission to create a symbolic link.
0x20006KEY_WRITECombines the READ_CONTROL, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY access rights.
0x20019KEY_EXECUTEPermission for read access.
0x20019KEY_READCombines the READ_CONTROL, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access rights.
0xF003FKEY_ALL_ACCESSCombines the KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access rights, plus all the standard access rights except SYNCHRONIZE.

File system permissions:

0x0001FILE_LIST_DIRECTORY, FILE_READ_DATARight to read data from a file. For a directory, the right to list the contents of a directory.
0x0002FILE_WRITE_DATARight to write data to a file. For a directory, the right to create a file in a directory.
0x0004FILE_ADD_SUBDIRECTORY, FILE_APPEND_DATARight to append data to the file. For a directory, the right to create a subdirectory.
0x0008FILE_READ_EARight to read extended attributes.
0x0010FILE_WRITE_EARight to write extended attributes.
0x0020FILE_EXECUTERight to execute a program.
0x0020FILE_TRAVERSERight to execute a file. For a directory, the directory can be traversed.
0x0040FILE_DELETE_CHILDFor a directory, the right to delete a subdirectory.
0x0080FILE_READ_ATTRIBUTESRight to read file attributes.
0x0100FILE_WRITE_ATTRIBUTESRight to write file attributes.
0x120089FILE_GENERIC_READCombination of permissions.
0x1200A0FILE_GENERIC_EXECUTECombination of permissions.
0x120116FILE_GENERIC_WRITECombination of permissions.

Parent:
ace

sacl

Description:
SACL for the specified object.

Parent:
executeData

Child:
ace

trustee

Description:
Identifies the user, group, or program (such as a Win32 service) to which the ACE applies. Can be either a sAMAccountName, LDAP path or security identifier (SID), depending on the value for the trusteeForm node. For TRUSTEE_IS_NAME or TRUSTEE_IS_OBJECTS_AND_NAME, trustee should be a valid sAMAccountName. For TRUSTEE_IS_SID or TRUSTEE_IS_OBJECTS_AND_SID, trustee must be a SID or LDAP path. If trustee begins with "LDAP://", the procedure assumes it is an LDAP path; otherwise, the procedure assumes trustee is a SID in string format. For LDAP path, the procedure gets the objectSid of the object and stores the SID.

Parent:
ace

Dd251753.note(en-us,TechNet.10).gifNote
sAMAccountName cannot be longer than 20 characters. See SAM-Account-Name Attribute for more information.

trusteeForm

Description:
Specifies a value from the TRUSTEE_FORM enumeration type that indicates the type of value in the trustee node. This value can be either a TRUSTEE_FORM string or a number. If an objectTypeName or inheritedObjectTypeName is supplied, it should be either TRUSTEE_IS_OBJECTS_AND_NAME or TRUSTEE_IS_OBJECTS_AND_SID.

0TRUSTEE_IS_SIDtrustee is the SID of the trustee.
1TRUSTEE_IS_NAMEtrustee is the name of the trustee.
3TRUSTEE_IS_OBJECTS_AND_SIDtrustee is the SID of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.
4TRUSTEE_IS_OBJECTS_AND_NAMEtrustee is the name of the trustee and either objectTypeName or inheritedObjectTypeName is supplied.

Parent:
ace

trusteeType

Description:
Indicates whether the trustee is a user account, a group account, or the account type is unknown. Specifies a value from the following TRUSTEE_TYPE enumeration. The default is TRUSTEE_IS_UNKNOWN.

0TRUSTEE_IS_UNKNOWNTrustee type is unknown, but not necessarily invalid.
1TRUSTEE_IS_USERIndicates a user.
2TRUSTEE_IS_GROUPIndicates a group.
3TRUSTEE_IS_DOMAINIndicates an Active Directory domain.
4TRUSTEE_IS_ALIASIndicates an alias.
5TRUSTEE_IS_WELL_KNOWN_GROUPIndicates a well-known group.
6TRUSTEE_IS_DELETEDIndicates a deleted account.
7TRUSTEE_IS_INVALIDIndicates an invalid trustee type.
8TRUSTEE_IS_COMPUTERIndicates a computer.

Parent:
ace

Remarks

During rollback, Update ACL restores the original DACL or SACL.

Numbers passed in are assumed to be decimal. A number can be prefixed with "0x" or "&H" to be interpreted as hex.

Schema Definition

Input

<executeData>1..1
  <name>1..1</name>
  <objectType>1..1</objectType>
  <dacl>0..1
    <ace>0..unbounded
      <permission>1..unbounded</permission>
      <mode>1..1</mode>
      <trusteeForm>1..1</trusteeForm>
      <trustee>1..1</trustee>
      <trusteeType>0..1</trusteeType>
      <inheritance>0..unbounded</inheritance>
      <objectTypeName>0..1</objectTypeName>
      <inheritedObjectTypeName>0..1</inheritedObjectTypeName>
    </ace>
  </dacl>
  <sacl>0..1
    <ace>0..unbounded
      <permission>1..unbounded</permission>
      <mode>1..1</mode>
      <trusteeForm>1..1</trusteeForm>
      <trustee>1..1</trustee>
      <trusteeType>0..1</trusteeType>
      <inheritance>0..unbounded</inheritance>
      <objectTypeName>0..1</objectTypeName>
      <inheritedObjectTypeName>0..1</inheritedObjectTypeName>
    </ace>
  </sacl>
</executeData>

Sample Code

Example XML Request

The following code fragment shows the format for sending data to this procedure. For more information on individual elements and attributes, see the Elements and Attributes table.

Example XML Response

Update ACL does not return data.

Applies To

Active Directory Provider for:

  • Hosted Messaging and Collaboration version 4.5

  • Hosted Messaging and Collaboration version 4.0

  • Hosted Messaging and Collaboration version 3.5

  • Hosted Messaging and Collaboration version 3.0

  • Windows-based Hosting version 4.5

  • Windows-based Hosting version 4.0

  • Windows-based Hosting version 3.5

  • Windows-based Hosting for Applications version 1.0

See also

Tasks

Active Directory Provider::Get SACL
Active Directory Provider::Get DACL