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:
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 126.96.36.199.2.4).
The elements GetADPrincipalGroupMembershipRequest/ResourceContextServer (section 188.8.131.52.2.6) and GetADPrincipalGroupMembershipRequest/ResourceContextPartition (section 184.108.40.206.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 220.127.116.11.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:
The primary group of the principal specified by GetADPrincipalGroupMembershipRequest/PrincipalDN element.
If the Server element specified in the GetADPrincipalGroupMembershipRequest SOAP message envelope (section 18.104.22.168) identifies an AD LDS instance, then the set of groups contains all groups, in the AD LDS forest ([MS-ADTS] section 22.214.171.124.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 126.96.36.199.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 188.8.131.52.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 184.108.40.206.2.8). Upon success, the GeADPrincipalGroupMembershipResponse (section 220.127.116.11.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 18.104.22.168.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.