Aceder Microsoft Defender para Aplicativos de Nuvem com o contexto da aplicação

Artigo
11/28/2024

Esta página descreve como criar uma aplicação para obter acesso programático a Defender para Aplicativos de Nuvem sem um utilizador. Se precisar de acesso programático a Defender para Aplicativos de Nuvem em nome de um utilizador, veja Obter acesso com o contexto de utilizador. Se não tiver a certeza de que acesso precisa, veja a página Gerir tokens de API .

Microsoft Defender para Aplicativos de Nuvem expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs ajudam-no a automatizar fluxos de trabalho e a inovar com base nas capacidades Defender para Aplicativos de Nuvem. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, veja OAuth 2.0 Authorization Code Flow (Fluxo de Código de Autorização do OAuth 2.0).

Em geral, tem de seguir os seguintes passos para utilizar as APIs:

Crie uma aplicação Microsoft Entra.
Obtenha um token de acesso com esta aplicação.
Utilize o token para aceder à API Defender para Aplicativos de Nuvem.

Este artigo explica como criar uma aplicação Microsoft Entra, obter um token de acesso para Microsoft Defender para Aplicativos de Nuvem e validar o token.

Criar uma aplicação para Defender para Aplicativos de Nuvem

Na centro de administração do Microsoft Entra, registe uma nova aplicação. Para obter mais informações, veja Início Rápido: Registar uma aplicação com o centro de administração do Microsoft Entra.
Para permitir que a sua aplicação aceda a Defender para Aplicativos de Nuvem e atribua-lhe a permissão "Ler todos os alertas", na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> que aminha organização utiliza>, escreva Microsoft Cloud App Security e, em seguida, selecione Microsoft Cloud App Security.

Observação

O Microsoft Cloud App Security não aparece na lista original. Comece a escrever o respetivo nome na caixa de texto para vê-lo aparecer. Certifique-se de que escreve este nome, apesar de o produto ser agora denominado Defender para Aplicativos de Nuvem.
- Selecione Application permissions>Investigation.Read e, em seguida, selecione Adicionar permissões.
  
  Tem de selecionar as permissões relevantes. Investigation.Read é apenas um exemplo. Para outros âmbitos de permissão, veja Âmbitos de permissão suportados
  - Para determinar de que permissão precisa, veja a secção Permissões na API que está interessado em chamar.
Selecione Conceder consentimento do administrador.

Observação

Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento do administrador para que a nova permissão entre em vigor.
Para adicionar um segredo à aplicação, selecione Certificados & segredos, selecione Novo segredo do cliente, adicione uma descrição ao segredo e, em seguida, selecione Adicionar.

Observação

Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter este valor depois de sair.
Anote o ID da aplicação e o ID do inquilino. Na página da aplicação, aceda a Descrição geral e copie o ID da Aplicação (cliente) e o ID do Diretório (inquilino).
Apenas para Parceiros Microsoft Defender para Aplicativos de Nuvem. Defina a aplicação como multi-inquilino (disponível em todos os inquilinos após o consentimento). Isto é necessário para aplicações de terceiros (por exemplo, se criar uma aplicação que se destina a ser executada no inquilino de vários clientes). Isto não é necessário se criar um serviço que pretenda executar apenas no seu inquilino (por exemplo, se criar uma aplicação para a sua própria utilização que só irá interagir com os seus próprios dados). Para definir a aplicação como multi-inquilino:
- Aceda a Autenticação e adicione https://portal.azure.com como URI de Redirecionamento.
- Na parte inferior da página, em Tipos de conta suportados, selecione o consentimento de contas em qualquer aplicação de diretório organizacional para a sua aplicação multi-inquilino.
Precisa que a sua aplicação seja aprovada em cada inquilino onde pretende utilizá-la. Isto acontece porque a sua aplicação interage Defender para Aplicativos de Nuvem em nome do cliente.

O utilizador (ou o cliente, se estiver a escrever uma aplicação de terceiros) tem de selecionar a ligação de consentimento e aprovar a sua aplicação. O consentimento deve ser feito com um utilizador que tenha privilégios administrativos no Active Directory.

A ligação de consentimento é formada da seguinte forma:
```
https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true
```
Em que 000000000-0000-0000-0000-0000000000000 é substituído pelo ID da aplicação.

Concluído! Registou uma aplicação com êxito! Veja os exemplos abaixo para obter a aquisição e validação de tokens.

Âmbitos de permissão suportados

Nome da permissão	Descrição	Ações suportadas
Investigação.read	Execute todas as ações suportadas em atividades e alertas, exceto alertas de fecho. Ver intervalos de IP, mas não adicionar, atualizar ou eliminar. Executar todas as ações de entidades.	Lista de atividades, obtenção, feedback Lista de alertas, obtenção, marca como lida/não lida Lista de entidades, obtenção e obtenção de árvore Lista de sub-redes
Investigation.manage	Efetue todas as ações investigation.read, além de gerir alertas e intervalos de IP.	Lista de atividades, obtenção, feedback Lista de alertas, obtenção, marca como lida/não lida, fechar Lista de entidades, obtenção e obtenção de árvore Lista de sub-redes, criar/atualizar/eliminar
Discovery.read	Execute todas as ações suportadas em atividades e alertas, exceto alertas de fecho. Listar relatórios e categorias de deteção.	Lista de alertas, obtenção, marca como lida/não lida Relatórios de lista de deteção, listar categorias de relatórios
Discovery.manage	Permissões discovery.read Fechar alertas, carregar ficheiros de deteção e gerar scripts de blocos	Lista de alertas, obtenção, marca como lida/não lida, fechar Relatórios de lista de deteção, listar categorias de relatórios Carregamento de ficheiros de deteção, gerar script de bloco
Definições.read	Listar intervalos de IP.	Lista de sub-redes
Settings.manage	Listar e gerir intervalos de IP.	Lista de sub-redes, criar/atualizar/eliminar

Obter um token de acesso

Para obter mais informações sobre tokens de Microsoft Entra, veja o tutorial Microsoft Entra.

Usar o Windows PowerShell!

# This script acquires the App Context Token and stores it in the variable $token for later use in the script.
# Paste your Tenant ID, App ID, and App Secret (App key) into the indicated quotes below.

$tenantId = '' ### Paste your tenant ID here
$appId = '' ### Paste your Application ID here
$appSecret = '' ### Paste your Application key here

$resourceAppIdUri = '05a65629-4c1b-48c1-a78b-804c4abdd4af'
$oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
$authBody = [Ordered] @{
    resource = "$resourceAppIdUri"
    client_id = "$appId"
    client_secret = "$appSecret"
    grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token

Utilizar C#

O código seguinte foi testado com o NuGet Microsoft.Identity.Client 4.47.2.

Crie uma nova aplicação de consola.
Instale o NuGet Microsoft.Identity.Client.
Adicione o seguinte:
```
using Microsoft.Identity.Client;
```

Copie e cole o seguinte código na sua aplicação (não se esqueça de atualizar as três variáveis: tenantId, appId, appSecret):

string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
string appId = "00001111-aaaa-2222-bbbb-3333cccc4444"; // Paste your own app ID here
string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place!
const string authority = "https://login.microsoftonline.com";
const string audience = "05a65629-4c1b-48c1-a78b-804c4abdd4af";

IConfidentialClientApplication myApp = ConfidentialClientApplicationBuilder.Create(appId).WithClientSecret(appSecret).WithAuthority($"{authority}/{tenantId}").Build();

List scopes = new List() { $"{audience}/.default" };

AuthenticationResult authResult = myApp.AcquireTokenForClient(scopes).ExecuteAsync().GetAwaiter().GetResult();

string token = authResult.AccessToken;

Utilizar Python

Veja Biblioteca de Autenticação da Microsoft (MSAL) para Python.

Utilizar Curl

Observação

O procedimento seguinte pressupõe que o Curl para Windows já está instalado no seu computador.

Abra uma linha de comandos e defina CLIENT_ID para o ID da aplicação do Azure.
Defina CLIENT_SECRET para o segredo da sua aplicação do Azure.
Defina TENANT_ID para o ID de inquilino do Azure do cliente que pretende utilizar a sua aplicação para aceder a Defender para Aplicativos de Nuvem.
Execute o seguinte comando:

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=05a65629-4c1b-48c1-a78b-804c4abdd4af/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID%/oauth2/v2.0/token" -k

Obtém uma resposta na seguinte forma:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}

Validar o token

Certifique-se de que obteve o token correto:

Copie e cole o token que obteve no passo anterior no JWT para o descodificar.
Valide se obtém uma afirmação de "funções" com as permissões pretendidas
Na imagem seguinte, pode ver um token descodificado adquirido a partir de uma aplicação com permissões para todas as funções de Microsoft Defender para Aplicativos de Nuvem:

Captura de ecrã a mostrar a validação de tokens.

Utilizar o token para aceder à API Microsoft Defender para Aplicativos de Nuvem

Escolha a API que pretende utilizar. Para obter mais informações, veja DEFENDER PARA APLICATIVOS DE NUVEM APIs.
Defina o cabeçalho de autorização no pedido http que envia para "Portador {token}" (Portador é o esquema de autorização).
O tempo de expiração do token é de uma hora. Pode enviar mais do que um pedido com o mesmo token.

Segue-se um exemplo de envio de um pedido para obter uma lista de alertas com C#:

    var httpClient = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Get, "https://portal.cloudappsecurity.com/cas/api/v1/alerts/");

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var response = httpClient.SendAsync(request).GetAwaiter().GetResult();

    // Do something useful with the response

Confira também

Gerir tokens de API

Compartilhar via