The security interfaces for Active Directory have not been finalized as of the release of this specification. The proposed objects and interfaces for ACL manipulation are described in this appendix.
Each network environment provides various operations designed to enhance the security of the network and its resources. These operations typically include security policy, authorization, and security-related monitoring or auditing. All of these operations are predicated on successful authentication of the identity of the user or principal.
Authorization refers to access control on resources, determining who is allowed to use a given resource and how they can use it. With many systems, the access control mechanism involves putting an access control list (ACL) on the resource. The ACL mechanisms are closely tied to the network environment where they are supported and differ greatly depending on the network environment. Another important aspect of ACLs is inheritance, the capability of influencing ACLs on child objects by modifying ACLs on the container objects.
Active Directory access control is focused on administering authorization, not on providing other security features typically needed by services. This is achieved using three dependent objects:
Access Control objects can be obtained from Active Directory objects via the IADs::Access() pr ::PropAccess() methods. By default, each object must support the following permissions:
AllAccess is shorthand for all available permissions on the object.
These permissions can be interpreted differently for different object classes. For example a container might equate the following permissions with the standard permissions:
An object class can also support additional permissions. For example, a User object class can support the following permissions in addition to the standard permissions:
By convention, the Access Control dependent object supports the IADsAccess interface for access control browsing and manipulation. It is derived from IDispatch. The definition looks like this:
[ object, uuid(IID_IADsAccess), oleautomation, dual ]
interface IADsAccess: IDispatch
{
// Read-only properties.
[propget]
HRESULT InheritanceType ([out, retval]BSTR *pbstrInheritance);
[propget]
HRESULT AvailablePermissions ([out, retval]VARIANT *pvPermissions);
// Methods.
HRESULT Grant([in]BSTR bstrTrustee,
[in]VARIANT vPerms );
HRESULT Deny([in]BSTR bstrTrustee,
[in]VARIANT vPerms );
HRESULT Revoke([in]BSTR bstrTrustee);
HRESULT Set([in]BSTR bstrTrustee,
[in]VARIANT vPerms );
HRESULT Rights([out, retval]IADsCollection **ppRightsCollection);
HRESULT Effective([in]BSTR bstrTrustee,
[out, retval]VARIANT *pvPerms );
HRESULT IsAccessPermitted([in]BSTR bstrTrustee,
[in]VARIANT vPerms,
[out, retval]boolean *pbPermitted );
};
| Method | Description |
| InheritanceType | Gets a BSTR defining the type of access
control inheritance the server supports. Currently
defined access control inheritances are: CREATE TIME DYNAMIC PERSCRIPTIVE |
| AvailablePermissions | Gets an array containing all the access
permissions supported by the object. These permissions
are the only valid access permissions on this object
type. Attempting to grant or deny a trustee other
permissions on the object will result in an error. The
array is a SAFEARRAY of BSTRs containing the names of the
access permissions: Read Write Delete Edit AllAccess Any other permissions supported by the object |
| Grant | Ensures that the trustee has at least
the specified access permissions. Other access
permissions the trustee is allowed or denied will not be
changed. If the permissions are not valid for the object,
an error is returned. Permissions are passed as a SAFEARRAY of BSTRs. Any permission string from the AvailablePermissions property is valid. |
| Deny | Ensures that the trustee is denied the
specified access permissions. Other access permissions
the trustee is allowed or denied will not be changed. If
the permissions are not valid for the object, an error is
returned. Permissions are passed as a SAFEARRAY of BSTRs. Any permission string from the AvailablePermissions property is valid. |
| Revoke | Ensures that the trustee is not explicitly allowed any access permissions on the object. The trustee may, however be allowed or denied other access permissions because of group membership. |
| Set | Ensures that the trustee has exactly the
specified access permissions. The trustee will no longer
be allowed other access permissions that were previously
allowed for that trustee. If the permissions are not
valid for the object, an error is returned. Permissions are passed as a SAFEARRAY of BSTRs. Any permission string from the AvailablePermissions property is valid. |
| Rights | Returns a Rights collection dependent object that allows enumerating through the access rights on the object. See "Rights Collection Sub-Object" later in this chapter. |
| Effective | Returns an array containing the effective access permissions the specified trustee has on the object. The array is a SAFEARRAY of BSTRs containing the names of the effective access permissions granted to the trustee. |
| IsAccessPermitted | Returns TRUE if the specified trustee
has the specified permissions. If the specified
permissions are not valid for the object, an error is
returned. Permissions are passed as a SAFEARRAY of BSTRs. Any permission string from the AvailablePermissions property is valid. |
The Rights collection is collection of pointers to Right Entry dependent objects, which represent the access permissions currently set on an object. This collection is obtained by calling the IADsAccess::Rights() method.
The Add and Remove methods on the IADsCollection interface are not implemented for this collection. Rights on an object are manipulated using the IADsAccess interface.
A Right Entry dependent object describes one access control entry (ACE) on the ACL that describes the access permissions currently set on an object. Right entry objects are obtained exclusively from an enumeration of a Rights collection.
By convention, the right entry dependent object supports the IADsRightEntry interface. It is derived from IDispatch. The definition looks like this:
[ object, uuid(IID_IADsRightEntry), oleautomation, dual ]
interface IADsRightEntry: IDispatch
{
// Read-only properties.
[propget]
HRESULT Trustee ([out, retval]BSTR *pbstrTrustee);
[propget]
HRESULT Permissions ([out, retval]VARIANT *pvPermissions);
};
| Method | Description |
| Trustee | Gets the ADsPath string of the Trustee object. |
| Permissions | Gets a SAFEARRAY of BSTRs containing the access permissions granted or denied to the trustee on the object. |
The following examples demonstrate how to use the access control objects.
Example 1: Setting Access Rights on a Property of the User Object (Visual Basic)
Dim User as IADsUser
' Bind to a user object.
Set User = GetObject("WinNT://MSFT/Users/John")
' Give the group Everyone read-only access to the Manager property.
User. PropAccess("Manager").Set("Everyone", Array("Read"))
Example 2: Displaying Access Rights for a Selected User on a Selected DS Object (Visual Basic)
Dim User as IADsUser
Dim RightEntry as IADsRightEntry
Dim Entry as String
' Bind to a user object.
Set User = GetObject("WinNT://MSFT/Users/John")
' Enumerate the rights on the user object.
For Each RightEntry In User.Access.Rights
' Print the access rights that are related to Jane.
If RightEntry.Trusteename = "WinNT://MSFT/Users/Jane" Then
For Each Entry in RightEntry.Permissions
Debug.Print Entry
Next Entry
End If
Next RightEntry
Example 3: Determining what a Selected User can do to a Selected DS Object (Visual Basic)
Dim User as IADsUser
Dim Permissions as Variant
Dim Entry as String
' Bind to a user object.
Set User = GetObject("WinNT://MSFT/Users/John")
' Find out Jane's effective access rights.
Permissions = User.Access.Effective("WinNT://MSFT/Users/Jane")
For Each Entry in Permissions
Debug.Print Entry
Next Entry
Example 4: Determining Who has Explicit Rights to Change a DS Object (Visual Basic)
Dim User as IADsUser
Dim RightEntry as IADsRightEntry
Dim Entry as String
' Bind to a user object.
Set User = GetObject("WinNT://MSFT/Users/John")
' Enumerate the "All" or "Write" permissions on this object.
For Each RightEntry In User.Access.Rights
For Each Entry in RightEntry.Permissions
If Entry = "All" or Entry = "Write"
Debug.Print RightEntry.Trustee
End If
Next Entry
Next RightEntry
Example 5: Setting Access Rights on Properties of the User object (C/C++)
IADsAccess *pSimpleAccess;
IADs_Access *pAccess;
IADsUser *pUser;
ACCESS_REQUEST ar[2];
//
// Build up an access request.
//
ar[0].Trustee.pwcsName = TEXT("WinNT://MSFT/Users/Jane");
ar[0].Trustee.Type = TRUSTEE_IS_USER;
ar[0].Trustee.Reserved = 0;
ar[0].grfAccessPermissions = PROV_OBJECT_READ | PROV_OBJECT_WRITE;
ar[1].Trustee.pwcsName = ADMINISTRATOR;
ar[1].Trustee.Type = TRUSTEE_IS_USER;
ar[1].Trustee.Reserved = 0;
ar[1].grfAccessPermissions = PROV_ALL_ACCESS;
//
// Use the Active Directory helper function ADsGetObject to bind to John and
// return the user interface.
//
ADsGetObject(TEXT("WinNT://MSFT/Users/John"),
IID_IADsUser,
(void**)&pUser);
//
// Get the access control object on the user and QI for the
// advanced access control interface.
//
pUser->Access(&pSimpleAccess);
pSimpleAccess->QueryInterface(IID_IADs_Access, (void**)&pAccess);
//
// Grant the access rights specified in the access request.
//
pAccess->GrantAccessRights(2,ar);
//
// Cleanup.
//
pAccess->Release();
pSimpleAccess->Release();
pUser->Release();
Example 6: Determine if a Selected User can change a Selected Active Directory Object (C/C++)
IADsAccess *pSimpleAccess;
IADs_Access *pAccess;
IADsUser *pUser;
boolean bPermitted;
//
// Use the Active Directory helper function ADsGetObject to bind to John.
//
ADsGetObject(TEXT("WinNT://MSFT/Users/John"),
IID_IADsUser,
(void**)&pUser
//
// Get the access control object on the user and QI for the
// advanced access control interface.
//
pUser->Access(&pSimpleAccess);
pSimpleAccess->QueryInterface(IID_IADs_Access, (void**)&pAccess);
//
// Determine if the selected user has read/write
// permissions on the object.
//
pAccess->IsAccessPermitted(TEXT("WinNT://MSFT/Users/Jane"),
(PROV_OBJECT_READ | PROV_OBJECT_WRITE),
&bPermitted);
if (bPermitted == TRUE)
{
printf("Jane can change the selected object.\n");
}
//
// Cleanup.
//
pAccess->Release();
pSimpleAccess->Release();
pUser->Release();