Usar grupos externos para gerenciar permissões para fontes de dados de conectores do Microsoft Graph

Grupos externos permitem que você gerencie permissões para exibir itens externos em uma conexão do Microsoft Graph e conectar-se a fontes de dados fora Microsoft Entra grupos.

Para fontes de dados que dependem de Microsoft Entra usuários e grupos, você define permissões em itens externos associando uma ACL (lista de controle de acesso) a um usuário Microsoft Entra e ID de grupo ao criar ou atualizar os itens externos.

No entanto, para fontes de dados que usam grupos não Azure AD ou construtores semelhantes a grupos, como Perfis salesforce, Dynamics Business Units, grupos do SharePoint, grupos locais do ServiceNow ou grupos locais de Confluence, recomendamos que você use grupos externos.

Cenários comuns de grupo externo

A seguir estão exemplos comuns de grupo não Azure AD específicos do aplicativo.

O Microsoft Dynamics 365 permite que os clientes estruturem seus CRMs com unidades de negócios e equipes. As informações de associação dessas unidades de negócios e equipes não são armazenadas em Microsoft Entra ID.

A imagem a seguir mostra a estrutura das unidades de negócios e equipes.

O Salesforce usa perfis, funções e conjuntos de permissões para autorização. Elas são específicas do Salesforce e as informações de associação não estão disponíveis no Microsoft Entra ID.

A imagem a seguir mostra a estrutura das informações de associação no Salesforce.

Usando grupos externos em sua conexão

Para usar grupos externos em sua conexão, siga estas etapas:

1. Para cada grupo não Azure AD, use a API de grupos para criar um grupo externo no Microsoft Graph.
2. Use o grupo externo ao definir a ACL para seus itens externos conforme necessário.
3. Mantenha a associação dos grupos externos atualizada e em sincronização.

Criar um grupo externo

Grupos externos pertencem a uma conexão. Para criar grupos externos em suas conexões, siga estas etapas:

1. Use a API de grupos no Microsoft Graph, conforme mostrado no exemplo a seguir.

   Observação

   O displayName e a descrição são campos opcionais.

   POST /external/connections/{connectionId}/groups
   
   { 
     "id": "contosoEscalations", 
     "displayName": "Contoso Escalations", 
     "description": "Tier-1 escalations within Contoso"
   } 
   

2. Forneça um identificador ou um nome no campo ID. Use esse valor para chamar o grupo externo em solicitações subsequentes.

   Observação

   O campo ID permite que você use conjuntos de caracteres Base64 com segurança de nome de arquivo e URL. Ele tem um limite de 128 caracteres.

   Um grupo externo pode conter um ou mais dos seguintes:

   • Um usuário Microsoft Entra.
   • Um grupo Microsoft Entra.
   • Outro grupo externo, incluindo grupos externos aninhados.

3. Depois de criar o grupo, você pode adicionar membros ao grupo, conforme mostrado nos exemplos a seguir.

   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"
   }
   

Usar grupos externos na ACL

Você pode usar grupos externos ao definir ACLs para itens externos, conforme mostrado no exemplo a seguir. Além de Microsoft Entra usuários e grupos, um item externo pode ter grupos externos em suas entradas de controle de acesso.

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": "john@contoso.com" 
  }, 
  "content": { 
    "value": "<h1>Error in payment gateway</h1><p>Error details...</p>", 
    "type": "html" 
  } 
} 

Observação

Você pode usar grupos externos em ACLs antes mesmo de os grupos serem criados.

Manter as associações de grupo externas em sincronização

Mantenha a associação do grupo externo atualizada no Microsoft Graph. Quando as associações mudarem em seu grupo personalizado, certifique-se de que a alteração seja refletida no grupo externo em um momento que funcione para suas necessidades.

Gerenciar grupos externos e associação

Você pode usar a API de grupos para gerenciar seus grupos externos e associação de grupo. Para obter detalhes, consulte externalGroup e externalGroupMember.

Observação

Um usuário deve ter menos de 2.049 associações de grupo de segurança externa, incluindo associações diretas e indiretas. Quando esse limite é excedido, os resultados da pesquisa se tornam imprevisíveis. Consultas de usuários com mais de 10.000 grupos de segurança externa falharão com uma 400 resposta.

Conteúdo relacionado

• Saiba mais sobre os limites da API de conectores do Microsoft Graph
• Trabalhar com a API de conectores do Microsoft Graph
• Use o Postman com a API de conectores do Microsoft Graph