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

Os dados de segurança acessíveis por meio 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 usuário: Um usuário que é membro do locatário do Microsoft Entra está conectado. O usuário deve ser membro de uma função Microsoft Entra ID Limited Administração, Leitor de Segurança ou Administrador de Segurança, além de o aplicativo ter recebido as permissões necessárias.

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

  • O administrador do locatário do Microsoft Entra deve conceder consentimento explicitamente para as permissões solicitadas ao aplicativo Graph Explorer.

  • O usuário deve ser membro da função de Leitor de Segurança Limitada Administração em Microsoft Entra ID (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 do locatário do Microsoft Entra deve conceder consentimento explicitamente ao seu aplicativo. Isso é necessário para autorização no nível de aplicativo e autorização delegada pelo usuário.
  • Se você estiver usando a autorização delegada pelo usuário, o usuário deverá ser membro da função Leitor de Segurança ou Administrador de Segurança Limitado Administração no Microsoft Entra ID.

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 de locatários do Microsoft Entra DEVE conceder explicitamente as permissões ao aplicativo. 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 você tenha um aplicativo, dois locatários 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 usuários no locatário T1 obtêm um token do Microsoft Entra para esse aplicativo, o token não contém permissões.

  • O administrador do Microsoft Entra do locatário T1 concede explicitamente permissões ao aplicativo. Quando os usuários no locatário T1 obtiverem um token do Microsoft Entra para o aplicativo, ele conterá a permissão P1.

  • Quando os usuários no locatário T2 obtêm um token do Microsoft Entra para o aplicativo, o token não contém permissões porque o administrador do locatário T2 ainda não concedeu permissões ao aplicativo. 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 usuários no locatário T1 obtêm um token do Microsoft Entra para o aplicativo, ele 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 usuários no locatário T2 obtiverem um token do Microsoft Entra para o aplicativo, o token conterá as permissões P1 e P2.

    Observação

    Os tokens do Microsoft Entra para o aplicativo no locatário T1 e o aplicativo no locatário T2 contêm permissões diferentes, pois cada administrador de locatário concedeu permissões diferentes ao aplicativo.

  • 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: A URL para a qual a resposta de autenticação do Microsoft Entra ID é enviada. 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 (versão prévia) GET
    SecurityActions.ReadWrite.All • securityActions (versão prévia) GET, POST
    SecurityEvents.Read.All • alertas
    • secureScores • secureScoreControlProfiles
    		 OBTER
    SecurityEvents.ReadWrite.All • alertas
    • secureScores • secureScoreControlProfiles
    		 GET, POST, PATCH
    ThreatIndicators.ReadWrite.OwnedBy • tiIndicator (versão prévia) 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 usuário adicionais às exigidas pela API de Segurança do Microsoft Graph; portanto, apenas os usuários nas funções WDATP e API de API de Segurança do Microsoft Graph podem ter acesso aos dados 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 de locatários do Microsoft Entra deve conceder explicitamente essas permissões fazendo uma chamada para o ponto de extremidade 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. Isso significa que todos os usuários pertencentes ao locatário do Microsoft Entra que usam esse aplicativo receberão essas permissões, mesmo os usuários não administradores.

Atribuir funções do Microsoft Entra aos usuários

Depois que um aplicativo recebe permissões, todas as pessoas com acesso ao aplicativo (ou seja, membros do locatário 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 exige que os usuários sejam atribuídos à função de 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 aos usuários 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 Usuários> e selecione Todos os usuários.
  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: A URL para a qual a resposta de autenticação do Microsoft Entra ID é enviada. 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 você usar a biblioteca OpenId Connect, consulte Autenticar usando o Microsoft Entra ID e o OpenID Connect e chamar 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 de caracteres) é retornado pelo Microsoft Entra ID que contém suas informações de autenticação e as permissões exigidas pelo aplicativo. 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.

  • Last updated on