Edit

Share via

Use external groups to manage permissions to Microsoft Graph connectors data sources

  • Article

External groups let you manage permissions to view external items in a Microsoft Graph connection and connect to data sources outside Microsoft Entra groups.

For data sources that rely on Microsoft Entra users and groups, you set permissions on external items by associating an access control list (ACL) with a Microsoft Entra user and group ID when creating or updating the external items.

However, for data sources that use non-Microsoft Entra ID groups or group-like constructs such as Salesforce Profiles, Dynamics Business Units, SharePoint groups, ServiceNow local groups, or Confluence local groups, we recommend that you use external groups.

Common external group scenarios

The following are common non-Microsoft Entra ID application-specific group examples.

Microsoft Dynamics 365 allows customers to structure their CRMs with business units and teams. The membership information for these business units and teams isn't stored in Microsoft Entra ID.

The following image shows the structure of the business units and teams.


Diagram of a structure in Dynamics 365. A business unit has a team and a manager under it. This manager has other users.

Salesforce uses profiles, roles, and permission sets for authorization. These are specific to Salesforce, and the membership information isn't available in Microsoft Entra ID.

The following image shows the structure of the membership information in Salesforce.


Diagram of a structure of roles in Salesforce. The role of vice president of sales is at the top level of the hierarchy and has three subordinates, namely, the head of sales operations, the head of sales, and the head of account management. The head of sales operations has a sales operations manager as a subordinate. The head of sales has a sales development manager as a subordinate.

Use external groups in your connection

To use external groups in your connection, follow these steps:

  1. For each non-Microsoft Entra ID group, use the groups API to create an external group in Microsoft Graph.
  2. Use the external group when defining the ACL for your external items as necessary.
  3. Keep the membership of the external groups up to date and in sync.

Create an external group

External groups belong to a connection. Follow these steps to create external groups in your connections:

  1. Use the groups API in Microsoft Graph. The following example shows how to create an external group.

    Note

    The displayName and description are optional fields.

    POST /external/connections/{connectionId}/groups

{ 
  "id": "contosoEscalations", 
  "displayName": "Contoso Escalations", 
  "description": "Tier-1 escalations within Contoso"
} 

  2. Provide either an identifier or a name in the ID field. Use this value to call the external group in subsequent requests.

    Note

    The ID field allows you to use URL and filename-safe Base64 character sets. It has a limit of 128 characters.

    An external group can contain one or more of the following:

    • A Microsoft Entra user.
    • A Microsoft Entra group.
    • Another external group, including nested external groups.

  3. After you create the group, you can add members to it. The following examples show how to add members to an external group.

    POST https://graph.microsoft.com/beta/external/connections/{connectionId}/groups/{groupId}/members

{
  "id": "contosoSupport",
  "type": "group",
  "identitySource": "external"
}

    POST https://graph.microsoft.com/beta/external/connections/{connectionId}/groups/{groupId}/members

{
  "id": "25f143de-be82-4afb-8a57-e032b9315752",
  "type": "user",
  "identitySource": "azureActiveDirectory"
}

    POST https://graph.microsoft.com/beta/external/connections/{connectionId}/groups/{groupId}/members

{
  "id": "99a3b3d6-71ee-4d21-b08b-4b6f22e3ae4b",
  "type": "group",
  "identitySource": "azureActiveDirectory"
}

Use external groups in the ACL

You can use external groups when defining ACLs for external items, as shown in the following example. In addition to Microsoft Entra users and groups, an external item can have external groups in its access control entries.

PUT https://graph.microsoft.com/beta/external/connections/{id}/items/{id} 

Content-type: application/json 
{ 
  "@odata.type": "microsoft.graph.externalItem", 
  "acl": [ 
    { 
      "type": "group", 
      "value": "contosEscalations", 
      "accessType": "grant", 
      "identitySource": "External" 
    }, 
    { 
      "type": "user", 
      "value": "87e9089a-08d5-4d9e-9524-b7bd6be580d5", 
      "accessType": "grant", 
      "identitySource": "azureActiveDirectory" 
    }, 
    { 
      "type": "group", 
      "value": "96fbeb4f-f71c-4405-9f0b-1d6988eda2d2", 
      "accessType": "deny", 
      "identitySource": "azureActiveDirectory" 
    } 
  ], 
  "properties": { 
    "title": "Error in the payment gateway", 
    "priority": 1, 
    "assignee": "[email protected]" 
  }, 
  "content": { 
    "value": "<h1>Error in payment gateway</h1><p>Error details...</p>", 
    "type": "html" 
  } 
} 

Note

You can use external groups in ACLs even before the groups are created.

Keep external group memberships in sync

Keep the membership of your external group up to date in Microsoft Graph. When memberships change in your custom group, make sure that the change is reflected in the external group at a time that works for your needs.

Manage external groups and membership

You can use the groups API to manage your external groups and group membership. For more information, see externalGroup and externalGroupMember.

Note

A user should have less than 2,049 external security group memberships, including direct and indirect memberships. When this limit is exceeded, search results become unpredictable. Queries from users with more than 10,000 external security groups will fail with a 400 response.

Related content