Microsoft Entra ID Governance
Governance

Author Microsoft Entra resource policies with Rego (preview)

In brief

The documentation now includes detailed Microsoft Graph group-creation input, delegated caller context, member bindings, URI segments, and a `fetchAsPolicy()` example for retaining user owners during owner removal.

What Entra admins need to know

Administrators can use the updated examples to author and validate custom Rego resource policies more accurately.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

Author Microsoft Entra resource policies with Rego (preview)

Use RegoRego to author a custom Microsoft Entra resource policy when a built-in policy doesn't meet your requirements. Rego evaluates structured data against declarative rules. Resource policy uses those rules to identify noncompliant Microsoft Graph requests.

You don't need to author Rego to assign a built-in policy.

| input.request.resourceKeys | Keys of the target resource, when the request identifies an existing resource. | | input.resource | The normalized request body, when the request has a body. |

For example, the following request creates a security group with two existing users as members. It includes the required group properties and uses [email protected] for the member references:

POST https://graph.microsoft.com/v1.0/groups
Content-Type: application/json

{
  "displayName": "Contoso-Inventory-Takers",
  "groupTypes": [],
  "mailEnabled": false,
  "mailNickname": "contoso-inventory-takers",
  "securityEnabled": true,
  "[email protected]": [
    "https://graph.microsoft.com/v1.0/users/11111111-1111-1111-1111-111111111111",
    "https://graph.microsoft.com/v1.0/users/22222222-2222-2222-2222-222222222222"
  ]
}

For a delegated caller, the corresponding normalized request body for application creationinput can include:look like this. All member, application, tenant, and caller IDs in these examples are placeholders:

{
  "request": {
    "apiVersion": "v1.0",
    "authContext": {
      "isAppOnly": false,
      "appid": "33333333-3333-3333-3333-333333333333",
      "tid": "44444444-4444-4444-4444-444444444444",
      "oid": "55555555-5555-5555-5555-555555555555",
      "idtyp": "user"
    },
    "uriSegments": [
      {
        "name": "groups",
        "type": "microsoft.graph.group"
      }
    ]
  },
  "resource": {
    "displayName": "Contoso-InventoryInventory-Takers",
    "signInAudiencegroupTypes": [],
    "mailEnabled": false,
    "mailNickname": "AzureADMyOrgcontoso-inventory-takers",
    "securityEnabled": true,
    "[email protected]": [
      "https://graph.microsoft.com/v1.0/users/11111111-1111-1111-1111-111111111111",
      "https://graph.microsoft.com/v1.0/users/22222222-2222-2222-2222-222222222222"
    ]
  }
}

This fragment illustratesThe member bindings remain an array of URLs in input.resource. In Rego, access them with input.resource["[email protected]"].

The request URI contributes only the groups segment to input.request.uriSegments; it isnthe member bindings don't add URI segments. input.request.resourceKeys is absent because the request creates a complete normalized input document.group rather than addressing an existing group.

Properties can be absent. For example, the request might not have a body or a target resource key. Don't treat an absent property as proof of a particular identity type. input.request.authContext.isAppOnly is a Boolean.

The function takes a request object containing relativePathUri, including the Microsoft Graph API version. The result contains an HTTP response code and response data.

Example: Retain at least two user owners for a group

Suppose a group must retain at least two owners of type user. A client submits the following request to remove an owner:

DELETE /beta/groups/{groupId}/owners/{ownerId}/$ref

The policy needs the current owners to decide whether that removal would meet the requirement. It uses fetchAsPolicy() to make a separate read-only GET request:

GET /beta/groups/{groupId}/owners?$select=id,displayName

The GET request returns the owners collection, which fetchAsPolicy() exposes in data.value. The following illustrative result contains two user owners and one service-principal owner:

{
  "code": 200,
  "data": {
    "value": [
      {
        "@odata.type": "#microsoft.graph.user",
        "id": "00000000-0000-0000-0000-000000000001",
        "displayName": "Owner A"
      },
      {
        "@odata.type": "#microsoft.graph.user",
        "id": "00000000-0000-0000-0000-000000000002",
        "displayName": "Owner B"
      },
      {
        "@odata.type": "#microsoft.graph.servicePrincipal",
        "id": "00000000-0000-0000-0000-000000000003",
        "displayName": "Group automation"
      }
    ]
  }
}

The following denyfragment makes that read and filters the returned collection to user owners. It excludes the owner being removed and checks that an existing application's display name starts with Contoso- after an update. Use it as the deny logic for an application policy whose selector sets operations to ["updateOrUpsert"]. It uses the proposed name when the update supplies displayName, or the existing name from the read response when the update omits it:at least two distinct user IDs remain:

default deny := true

deny := false if {
    group_id := input.request.uriSegments[0].keys.id
    removed_owner_id := input.request.uriSegments[1].keys.id

    response := fetchAsPolicy({
        "relativePathUri": sprintf(
            "/%s/applications/groups/%s?s/owners?$select=id,displayName",
            [input.request.apiVersion, input.request.resourceKeys.id]group_id]
        )
    })
    response.code == 200

    name_after_updateremaining_user_owner_ids := object.get(
        object.get(input, "resource", {}),
        "displayName",{owner.id |
        some owner in response.data.displayName
    )
    is_string(name_after_update)
    startswith(name_after_update, value
        owner["Contoso-@odata.type")] == "#microsoft.graph.user"
        owner.id != removed_owner_id
    }

    count(remaining_user_owner_ids) >= 2
}

Use this pattern only when normalized input containsWith the required resource key. The exampleillustrated collection, removing Owner A or Owner B reports noncompliance ifbecause only one user owner would remain. Removing the read fails, required data is missing, orservice-principal owner satisfies the name check fails.requirement because both user owners remain. The assignment's enforcement mode determines whether that resultnoncompliance blocks the request.

Additional reads increase latency and consume Microsoft Graph request capacity. Request only the properties you need, prefer a specific resource to a collection, and don't rely on paging. Keep calls within the additional-read limits

Additional reads increase latency and consume Microsoft Graph request capacity. Request only the properties you need, prefer a specific resource to a collection, and don't rely on paging. Keep calls within the additional-read limits.

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…