group: evaluateDynamicMembership

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Evaluate whether a user or device is or would be a member of a dynamic group. The membership rule is returned along with other details that were used in the evaluation. You can complete this operation in the following ways:

  • Evaluate whether a user or device is a member of a specified dynamic group.
  • Evaluate whether a user or device would be a member of a dynamic group based on the ID of the user or device and a membership rule.

Permissions

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

Evaluate dynamic membership with member ID and group ID

Permission type Permissions (from least to most privileged)
Delegated (work or school account) For user: Group.Read.All and User.Read.All, Directory.Read.All
For device: Group.Read.All and Device.Read.All, Directory.Read.All
Delegated (personal Microsoft account) Not supported.
Application Not supported.

Evaluate dynamic membership with member ID and membership rule

Permission type Permissions (from least to most privileged)
Delegated (work or school account) For user: User.Read.All, Directory.Read.All
For device: Device.Read.All, Directory.Read.All
Delegated (personal Microsoft account) Not supported.
Application Not supported.

HTTP request

POST /groups/{id}/evaluateDynamicMembership
POST /groups/evaluateDynamicMembership

Request headers

Name Description
Authorization Bearer {token}
Content-type application/json

Request body

In the request body, supply the required properties.

The following table lists the properties that are required when you evaluate group membership.

Parameter Type Description
memberId String collection memberId is the object Id of the user or device to be evaluated.
membershipRule String collection The rule that is used for membership evaluation. If this property is not provided, the rule for the existing group is evaluated. If this property is provided, the user or device is evaluated for possible membership in a group with the same rule. For more information, see Dynamic membership rules for groups in Azure Active Directory.

Response

If successful, this method returns a 200 OK response code and an evaluateDynamicMembershipResult object.

Examples

Example 1: Evaluate if a user or device is a member of an existing group

Request

The following is an example of the request.

POST https://graph.microsoft.com/beta/groups/{id}/evaluateDynamicMembership
Content-type: application/json

{
  "memberId": "319b41e8-d9e4-42f8-bdc9-741113f48b33"
}

Response

The following is an example of the response.

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

{
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")",
  "membershipRuleEvaluationResult": true,
  "membershipRuleEvaluationDetails": {
    "expressionResult": true,
    "expression": "user.displayName -startsWith \"EndTestUser\"",
    "propertyToEvaluate": {
      "propertyName": "displayName",
      "propertyValue": "EndTestUser001"
    }
  }
}

Example 2: Evaluate if a user or device would be a member of a group based on a membership rule

Request

The following is an example of the request.

POST https://graph.microsoft.com/beta/groups/evaluateDynamicMembership
Content-type: application/json

{
  "memberId": "319b41e8-d9e4-42f8-bdc9-741113f48b33",
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")"
}

Response

The following is an example of the response.

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

{
  "membershipRule": "(user.displayName -startsWith \"EndTestUser\")",
  "membershipRuleEvaluationResult": true,
  "membershipRuleEvaluationDetails": {
    "expressionResult": true,
    "expression": "user.displayName -startsWith \"EndTestUser\"",
    "propertyToEvaluate": {
      "propertyName": "displayName",
      "propertyValue": "EndTestUser001"
    }
  }
}