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

Os grupos externos permitem gerenciar permissões para exibir itens externos em uma conexão do Microsoft Graph e conectar-se a fontes de dados fora dos grupos do Microsoft Entra.

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

No entanto, para fontes de dados que usam grupos que não são do Microsoft Entra ID ou construções semelhantes a grupos, como perfis do Salesforce, unidades de negócios do Dynamics, grupos do SharePoint, grupos locais do ServiceNow ou grupos locais do Confluence, recomendamos que você use grupos externos.

Cenários comuns de grupo externo

Veja a seguir exemplos comuns de grupos específicos de aplicativos que não são do Microsoft Entra ID.

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 no 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. Eles são específicos 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.

Usar grupos externos em sua conexão

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

1. Para cada grupo que não for do Microsoft Entra ID, 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 sincronia.

Criar um grupo externo

Os grupos externos pertencem a uma conexão. Siga estas etapas para criar grupos externos em suas conexões:

1. Use a API de grupos no Microsoft Graph. O exemplo a seguir mostra como criar um grupo externo.

   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 seguros para URL e nome de arquivo. Tem um limite de 128 caracteres.

   Um grupo externo pode conter um ou mais dos seguintes:

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

3. Depois de criar o grupo, você pode adicionar membros a ele. Os exemplos a seguir mostram como adicionar membros a um grupo externo.

   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 usuários e grupos do Microsoft Entra, 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" 
  } 
} 

Manter associações a grupos externos em sincronia

Mantenha a associação de seu grupo externo atualizada no Microsoft Graph. Quando as associações forem alteradas em seu grupo personalizado, verifique se a alteração é 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 a grupo. Para obter mais informações, consulte externalGroup e externalGroupMember.

Conteúdo relacionado

• Saiba mais sobre os limites de API dos conectores do Copilot
• Trabalhar com a API de conectores do Copilot