Skip to content

directoryobject-checkmembergroups.md

Latest commit

 

History

History
332 lines (258 loc) · 12.7 KB

directoryobject-checkmembergroups.md

File metadata and controls

332 lines (258 loc) · 12.7 KB
title directoryObject: checkMemberGroups
description Check for membership in a specified list of groups, and return from that list those groups of which the specified user, group, service principal, organizational contact, device, or directory object is a member.
ms.localizationpriority medium
author FaithOmbongi
ms.subservice entra-directory-management
doc_type apiPageType
ms.date 10/24/2024

directoryObject: checkMemberGroups

Namespace: microsoft.graph

Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types:

This function is transitive.

You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct.

[!INCLUDE national-cloud-support]

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Group memberships for a directory object

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Directory.Read.All Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Directory.Read.All Directory.ReadWrite.All

Note

The Directory.* permissions allow you to retrieve any supported directory object type via this API. To retrieve only a specific type, you can use permissions specific to the resource.

Group memberships for the signed-in user

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) User.Read User.ReadBasic.All and GroupMember.Read.All, User.Read.All and GroupMember.Read.All, User.ReadBasic.All and Group.Read.All, User.Read.All and Group.Read.All, Directory.Read.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Not supported. Not supported.

Group memberships for other users

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) User.ReadBasic.All and GroupMember.Read.All User.Read.All and GroupMember.Read.All, User.ReadBasic.All and Group.Read.All, User.Read.All and Group.Read.All, Directory.Read.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application User.ReadBasic.All and GroupMember.Read.All User.Read.All and GroupMember.Read.All, User.Read.All and Group.Read.All, Directory.Read.All

Group memberships for a group

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) GroupMember.Read.All Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application GroupMember.Read.All Group.Read.All, Directory.Read.All, Group.ReadWrite.All, Directory.ReadWrite.All

Group memberships for a service principal

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Application.Read.All Directory.Read.All, Application.ReadWrite.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Application.Read.All Directory.Read.All, Application.ReadWrite.All, Directory.ReadWrite.All

Group memberships for an organizational contact

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Directory.Read.All Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Directory.Read.All Directory.ReadWrite.All

Group memberships for a device

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Device.Read.All Device.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Device.Read.All Device.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP request

Group memberships for a directory object (user, group, service principal, or organizational contact).

POST /directoryObjects/{id}/checkMemberGroups

Group memberships for the signed-in user.

POST /me/checkMemberGroups

[!INCLUDE me-apis-sign-in-note]

[!INCLUDE me-apis-sign-in-note]

Group memberships for other users.

POST /users/{id | userPrincipalName}/checkMemberGroups

Group memberships for a group.

POST /groups/{id}/checkMemberGroups

Group memberships for a service principal.

POST /servicePrincipals/{id}/checkMemberGroups

Group memberships for an organizational contact.

POST /contacts/{id}/checkMemberGroups

Group memberships for a device.

POST /devices/{id}/checkMemberGroups

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json

Request body

In the request body, provide a JSON object with the following parameters.

Parameter Type Description
groupIds String collection A collection that contains the object IDs of the groups in which to check membership. Up to 20 groups may be specified.

Response

If successful, this method returns 200 OK response code and String collection object in the response body.

Examples

Example 1: Check group memberships for a directory object

Request

HTTP

POST https://graph.microsoft.com/v1.0/directoryObjects/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e/checkMemberGroups
Content-type: application/json

{
    "groupIds": [
        "f448435d-3ca7-4073-8152-a1fd73c0fd09",
        "bd7c6263-4dd5-4ae8-8c96-556e1c0bece6",
        "93670da6-d731-4366-94b5-abed40b6016b",
        "f5484ab1-4d4d-41ec-a9b8-754b3957bfc7",
        "c9103f26-f3cf-4004-a611-2a14e81b8f79"
    ]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)",
    "value": [
        "f448435d-3ca7-4073-8152-a1fd73c0fd09",
        "93670da6-d731-4366-94b5-abed40b6016b",
        "f5484ab1-4d4d-41ec-a9b8-754b3957bfc7",
        "c9103f26-f3cf-4004-a611-2a14e81b8f79"
    ]
}

Example 2: Check group memberships for the signed-in user

Request

HTTP

POST https://graph.microsoft.com/v1.0/me/checkMemberGroups
Content-type: application/json

{
  "groupIds": [
        "fee2c45b-915a-4a64b130f4eb9e75525e",
        "4fe90ae065a-478b9400e0a0e1cbd540"
  ]
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)",
  "value": [
        "fee2c45b-915a-4a64-b130-f4eb9e75525e"
  ]
}