Autorização e API de Segurança do Microsoft Graph
Os dados de segurança acessíveis por meio do Microsoft Graph API de Segurança são confidenciais e protegidos por permissões e Microsoft Entra funções.
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 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 Microsoft Entra deve conceder explicitamente o consentimento para as permissões solicitadas para o aplicativo graph Explorer.
O usuário deve ser membro da função de Administração Limitada do Leitor de Segurança no 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 Microsoft Entra deve conceder explicitamente o consentimento 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 limitada Administração na 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 do locatário 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 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 recebem um token Microsoft Entra para este aplicativo, o token não contém nenhuma permissão.
O Microsoft Entra administrador do locatário T1 concede explicitamente permissões ao aplicativo. Quando os usuários no locatário T1 receberem um token Microsoft Entra para o aplicativo, ele conterá a permissão P1.
Quando os usuários no locatário T2 recebem um token Microsoft Entra para o aplicativo, o token não contém nenhuma permissão 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 recebem um token 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 receberem um token Microsoft Entra para o aplicativo, o token conterá permissões P1 e P2.
Observação
Os tokens 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 em que a resposta de autenticação de 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:
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.
Selecione Novo registro.
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.
Selecione Registrar para criar o aplicativo e exibir a respectiva página de visão geral. *
Acesse a páginapermissões de API do aplicativo.
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 Selecione Adicionar permissões.
Salve as informações a seguir:
- ID do aplicativo (cliente)
- URL de redirecionamento
- Lista de permissões necessárias
*Windows Defender A Proteção Avançada contra Ameaças (WDATP) requer funções de usuário adicionais do que o exigido pelo Microsoft Graph API de Segurança; portanto, apenas os usuários em funções WDATP e Microsoft Graph API de Segurança 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 Microsoft Entra locatário 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 Microsoft Entra que usam esse aplicativo receberão essas permissões, mesmo usuários não administradores.
Atribuir funções de Microsoft Entra aos usuários
Depois que um aplicativo recebe permissões, todos com acesso ao aplicativo (ou seja, membros do locatário Microsoft Entra) recebem as permissões concedidas. Para proteger ainda mais dados confidenciais de segurança, o Microsoft Graph API de Segurança também exige que os usuários sejam atribuídos à função Microsoft Entra ID Leitor de Segurança. Para obter detalhes, consulte Permissões de função de administrador em Microsoft Entra ID e Atribuir funções de administrador e não administrador a usuários com 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:
- Entre no Centro de administração do Microsoft Entra.
- Expanda o menu >Identidade expanda Usuários> selecionem Todos os usuários.
- Selecione o usuário.
- Escolha Funções atribuídas e, em seguida, Adicionar atribuição.
- 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 em que a resposta de autenticação de 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.
Para aplicativos que não usam nenhuma das bibliotecas existentes, consulte Obter acesso em nome de um usuário.
- Obtenha um código de 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.
- Use o código para obter um token de acesso.
Se você usar a biblioteca OpenId Connect, consulte Autenticar usando Microsoft Entra ID e 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 por Microsoft Entra ID que contém suas informações de autenticação e as permissões necessárias 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.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de