AtribuiçÀo de Acesso Granular a Sites SharePoint via Microsoft Graph API

A gestÀo de permissÀµes granulares para aplicaçÀµes que necessitam de aceder a sites especÀ­ficos do SharePoint é um requisito comum em implementaçÀµes empresariais. Este artigo apresenta uma abordagem detalhada sobre como configurar e atribuir permissÀµes programaticamente a uma Service Principal para aceder a sites SharePoint utilizando o Microsoft Graph API e Postman.

Contexto

Nas organizaçÀµes que utilizam o SharePoint como plataforma de colaboraçÀo e gestÀo documental, é frequentemente necessÀ¡rio permitir que aplicaçÀµes de terceiros ou sistemas internos acedam a conteÀºdos especÀ­ficos. A utilizaçÀo de permissÀµes granulares é essencial para garantir o princÀ­pio do mÀ­nimo privilégio, permitindo apenas o acesso necessÀ¡rio e suficiente para o funcionamento da aplicaçÀo.

Neste guia, vamos explorar como:

1. Criar registos de aplicaçÀµes no Microsoft Entra ID (anteriormente Azure AD)
2. Configurar diferentes nÀ­veis de permissÀµes para acesso ao SharePoint
3. Utilizar o Postman para obter tokens de autenticaçÀo
4. Atribuir permissÀµes granulares a uma Service Principal para sites especÀ­ficos

Pré-requisitos

• Conta de administrador global ou de administrador de aplicaçÀµes no Microsoft Entra ID
• Postman instalado no seu ambiente
• Conhecimentos bÀ¡sicos de REST APIs e JSON
• Site(s) SharePoint Online jÀ¡ criado(s) e configurado(s)

CriaçÀo e ConfiguraçÀo de AplicaçÀµes no Microsoft Entra ID

Começaremos por criar duas aplicaçÀµes distintas no Microsoft Entra ID, cada uma com diferentes nÀ­veis de permissÀo para aceder ao SharePoint:

API 1: AplicaçÀo com Acesso Total ao SharePoint

Esta aplicaçÀo terÀ¡ permissÀµes para aceder a todos os sites SharePoint na organizaçÀo.

1. Aceda ao portal do Microsoft Entra ID
2. Navegue para GestÀo de Identidades > AplicaçÀµes > Registos de aplicaçÀµes
3. Clique em Novo registo
4. Preencha os seguintes detalhes:
   • Nome: SP-AllSites-FullControl
   • Tipos de conta suportados: Contas apenas neste diretório organizacional
   • URI de redirecionamento: (Deixe em branco para este cenÀ¡rio)
5. Clique em Registar

Após o registo da aplicaçÀo, proceda À  configuraçÀo das permissÀµes:

1. No menu lateral da aplicaçÀo, aceda a PermissÀµes API
2. Clique em Adicionar uma permissÀo
3. Selecione Microsoft Graph
4. Escolha PermissÀµes de aplicaçÀo
5. Procure e selecione Sites.FullControl.All
6. Clique em Adicionar permiss˵es
7. Importante: Clique no botÀo Conceder consentimento de administrador para esta permissÀo

Agora configure um segredo para a aplicaçÀo:

1. No menu lateral, aceda a Certificados e segredos
2. Em Segredos do cliente, clique em Novo segredo do cliente
3. Forneça uma descriçÀo como “Chave para acesso via Graph API”
4. Selecione a validade adequada (por exemplo, 1 ano)
5. Clique em Adicionar
6. IMPORTANTE: Copie e guarde o valor do segredo num local seguro, pois nÀo serÀ¡ possÀ­vel visualizÀ¡-lo novamente

API 2: AplicaçÀo com Acesso Limitado a Sites EspecÀ­ficos

Esta aplicaçÀo terÀ¡ permissÀµes apenas para aceder a sites SharePoint previamente configurados.

1. Aceda ao portal do Microsoft Entra ID
2. Navegue para GestÀo de Identidades > AplicaçÀµes > Registos de aplicaçÀµes
3. Clique em Novo registo
4. Preencha os seguintes detalhes:
   • Nome: SP-SelectedSites-Access
   • Tipos de conta suportados: Contas apenas neste diretório organizacional
   • URI de redirecionamento: (Deixe em branco para este cenÀ¡rio)
5. Clique em Registar

Após o registo da aplicaçÀo, proceda À  configuraçÀo das permissÀµes:

1. No menu lateral da aplicaçÀo, aceda a PermissÀµes API
2. Clique em Adicionar uma permissÀo
3. Selecione Microsoft Graph
4. Escolha PermissÀµes de aplicaçÀo
5. Procure e selecione Sites.Selected
6. Clique em Adicionar permiss˵es
7. Importante: Clique no botÀo Conceder consentimento de administrador para esta permissÀo

Agora configure um segredo para a aplicaçÀo:

1. No menu lateral, aceda a Certificados e segredos
2. Em Segredos do cliente, clique em Novo segredo do cliente
3. Forneça uma descriçÀo como “Chave para acesso via Graph API”
4. Selecione a validade adequada (por exemplo, 1 ano)
5. Clique em Adicionar
6. IMPORTANTE: Copie e guarde o valor do segredo num local seguro, pois nÀo serÀ¡ possÀ­vel visualizÀ¡-lo novamente

AtribuiçÀo de PermissÀµes Utilizando o Postman

Agora que temos as aplicaçÀµes criadas e configuradas no Microsoft Entra ID, vamos utilizar o Postman para obter tokens de acesso e atribuir permissÀµes granulares.

1. Obter Token de Acesso para a API 1

Primeiro, precisamos obter um token de acesso para a aplicaçÀo com permissÀo total:

1. Abra o Postman e crie uma nova requisiçÀo POST
2. Introduza o URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
   • Substitua {tenant-id} pelo ID do seu tenant (pode ser encontrado no portal do Entra ID)
3. Na secçÀo Body, selecione x-www-form-urlencoded
4. Adicione os seguintes parâmetros:

5. Clique em Send
6. No corpo da resposta, copie o valor do campo access_token para utilizaçÀo nas próximas etapas

⚠️ Aviso de Segurança
Os tokens de acesso sÀo credenciais sensÀ­veis. NÀo os partilhe ou armazene em locais nÀo seguros.

2. Obter o ID do Site SharePoint

Antes de atribuir permiss˵es, precisamos obter o ID do site SharePoint para o qual queremos conceder acesso:

1. No Postman, crie uma nova requisiçÀo GET
2. Introduza o URL: https://graph.microsoft.com/v1.0/sites/{siteurl}
   • Substitua {siteurl} por uma das seguintes opçÀµes:
     • root (para o site raiz)
     • contoso.sharepoint.com:/sites/contoso (formato hostname:path)
3. Na secçÀo Headers, adicione:
   • Key: Authorization
   • Value: Bearer {access_token} (substitua pelo token obtido anteriormente)
4. Clique em Send
5. Na resposta, localize e guarde o valor do campo id - este é o identificador Àºnico do site SharePoint

3. Atribuir PermissÀµes Granulares À  API 2

Com o token de acesso e o ID do site, agora podemos atribuir permissÀµes granulares À  nossa segunda aplicaçÀo:

1. No Postman, crie uma nova requisiçÀo POST
2. Introduza o URL: https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
   • Substitua {site-id} pelo ID do site obtido no passo anterior
3. Na secçÀo Headers, adicione:
   • Key: Authorization
   • Value: Bearer {access_token} (substitua pelo token obtido anteriormente)
   • Key: Content-Type
   • Value: application/json
4. Na secçÀo Body, selecione raw e escolha JSON
5. Adicione o seguinte JSON, substituindo o ID da aplicaçÀo pelo ID da API 2 (SP-SelectedSites-Access):

{
  "roles": ["read", "write"],
  "grantedToIdentities": [{
    "application": {
      "id": "e9d55f72-aba1-41a0-97ee-f27b8a39957b",
      "displayName": "SP-SelectedSites-Access"
    }
  }]
}

Nota: O JSON acima concede permissÀµes de leitura e escrita. Ajuste conforme necessÀ¡rio:

• Para acesso somente leitura, utilize apenas ["read"]
• Para acesso total, utilize ["read", "write", "manage"]

6. Clique em Send
7. Verifique a resposta para confirmar que a permissÀo foi atribuÀ­da com sucesso

VerificaçÀo das PermissÀµes

Para confirmar que as permissÀµes foram atribuÀ­das corretamente:

1. No Postman, crie uma nova requisiçÀo GET
2. Introduza o URL: https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
   • Substitua {site-id} pelo ID do site
3. Na secçÀo Headers, adicione:
   • Key: Authorization
   • Value: Bearer {access_token}
4. Clique em Send
5. Verifique na resposta se a aplicaçÀo aparece na lista de permissÀµes do site

UtilizaçÀo da API 2 para Aceder ao SharePoint

Agora que a API 2 tem permissÀµes especÀ­ficas para o site, pode obter um token para esta aplicaçÀo e utilizar os recursos do SharePoint:

1. Obtenha um token de acesso para a API 2 (similarmente ao processo para a API 1)
2. Utilize esse token para aceder aos recursos do site SharePoint através do Microsoft Graph API

Por exemplo, para listar itens numa biblioteca de documentos:

GET https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items
Authorization: Bearer {access_token-api2}

ConsideraçÀµes de Segurança

Ao implementar este tipo de integraçÀo, considere as seguintes prÀ¡ticas recomendadas de segurança:

• Utilize sempre o princÀ­pio do mÀ­nimo privilégio ao atribuir permissÀµes
• Configure a expiraçÀo de segredos de aplicaçÀµes para perÀ­odos adequados ao contexto
• Implemente uma soluçÀo segura para armazenamento e gestÀo de segredos
• Monitorize regularmente as permissÀµes atribuÀ­das À s aplicaçÀµes
• Considere a utilizaçÀo de certificados em vez de segredos para autenticaçÀo em ambientes de produçÀo
• Implemente um processo de revisÀo periódica de permissÀµes

ConclusÀo

A atribuiçÀo de permissÀµes granulares a aplicaçÀµes para aceder a sites especÀ­ficos do SharePoint é uma capacidade poderosa que permite desenvolver integraçÀµes seguras e eficazes. Utilizando o Microsoft Graph API, é possÀ­vel automatizar este processo e gerir programaticamente as permissÀµes, facilitando a implementaçÀo de soluçÀµes empresariais que necessitam de interagir com o SharePoint.

Esta abordagem garante que as aplicaçÀµes tenham apenas o nÀ­vel de acesso necessÀ¡rio para o seu funcionamento, reforçando a segurança global do ambiente Microsoft 365 da sua organizaçÀo.

Recursos Adicionais

• DocumentaçÀo oficial do Microsoft Graph para permissÀµes de Sites
• Guia de autenticaçÀo para Microsoft Graph
• PermissÀµes de aplicaçÀo do Microsoft Graph