Partilhar via

Acesse o Microsoft Defender for Cloud Apps com contexto de aplicativo

  • Artigo

Esta página descreve como criar um aplicativo para obter acesso programático ao Defender for Cloud Apps sem um usuário. Se você precisar de acesso programático ao Defender for Cloud Apps 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 for Cloud Apps expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs ajudam você a automatizar fluxos de trabalho e inovar com base nos recursos do Defender for Cloud Apps. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, consulte Fluxo de código de autorização do OAuth 2.0.

Em geral, você precisa seguir as seguintes etapas para usar as APIs:

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

Este artigo explica como criar um aplicativo Microsoft Entra, obter um token de acesso ao Microsoft Defender for Cloud Apps e validar o token.

Criar um aplicativo para o Defender for Cloud Apps

  1. No centro de administração do Microsoft Entra, registre um novo aplicativo. Para obter mais informações, consulte Guia de início rápido: registrar um aplicativo no centro de administração do Microsoft Entra.

  2. Para permitir que seu aplicativo acesse o Defender for Cloud Apps e atribua a permissão "Ler todos os alertas", na página do aplicativo, selecione Permissões>de API Adicionar APIs de permissão>que minha organização usa>, digite Microsoft Cloud App Security e selecione Microsoft Cloud App Security.

    Nota

    O Microsoft Cloud App Security 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 for Cloud Apps.

    Captura de ecrã a mostrar a adição de permissão.

    • Selecione Application permissions>Investigation.Read e, em seguida, selecione Add permissions.

      Captura de ecrã a mostrar a adição de permissão de aplicação.

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

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

  3. Selecione Conceder consentimento do administrador.

    Nota

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

    Captura de ecrã a mostrar a concessão de permissões de administrador.

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

    Nota

    Depois de selecionar Adicionar, selecione copiar o valor secreto gerado. Você não poderá recuperar esse valor depois de sair.

    Captura de ecrã a mostrar a criação de uma chave de aplicação.

  5. Anote o ID do aplicativo e o ID do locatário. Na página do aplicativo, vá para Visão geral e copie a ID do aplicativo (cliente) e a ID do diretório (locatário).

    Captura de ecrã do ID da aplicação criada.

  6. Apenas para parceiros do Microsoft Defender for Cloud Apps. 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 destinado a ser executado no locatário de vários clientes). Isso não é necessário se você criar um serviço que deseja executar apenas 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 suportados, selecione Contas em qualquer consentimento de aplicativo de diretório organizacional para seu aplicativo multilocatário.

    Precisa que a sua candidatura seja aprovada em cada inquilino onde pretende utilizá-la. Isso ocorre porque seu aplicativo interage com o Defender for Cloud Apps em nome do seu 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 Ative 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-000000000000 é substituído pelo ID do aplicativo.

E já está! Registou com sucesso uma candidatura! Veja exemplos abaixo para aquisição e validação de tokens.

Escopos de permissão suportados

Nome da permissão Description Ações suportadas
Investigação.read Execute todas as ações suportadas em atividades e alertas, exceto alertas de fechamento.
Visualize intervalos de IP, mas não adicione, atualize ou exclua.

Executar todas as ações das entidades.		 Lista de atividades, busca, feedback
Lista de alertas, buscar, marcar como lido/não lido
Lista de entidades, buscar, buscar árvore
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, buscar, buscar árvore
Lista de sub-redes, criar/atualizar/excluir
Descoberta.ler Execute todas as ações suportadas 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
Descoberta.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 arquivo 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 tokens do Microsoft Entra, consulte o tutorial do Microsoft Entra.

Utilizar o 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 a seguir foi testado com o NuGet Microsoft.Identity.Client 4.47.2.

  1. Crie uma nova aplicação de consola.

  2. Instale o NuGet Microsoft.Identity.Client.

  3. Aditar 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 = "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 o Python

Consulte Microsoft Authentication Library (MSAL) para Python.

Use Curl

Nota

O procedimento a seguir pressupõe que o Curl para Windows já esteja instalado no seu 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 for Cloud Apps.
  4. 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

A resposta é obtida da 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:

  1. Copie e cole o token que você obteve na etapa anterior no JWT para decodificá-lo.
  2. Valide que você recebe 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 for Cloud Apps:

Captura de tela da validação do token.

Use o token para acessar a API do Microsoft Defender for Cloud Apps

  1. Escolha a API que deseja usar. Para obter mais informações, consulte APIs do Defender for Cloud Apps.
  2. Defina o cabeçalho de autorização na solicitação http que você envia para "Portador {token}" (Portador é 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

Consulte também