Autorização e API de Segurança do Microsoft Graph

  • Artigo

Os dados de segurança acessíveis através da API de Segurança do Microsoft Graph são confidenciais e protegidos por permissões e funções do Microsoft Entra.

A API de Segurança do Microsoft Graph dá suporte a dois tipos de autorização:

  • Autorização no nível de aplicativo: não há usuário conectado (por exemplo, um cenário SIEM). As permissões concedidas ao aplicativo determinam a autorização.

    Observação

    Esta opção também pode suportar casos em que o RBAC (controle de acesso baseado em função) é gerenciado pelo aplicativo.

  • Autorização delegada pelo utilizador: Um utilizador que seja membro do inquilino do Microsoft Entra tem sessão iniciada. O utilizador tem de ser membro de uma função de Administrador Limitado do Microsoft Entra ID ( Leitor de Segurança ou Administrador de Segurança) para além de terem sido concedidas as permissões necessárias à aplicação.

Se você estiver chamando a API de Segurança do Microsoft Graph no Explorador do Graph:

  • O administrador de inquilinos do Microsoft Entra tem de conceder explicitamente consentimento para as permissões pedidas para a aplicação Graph Explorer.

  • O utilizador tem de ser membro da função de Administrador Limitado do Leitor de Segurança no ID do Microsoft Entra (Leitor de Segurança ou Administrador de Segurança).

    Observação

    O Explorador do Graph não suporta autorização no nível de aplicativo.

Se você estiver chamando a API de Segurança do Microsoft Graph de um aplicativo personalizado ou do seu próprio:

  • O administrador de inquilinos do Microsoft Entra tem de conceder explicitamente consentimento à sua aplicação. Isso é necessário para autorização no nível de aplicativo e autorização delegada pelo usuário.
  • Se estiver a utilizar a autorização delegada pelo utilizador, o utilizador tem de ser membro da função Leitor de Segurança ou Administrador Limitado administrador de segurança no ID do Microsoft Entra.

Gerenciar autorizações nos aplicativos de clientes de API de segurança

Os dados de segurança fornecidos por meio da API de Segurança do Microsoft Graph são confidenciais e devem ser protegidos por mecanismos de autenticação e autorização apropriados. A tabela a seguir lista as etapas para registrar e criar um aplicativo cliente que pode acessar a API de Segurança do Microsoft Graph.

Quem Ação
Desenvolvedor ou proprietário do aplicativo Registar o aplicativo como um aplicativo de empresa.
Administrador de locatários Conceda permissões para o aplicativo.
Administrador de locatários Atribuir funções aos usuários.
Desenvolvedor do aplicativo Entre como usuário e use o aplicativo para acessar a API de Segurança do Microsoft Graph.

O registro do aplicativo define somente quais permissões o mesmo precisa para ser executado. Ele NÃO concede estas permissões ao aplicativo.

O administrador inquilino do Microsoft Entra tem de conceder explicitamente as permissões à aplicação. Isso precisa ser feito por locatário e tem que ser executado sempre que as permissões do aplicativo forem alteradas no portal de registro do aplicativo.

Por exemplo, suponha que tem uma aplicação, dois inquilinos do Microsoft Entra, T1 e T2 e duas permissões, P1 e P2. O processo de autorização será assim:

  • O aplicativo registra para exigir permissão P1.

  • Quando os utilizadores no inquilino T1 obtêm um token do Microsoft Entra para esta aplicação, o token não contém quaisquer permissões.

  • O administrador do Microsoft Entra do inquilino T1 concede explicitamente permissões à aplicação. Quando os utilizadores no inquilino T1 obtêm um token do Microsoft Entra para a aplicação, este conterá a permissão P1.

  • Quando os utilizadores no inquilino T2 obtêm um token do Microsoft Entra para a aplicação, o token não contém permissões porque o administrador do inquilino T2 ainda não concedeu permissões à aplicação. A permissão deve ser concedida por locatário e por aplicativo.

  • O aplicativo agora tem seu registro alterado para requerer as permissões P1 e P2.

  • Quando os utilizadores no inquilino T1 obtêm um token do Microsoft Entra para a aplicação, contém apenas a permissão P1. As permissões concedidas a um aplicativo são registradas como instantâneos do que foi a elas concedido; as mesmas não são alteradas automaticamente depois que o registro do aplicativo (permissão) é alterado.

  • O administrador de locatários T2 concede as permissões P1 e P2 do aplicativo. Agora, quando os utilizadores no inquilino T2 recebem um token do Microsoft Entra para a aplicação, o token conterá as permissões P1 e P2.

    Observação

    Os tokens do Microsoft Entra para a aplicação no inquilino T1 e a aplicação no inquilino T2 contêm permissões diferentes, porque cada administrador de inquilinos concedeu permissões diferentes à aplicação.

  • Para que o aplicativo funcione novamente no locatário T1, o administrador de locatários T1 deve conceder explicitamente as permissões P1 e P2 ao aplicativo.

Registrar um aplicativo com o ponto de extremidade da plataforma de identidade da Microsoft

Para registrar um aplicativo com o ponto de extremidade da plataforma de identidade da Microsoft, você precisará:

  • Nome do aplicativo: uma cadeia de caracteres usada para o nome do aplicativo.
  • URL de redirecionamento: O URL para onde é enviada a resposta de autenticação do ID do Microsoft Entra. Para começar, você pode usar a homepage do aplicativo Web do cliente de teste.
  • Permissões necessárias: as permissões que seu aplicativo requer para poder chamar o Microsoft Graph.

Para registrar seu aplicativo:

  1. Vá para o portal de registro do aplicativo Azure e conecte-se.

    Observação

    Não é necessário ser um administrador de locatários. Você será redirecionado para a lista Meus aplicativos.

  2. Selecione Novo registro.

  3. Na página de registro do novo aplicativo, digite um valor para Nome e selecione os tipos de conta aos quais deseja dar suporte. No campo URI de redirecionamento, insira o URL de redirecionamento.

  4. Selecione Registrar para criar o aplicativo e exibir a respectiva página de visão geral. *

  5. Acesse a páginapermissões de API do aplicativo.

  6. Selecione Adicionar uma permissão e selecione Microsoft Graph no submenu. Selecione Permissões delegadas. Use a caixa de pesquisa para localizar e selecionar as permissões necessárias. Para obter uma lista de permissões, consulte Permissões de segurança.

    Observação

    A API de Segurança do Microsoft Graph requer o escopo *.Read.All para consultas GET, e o escopo *.ReadWrite.All para consultas PATCH/POST/DELETE.

    Permissão Entidade Solicitações com suporte
    SecurityActions.Read.All • securityActions (pré-visualização) GET
    SecurityActions.ReadWrite.All • securityActions (pré-visualização) GET, POST
    SecurityEvents.Read.All • alertas
    • secureScores
    • secureScoreControlProfiles    		 OBTER
    SecurityEvents.ReadWrite.All • alertas
    • secureScores
    • secureScoreControlProfiles    		 GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (pré-visualização) GET, POST, PATCH, DELETE

  7. Selecione Adicionar permissões.

Salve as informações a seguir:

  • ID do aplicativo (cliente)
  • URL de redirecionamento
  • Lista de permissões necessárias

*A Proteção Avançada Contra Ameaças do Windows Defender (WDATP) requer funções de utilizador adicionais do que as necessárias para a API de Segurança do Microsoft Graph; Por conseguinte, apenas os utilizadores nas funções da API de Segurança do WDATP e do Microsoft Graph podem ter acesso aos dados do WDATP. A autenticação somente para aplicativos não é limitada por isso. Portanto, recomendamos que você use um token de autenticação somente para aplicativos.

Para obter mais informações, consulte Registrar um aplicativo na Plataforma de Identidade da Microsoft.

Conceder permissões a um aplicativo.

O registro do aplicativo define somente qual permissão o aplicativo requer; ele não concede essas permissões ao aplicativo. Um administrador inquilino do Microsoft Entra tem de conceder explicitamente estas permissões ao fazer uma chamada para o ponto final de consentimento do administrador. Para detalhes, consulte Usando o ponto de extremidade de consentimento do administrador.

Para conceder permissões a um aplicativo, você precisará:

  • ID do Aplicativo: a ID do aplicativo do portal de registro do aplicativo Azure.
  • URL de redirecionamento: Cadeia de caracteres que você define no portal de registro do aplicativo para resposta de autenticação.

Para conceder as permissões:

  • Em um editor de texto, crie a seguinte cadeia de caracteres de URL:

    https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL>

  • Em um navegador Web, acesse este URL e faça login como administrador de locatários. A caixa de diálogo mostra a lista de permissões que o aplicativo requer, conforme especificado no portal de registro do aplicativo. Selecione OK para conceder ao aplicativo essas permissões.

    Observação

    Esta etapa concede permissões ao aplicativo, não aos usuários. Isto significa que todos os utilizadores pertencentes ao inquilino do Microsoft Entra que utilizam esta aplicação receberão estas permissões, mesmo os utilizadores não administradores.

Atribuir funções do Microsoft Entra aos utilizadores

Depois de ser concedida permissão a uma aplicação, todas as pessoas com acesso à aplicação (ou seja, membros do inquilino do Microsoft Entra) recebem as permissões concedidas. Para proteger ainda mais os dados de segurança confidenciais, a API de Segurança do Microsoft Graph também requer que os utilizadores sejam atribuídos à função Leitor de Segurança do Microsoft Entra ID. Para obter detalhes, consulte Permissões de função de administrador no Microsoft Entra ID e Atribuir funções de administrador e não administrador a utilizadores com o Microsoft Entra ID.

Observação

Você precisa ser um administrador de locatários para executar esta etapa.

Para atribuir uma função a um usuário:

  1. Entre no Centro de administração do Microsoft Entra.
  2. Expanda o menu >Identidade expanda Utilizadores> selecione Todos os utilizadores.
  3. Selecione o usuário.
  4. Escolha Funções atribuídas e, em seguida, Adicionar atribuição.
  5. Selecione Leitor de segurança e clique em Adicionar.

Crie um código de autenticação

Para criar um código de autenticação, você precisará de:

  • ID do Aplicativo: a ID do aplicativo do portal de registro do aplicativo.
  • URL de redirecionamento: O URL para onde é enviada a resposta de autenticação do ID do Microsoft Entra. Para começar, você pode usar https://localhost ou a homepage do aplicativo Web do cliente de teste.
  • Chave do aplicativo (opcional): a chave do aplicativo. Isso se aplica quando você está desenvolvendo um aplicativo que usará somente o código de autenticação do aplicativo (ou seja, não oferecerá suporte à autenticação delegada pelo usuário).

A tabela a seguir lista os recursos que você pode usar para criar um código de autenticação.

Tipo de aplicativo Biblioteca de autenticação
Aplicativos da área de trabalho, iOS MSAL.framework: Visualização da Biblioteca de Autenticação da Microsoft para iOS
Aplicativos da área de trabalho - Android Biblioteca de Autenticação Microsoft (MSAL)
Aplicativos da área de trabalho - .Net Biblioteca de Autenticação Microsoft (MSAL)
Aplicativos Web - JavaScript SPA Biblioteca de autenticação da Microsoft para visualização de JavaScript
Aplicativos Web - Servidor Web .NET OpenIdConnection, Cookies, SystemWeb
Aplicativos Web - Aplicativo da Web NodeJS

Para aplicativos que não usam nenhuma das bibliotecas existentes, consulte Obter acesso em nome de um usuário.

  1. Obtenha um código do Microsoft Entra ID. A consulta a ser chamada contém o parâmetro para a ID do aplicativo, o URL de redirecionamento e as permissões necessárias.
  2. Use o código para obter um token de acesso.

Se utilizar a biblioteca do OpenId Connect, consulte Authenticate using Microsoft Entra ID (Autenticar com o Microsoft Entra ID) e OpenID Connect e chame app.UseOpenIdConnectAuthentication().

Observação

Se você estiver solicitando tokens de autenticação delegada pelo usuário, o parâmetro da biblioteca será Escopos Solicitados. Use o User.Read para este parâmetro ao invés do que o aplicativo registrado solicitar. O parâmetro Escopos solicitados NÃO afeta as permissões contidas nos tokens de autenticação retornados. Estes são determinados pelas permissões que o administrador de locatários concedeu ao aplicativo.

Por exemplo, se você estiver usando a biblioteca MSAL do .NET, chame o seguinte:

var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken;

Observação

Este exemplo deve usar a permissão menos privilegiada, como User.Read. No entanto, o token de acesso retornado pode conter permissões que foram concedidas pelo administrador locatário para o locatário do usuário atual, como User.Read.All ou User.ReadWrite.All.

Um token (cadeia) é devolvido pelo ID do Microsoft Entra que contém as suas informações de autenticação e as permissões exigidas pela aplicação. Atribua esse token ao cabeçalho HTTP como um token de portador, conforme mostrado no exemplo a seguir.

request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken);

O Microsoft Graph validará as informações contidas nesse token e concederá ou rejeitará o acesso.

Para visualizar as declarações contidas no token retornado, use a biblioteca do NuGet System.IdentityModel.Tokens.Jwt.

JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken;

A resposta do Microsoft Graph contém um cabeçalho chamado client-request-id, que é um GUID. Se o acesso for negado, especifique esse GUID ao procurar suporte na Microsoft Tech Community, para que possamos ajudar a investigar a causa dessa falha de autenticação.