3.3.4.4 GetADPrincipalGroupMembership
A server processes a GetADPrincipalGroupMembership request using the Active Directory Web Services: Custom Action Protocol upon receiving a SOAP message that contains the GetADPrincipalGroupMembershipRequest_Headers header and that specifies the following URI as the SOAP action:
http://schemas.microsoft.com/2008/1/ActiveDirectory/CustomActions/AccountManagement/GetADPrincipalGroupMembership
This operation is specified by the following WSDL.
-
<wsdl:operation name="GetADPrincipalGroupMembership"> <wsdl:input wsam:Action= "http://schemas.microsoft.com/2008/1/ActiveDirectory/CustomActions/AccountManagement/GetADPrincipalGroupMembership" name="GetADPrincipalGroupMembershipRequest" message="ca:GetADPrincipalGroupMembershipRequest" /> <wsdl:output wsam:Action= "http://schemas.microsoft.com/2008/1/ActiveDirectory/CustomActions/AccountManagement/GetADPrincipalGroupMembershipResponse" name="GetADPrincipalGroupMembershipResponse" message="ca:GetADPrincipalGroupMembershipResponse" /> <wsdl:fault wsam:Action="http://schemas.microsoft.com/2008/1/ActiveDirectory/Data/fault" name="GetADPrincipalGroupMembershipFault" message= "ca:AccountManagement_GetADPrincipalGroupMembership_GetADPrincipalGroupMembershipFault_FaultMessage" /> </wsdl:operation>
The GetADPrincipalGroupMembership custom action retrieves a set of groups associated with the principal specified by the GetADPrincipalGroupMembershipRequest/PrincipalDN element (section 3.3.4.4.2.4).
The elements GetADPrincipalGroupMembershipRequest/ResourceContextServer (section 3.3.4.4.2.6) and GetADPrincipalGroupMembershipRequest/ResourceContextPartition (section 3.3.4.4.2.5) are optional. If specified, they are specified together. That is, if one is non-null then the other is also non-null; otherwise, the server MUST return the appropriate SOAP fault for this particular condition as specified in section 3.3.4.4.8.
Depending on the parameters of GetADPrincipalGroupMembershipRequest, the group membership of the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN is retrieved according to the following rules:
If GetADPrincipalGroupMembershipRequest/ResourceContextServer and GetADPrincipalGroupMembershipRequest/ResourceContextPartition elements are not specified in the GetADPrincipalGroupMembershipRequest then:
If the Server element specified in the GetADPrincipalGroupMembershipRequest SOAP message envelope (section 2.2.3.5) identifies an AD DS instance then the set of groups contains:
All domain local and global groups from the domain of the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element that have that principal as a member.
All universal groups from the forest of the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element that have that principal as a member.
The primary group of the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element.
If the Server element specified in the GetADPrincipalGroupMembershipRequest SOAP message envelope (section 2.2.3.5) identifies an AD LDS instance, then the set of groups contains all groups, in the AD LDS forest ([MS-ADTS] section 3.1.1.1.7) in which the principal specified by the GetADPrincipalGroupMembershipRequest/PrincipalDN element is defined, that have the principal as member.
The server-to-server methods required to implement retrieving group memberships, including possibly contacting other servers, are not included in this document. Any failure of this method specific to the server-to-server implementation MUST return the SOAP fault as described in section 3.3.4.4.8.5. The fault MAY have meaning to peer servers or administrators of those servers.
If GetADPrincipalGroupMembershipRequest/ResourceContextServer and GetADPrincipalGroupMembershipRequest/ResourceContextPartition elements are specified in the GetADPrincipalGroupMembershipRequest, then the domain controller specified by the GetADPrincipalGroupMembershipRequest/ResourceContextServer element is used to retrieve a set of groups from the NC specified by GetADPrincipalGroupMembershipRequest/ResourceContextPartition which have the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element as a member. The NC specified by the GetADPrincipalGroupMembershipRequest/ResourceContextPartition can exist either in the same forest or in a different forest than the principal specified by the GetADPrincipalGroupMembershipRequest/PrincipalDN.
The server-to-server methods required to implement retrieving group memberships from GetADPrincipalGroupMembershipRequest/ResourceContextPartition, are not included in this document. Any failure of this method specific to the server-to-server implementation MUST return the SOAP fault as described in section 3.3.4.4.8.5. The fault MAY have meaning to peer servers or administrators of those servers.
For each group in the set retrieved using the above rules, the GetADPrincipalGroupMembership custom action constructs an ActiveDirectoryGroup element with all the properties populated, and adds it to the GeADPrincipalGroupMembershipResponse/MemberOf element (section 3.3.4.4.2.8). Upon success, the GeADPrincipalGroupMembershipResponse (section 3.3.4.4.2.7) element is returned. If no groups satisfy the above rules, then the server returns a GeADPrincipalGroupMembershipResponse with an empty MemberOf element.
If an error occurs while processing this operation, the server MUST return the appropriate SOAP fault for the particular error condition as specified in section 3.3.4.4.8.
Note The set of groups returned contains only those that have the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element as a direct member. No transitive group membership evaluation is done.
Note The GetADPrincipalGroupMembershipRequest/PartitionDN element, together with the GetADPrincipalGroupMembershipRequest/PrincipalDN element, is used only to verify the existence of the principal. The GetADPrincipalGroupMembershipRequest/PartitionDN element does not affect the set of groups returned in GeADPrincipalGroupMembershipResponse.