Partilhar via

Aceder Microsoft Defender for Cloud Apps com o contexto da aplicação

  • Artigo

Esta página descreve como criar uma aplicação para obter acesso programático a Defender for Cloud Apps sem um utilizador. Se precisar de acesso programático a Defender for Cloud Apps 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 for Cloud Apps expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Estas APIs ajudam-no a automatizar fluxos de trabalho e a inovar com base nas capacidades Defender for Cloud Apps. 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 for Cloud Apps.

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

Criar uma aplicação para Defender for Cloud Apps

  1. Na centro de administração 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 Microsoft Entra.

  2. Para permitir que a sua aplicação aceda a Defender for Cloud Apps 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.

    Nota

    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 for Cloud Apps.

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

    • Selecione Application permissions>Investigation.Read e, em seguida, selecione Adicionar permissões.

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

      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.

  3. Selecione Conceder consentimento do administrador.

    Nota

    Sempre que adicionar uma permissão, tem de selecionar Conceder consentimento do 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 à aplicação, selecione Certificados & segredos, selecione Novo segredo do cliente, adicione uma descrição ao segredo e, em seguida, selecione Adicionar.

    Nota

    Depois de selecionar Adicionar, selecione copiar o valor do segredo gerado. Não poderá obter este valor depois de sair.

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

  5. 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).

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

  6. Apenas para Parceiros Microsoft Defender for Cloud Apps. 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 for Cloud Apps 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.

Feito! 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.

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 seguinte 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. Adicione o seguinte:

    using Microsoft.Identity.Client;

  4. 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

Nota

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

  1. Abra uma linha de comandos e defina CLIENT_ID para o ID da aplicação do Azure.
  2. Defina CLIENT_SECRET para o segredo da sua aplicação do Azure.
  3. Defina TENANT_ID para o ID de inquilino do Azure do cliente que pretende utilizar a sua aplicação para aceder a 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

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:

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

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

Utilizar o token para aceder à API Microsoft Defender for Cloud Apps

  1. Escolha a API que pretende utilizar. Para obter mais informações, veja DEFENDER FOR CLOUD APPS APIs.
  2. Defina o cabeçalho de autorização no pedido http que envia para "Portador {token}" (Portador é o esquema de autorização).
  3. 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

Consulte também