Entender o consentimento específico do recurso para o Microsoft Graph e o SharePoint Online

Historicamente no Microsoft SharePoint, local e online, houve a capacidade de registrar aplicativos no ACS (Serviços de Controle de Acesso) do Azure com permissões granulares direcionadas apenas a coleções de sites específicas. Por meio dessa técnica, você foi capaz de autorizar um aplicativo personalizado a ler, gravar, gerenciar ou ter controle total em coleções de sites específicas com permissões somente de aplicativo.

No entanto, o ACS não é mais a melhor opção para gerenciar o registro e a segurança do aplicativo para o SharePoint. Você deve contar com Microsoft Entra (anteriormente registro de aplicativo do Azure Active Directory) e OAuth. Por padrão, quando você registra um aplicativo no Microsoft Entra e pode configurar permissões de aplicativo do Microsoft Graph, como Sites.Read.All, Sites.ReadWrite.All, Sites.Manage.All ou Sites.FullControl.All, que são permissões que visam todas as coleções de sites no locatário de destino, como a palavra All implica no nome dos escopos de permissão.

O destino All nem sempre é bem-vindo pelos clientes, em particular por clientes corporativos com milhares de coleções de sites, dispostos a ter permissões mais granulares, podendo selecionar as coleções de sites de destino em que o aplicativo deve ter permissões de leitura, gravação, gerenciamento ou controle completo.

Se preferir, você pode watch o vídeo a seguir, em vez de ler o artigo inteiro, que ainda pode considerar como uma referência muito mais detalhada.

Com o RSC (Consentimento Específico do Recurso) você pode registrar aplicativos em Microsoft Entra e conceder-lhes permissões somente de aplicativo que podem direcionar apenas coleções de sites específicas, como você costumava fazer com o ACS. Neste artigo, você aprenderá a se beneficiar dessa funcionalidade.

Registrar um aplicativo com permissões de Consentimento Específico do Recurso

Para registrar um aplicativo Microsoft Entra com permissão RSC, basta registrar um aplicativo regular no Microsoft Entra. No entanto, ao configurar as permissões de API do aplicativo, em vez de selecionar qualquer um dos Sites.<alguma coisa>. Todas as permissões de aplicativo para o Microsoft Graph, você precisa escolher a permissão Sites.Selected application, conforme ilustrado na captura de tela a seguir.

Em seguida, um administrador de locatário, que eventualmente ainda pode ser você, terá que conceder a permissão de aplicativo Sites.Selected para o aplicativo.

Há também uma permissão de aplicativo Sites.Selected para SharePoint Online, caso você queira consumir o SharePoint Online por meio de APIs REST, em vez de consumir o SharePoint Online por meio do Microsoft Graph. Na captura de tela a seguir, você pode ver como a permissão Sites.Selected para SharePoint Online se parece em Microsoft Entra.

Concedendo permissões a uma coleção de sites específica

Depois que a permissão de aplicativo Sites.Selected for atribuída e concedida, o aplicativo ainda não poderá acessar nenhuma coleção de sites de destino. Para poder acessar qualquer site de destino, você precisará de um administrador global do locatário ou de um aplicativo com a permissão Sites.FullControl.All para conceder permissões explícitas para os sites de destino selecionados.

Concessão de permissões por meio do Microsoft Graph

Para conceder permissões aos sites de destino selecionados, você pode usar uma solicitação POST API do Graph Microsoft, visando a seguinte URL:

https://graph.microsoft.com/v1.0/sites/{siteId}/permissions

Onde o {siteId} é a ID exclusiva do Microsoft Graph da coleção de sites de destino, com um formato como o seguinte:

contoso.sharepoint.com,5a58bb09-1fba-41c1-8125-69da264370a0,9f2ec1da-0be4-4a74-9254-973f0add78fd

O corpo da solicitação HTTP POST deve ter uma estrutura como o trecho de código a seguir.

{
  "roles": ["{role}"],
  "grantedToIdentities": [{
    "application": {
      "id": "{clientId}",
      "displayName": "{application-name}"
    }
  }]
}

Onde {role} pode ser qualquer um dos seguintes valores ou uma matriz de qualquer um dos seguintes valores:

• leia: fornece a capacidade de ler os metadados e o conteúdo do item.
• write: fornece a capacidade de ler e modificar os metadados e o conteúdo do item.
• gerenciar: fornece a capacidade de ler e modificar os metadados e o conteúdo do item e gerenciar o site.
• fullcontrol: fornece controle total sobre o site e seu conteúdo.

O atributo {client-id} é a ID real do cliente do aplicativo Microsoft Entra e {nome do aplicativo} é uma descrição para o aplicativo.

A resposta que você receberá do Microsoft Graph será semelhante ao arquivo JSON a seguir.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites('contoso.sharepoint.com,5a58bb09-1fba-41c1-8125-69da264370a0,9f2ec1da-0be4-4a74-9254-973f0add78fd')/permissions/$entity",
  "id": "aTowaS50fG1zLnNwLmV4dHxlMDBiNWUzZi0yMzI1LTQ3MWQtOTljZi1iOGM5ZDlmNDU2N2FANmM5NDA3NWEtZGEwYS00YzZhLTg0MTEtYmFkZjY1MmU4YjUz",
  "roles": [
    "write"
  ],
  "grantedToIdentitiesV2": [
    {
      "application": {
        "displayName": "AddInGuidanceRSC",
        "id": "e00b5e3f-2325-471d-99cf-b8c9d9f4567a"
      }
    }
  ],
  "grantedToIdentities": [
    {
      "application": {
        "displayName": "AddInGuidanceRSC",
        "id": "e00b5e3f-2325-471d-99cf-b8c9d9f4567a"
      }
    }
  ]
}

Observe que a propriedade ID na resposta representa a ID exclusiva para identificar a permissão atribuída sob medida. Usando essa ID, você também pode gerenciar permissões selecionadas já atribuídas usando REST e fazendo solicitações GET, PATCH ou DELETE direcionadas ao ponto de extremidade permissions/{permission-id} da coleção de sites de destino, em que {permission-id} representa a ID exclusiva da permissão.

Claramente, você também pode optar por usar o SDK do Microsoft Graph para gerenciar as permissões, em vez de depender de solicitações HTTP de baixo nível.

Concessão de permissões por meio do PowerShell PnP

Para conceder e gerenciar permissões para os sites de destino selecionados, você também pode usar um conjunto de cmdlets do PowerShell PnP:

• Grant-PnPAzureAdAppSitePermission: adiciona permissões para um determinado registro de aplicativo Microsoft Entra.
• Get-PnPAzureAdAppSitePermission: retorna Microsoft Entra permissões de aplicativo para um site.
• Set-PnPAzureAdAppSitePermission: atualiza as permissões para um determinado registro de aplicativo Microsoft Entra.
• Revoke-PnPAzureAdAppSitePermission: revoga permissões para um determinado aplicativo.

Por exemplo, se você quiser conceder permissão de gravação a um aplicativo de destino para um site selecionado, poderá usar a seguinte sintaxe do PowerShell:

Grant-PnPAzureADAppSitePermission -AppId {client-id} -DisplayName {display-name} -Permissions <Read|Write|Manage|FullControl> -Site {site-object}

Como foi com o ponto de extremidade do Microsoft Graph, o argumento {client-id} é a ID do cliente do aplicativo Microsoft Entra e {display-name} é uma descrição para o aplicativo. O argumento Permissões pode ser um ou mais dos seguintes valores:

• Leia: fornece a capacidade de ler os metadados e o conteúdo do item.
• Gravação: fornece a capacidade de ler e modificar os metadados e o conteúdo do item.
• Gerenciar: fornece a capacidade de ler e modificar os metadados e o conteúdo do item e gerenciar o site.
• FullControl: fornece controle total sobre o site e seu conteúdo.

O valor {site-object} pode ser um objeto de site recuperado usando o cmdlet Get-PnPSite ou pode ser omitido para o destino como o site selecionado ao qual você está conectado ao cmdlet Connect-PnPOnline .

A saída de tal comando será semelhante à seguinte, no console do PowerShell.

Id    : aTowaS50fG1zLnNwLmV4dHxlMDBiNWUzZi0yMzI1LTQ3MWQtOTljZi1iOGM5ZDlmNDU2N2FANmM5NDA3NWEtZGEwYS00YzZhLTg0MTEtYmFkZjY
        1MmU4YjUz
Roles : {fullcontrol}
Apps  : {AddInGuidanceRSC, e00b5e3f-2325-471d-99cf-b8c9d9f4567a}

Observe que o cmdlet retorna a permissão concedida e a ID exclusiva do objeto de permissão.

Caso deseje atualizar uma atribuição de permissão para um site selecionado, você pode usar uma sintaxe do PowerShell como a seguinte:

Set-PnPAzureADAppSitePermission -PermissionId {permission-id} -Permissions <Read|Write|Manage|FullControl>

Onde o argumento {permission-id} é a ID que você tem de volta ao invocar o cmdlet Grant-PnPAzureADAppSitePermission .

Se você quiser revogar uma concessão de permissão de um site selecionado, poderá usar o cmdlet Revoke-PnPAzureADAppSitePermission com a sintaxe a seguir.

Revoke-PnPAzureADAppSitePermission -PermissionId {permission-id}

Consumindo a coleção de sites de destino

Depois de registrar um aplicativo Microsoft Entra com a permissão do aplicativo Sites.Selected, com o Microsoft Graph ou com o SharePoint Online, ou com ambos, você pode começar a consumir as coleções de sites selecionadas de acordo com as permissões concedidas.

Você precisa solicitar um token de acesso somente aplicativo de Microsoft Entra e começar a consumir as coleções de sites selecionadas. Se você direcionar um site, para o qual seu aplicativo recebeu permissões, você fará isso acontecer com êxito. Se você tiver como destino qualquer outra coleção de sites, para a qual seu aplicativo não recebeu permissões, seu código falhará e você verá uma exceção "Acesso negado".

Se você quiser saber mais sobre como consumir o SharePoint Online por meio da API REST do SharePoint ou por meio do Microsoft Graph usando um token somente aplicativo, você pode ler a seção Consumindo o SharePoint Online no modo somente aplicativo por meio de um aplicativo registrado Azure AD do artigo Atualizando aplicativos do SharePoint do Serviço de Controle de Acesso do Azure para Microsoft Entra.

Conteúdo recomendado

Você pode encontrar informações adicionais sobre este artigo lendo os seguintes documentos:

• Atualizar aplicativos do SharePoint do Serviço de Controle de Acesso do Azure para Microsoft Entra
• Tipo de recurso permission
• O controle do acesso ao aplicativo em coleções específicas de sites do SharePoint já está disponível no Microsoft Graph