Compartilhar via

Acessar o Microsoft Defender para Aplicativos de Nuvem com contexto de aplicativo

  • Artigo

Esta página descreve como criar um aplicativo para obter acesso programático ao Defender para Aplicativos de Nuvem sem um usuário. Se você precisar de acesso programático ao Defender para Aplicativos de Nuvem em nome de um usuário, consulte Obter acesso com contexto de usuário. Se você não tiver certeza de qual acesso precisa, consulte a página Gerenciando tokens de API.

O Microsoft Defender para Aplicativos de Nuvem expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs ajudarão você a automatizar fluxos de trabalho e inovar com base nos recursos do Defender para Aplicativos de Nuvem. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, confira Fluxo de Código de Autorização OAuth 2.0.

Em geral, você precisará executar as seguintes etapas para utilizar as APIs:

  • Crie um aplicativo do Microsoft Entra.
  • Obtenha um token de acesso usando este aplicativo.
  • Use o token para acessar a API do Defender para Aplicativos de Nuvem.

Este artigo explica como criar um aplicativo Microsoft Entra, obter um token de acesso ao Microsoft Defender para Aplicativos de Nuvem e validar o token.

Criar um aplicativo

  1. Faça login no Azure com um usuário que tenha a função de Administrador Global.

  2. Navegue até Microsoft Entra ID>Registros de aplicativo>Novo registro.

    Image of Microsoft Azure and navigation to application registration.

  3. No formulário de registro, escolha um nome para sua inscrição e selecione Registrar.

  4. Para permitir que seu aplicativo acesse o Defender para Aplicativos de Nuvem e atribua a ele a permissão "Ler todos os alertas", na página do aplicativo, selecione Permissões de API>Adicionar APIs>de permissãoque minha organização usa>, digite Microsoft Defender para Aplicativos de Nuvem e selecione Microsoft Defender para Aplicativos de Nuvem.

    Observação

    O Microsoft Defender para Aplicativos de Nuvem não aparece na lista original. Comece a escrever seu nome na caixa de texto para vê-lo aparecer. Certifique-se de digitar esse nome, mesmo que o produto agora se chame Defender para Aplicativos de Nuvem.

    add permission.

    • Selecione Permissões de aplicativo>Investigation.Read e, em seguida, selecione Adicionar permissões.

      app permission.

      Você precisa selecionar as permissões relevantes. Investigation.Read é apenas um exemplo. Para outros escopos de permissão, consulte Escopos de permissão com suporte

      • Para determinar de que permissão você precisa, consulte a seção Permissões na API que você está interessado em chamar.

  5. Selecione Conceder consentimento do administrador.

    Observação

    Sempre que adicionar uma permissão, você deverá selecionar Conceder consentimento de administrador para que a nova permissão entre em vigor.

    Grant permissions.

  6. Para adicionar um segredo ao aplicativo, selecione Certificados e segredos, selecione Novo segredo do cliente, adicione uma descrição ao segredo e selecione Adicionar.

    Observação

    Depois de selecionar Adicionar, selecione copiar o valor secreto gerado. Não será possível recuperar esse valor depois que você sair.

    Image of create app key.

  7. Anote a ID do aplicativo e a ID do locatário. Na página da sua aplicação, vá a Visão geral e copie o ID da aplicação (cliente) e o ID do diretório (locatário).

    Image of created app id.

  8. Apenas para parceiros do Microsoft Defender para Aplicativos de Nuvem. Defina seu aplicativo como multilocatário (disponível em todos os locatários após consentimento). Isso é necessário para aplicativos de terceiros (por exemplo, se você criar um aplicativo que se destina a ser executado no locatário de vários clientes). Isso não será necessário se você criar um serviço que deseja executar somente em seu locatário (por exemplo, se você criar um aplicativo para seu próprio uso que só interagirá com seus próprios dados). Para definir seu aplicativo como multilocatário:

    • Vá para Autenticação e adicione https://portal.azure.com como o URI de redirecionamento.

    • Na parte inferior da página, em Tipos de conta com suporte, selecione o consentimento Contas em qualquer aplicativo de diretório organizacional para seu aplicativo multilocatário.

    Você precisa que seu aplicativo seja aprovado em cada locatário onde você pretende usá-lo. Isso ocorre porque seu aplicativo interage com o Defender para Aplicativos de Nuvem em nome do cliente.

    Você (ou seu cliente, se estiver escrevendo um aplicativo de terceiros) precisa selecionar o link de consentimento e aprovar seu aplicativo. O consentimento deve ser feito com um usuário que tenha privilégios administrativos no Active Directory.

    O link de consentimento é formado 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

    Onde 00000000-0000-0000-0000-0000000000000 é substituído pelo ID do aplicativo.

Feito! Você registrou um aplicativo com sucesso! Veja exemplos abaixo para aquisição e validação de tokens.

Escopos de permissão com suporte

Nome da permissão Descrição Ações com suporte
Investigação.ler Execute todas as ações com suporte em atividades e alertas, exceto alertas de fechamento.
Exibir intervalos de IP, mas não adicionar, atualizar ou excluir.

Executar todas as ações de entidades.		 Lista de atividades, busca, feedback
Lista de alertas, buscar, marcar como lido/não lido
Lista de entidades, busca, árvore de busca
Lista de sub-redes
Investigação.gerenciar Execute todas as ações investigation.read, além de gerenciar alertas e intervalos de IP. Lista de atividades, busca, feedback
Lista de alertas, buscar, marcar como lido/não lido, fechar
Lista de entidades, busca, árvore de busca
Lista de sub-redes, criar/atualizar/excluir
Descoberta.ler Execute todas as ações com suporte em atividades e alertas, exceto alertas de fechamento.
Listar relatórios e categorias de descoberta.		 Lista de alertas, buscar, marcar como lido/não lido
Relatórios de lista de descoberta, categorias de relatório de lista
Discovery.gerenciar Permissões Discovery.read
Feche alertas, carregue arquivos de descoberta e gere scripts de bloco		 Lista de alertas, buscar, marcar como lido/não lido, fechar
Relatórios de lista de descoberta, categorias de relatório de lista
Upload de arquivos de descoberta, gerar script de bloco
Configurações.ler Listar intervalos de IP. Lista de sub-redes
Configurações.gerenciar Listar e gerenciar intervalos de IP. Lista de sub-redes, criar/atualizar/excluir

Obter um token de acesso

Para obter mais informações sobre os tokens do Microsoft Entra, consulte o tutorial do Microsoft Entra.

Usar 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

Use o C#

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

  1. Crie um novo aplicativo de console.

  2. Instale o NuGet Microsoft.Identity.Client.

  3. Adicione o seguinte:

    using Microsoft.Identity.Client;

  4. Copie e cole o seguinte código em seu aplicativo (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 = "11111111-1111-1111-1111-111111111111"; // 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;

Como usar o Python

Consulte Microsoft Authentication Library (MSAL) for Python.

Usar Curl

Observação

O procedimento a seguir pressupõe que o Curl para Windows já esteja instalado no computador.

  1. Abra um prompt de comando e defina CLIENT_ID para sua ID de aplicativo do Azure.
  2. Defina CLIENT_SECRET para o segredo do aplicativo do Azure.
  3. Defina TENANT_ID para a ID de locatário do Azure do cliente que deseja usar seu aplicativo para acessar o Defender para Aplicativos de Nuvem.
  4. Execute o comando a seguir:
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

Você receberá uma resposta da seguinte maneira:

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

Validar o token

Certifique-se de que você obteve o token correto:

  1. Copie e cole o token que você obteve na etapa anterior no JWT para decodificá-lo.
  2. Valide se você obtém uma declaração de 'funções' com as permissões desejadas
  3. Na imagem a seguir, você pode ver um token decodificado adquirido de um aplicativo com permissões para todas as funções do Microsoft Defender para Aplicativos de Nuvem:

Image of token validation.

Usar o token para acessar a API do Microsoft Defender para Aplicativos de Nuvem

  1. Escolha a API que você deseja usar. Para obter mais informações, consulte APIs do Defender para Aplicativos de Nuvem.
  2. Defina o cabeçalho de autorização na solicitação http que você envia para "Bearer {token}" (Bearer é o esquema de autorização).
  3. O tempo de expiração do token é de uma hora. Você pode enviar mais de uma solicitação com o mesmo token.

Veja a seguir um exemplo de envio de uma solicitação para obter uma lista de alertas usando 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