Crie uma aplicação para aceder ao Microsoft Defender para Apps cloud sem um utilizador (pré-visualização)

Nota

Rebaptizámo-Microsoft Cloud App Security. Chama-se Agora Microsoft Defender para Aplicações Cloud. Nas próximas semanas, atualizaremos as imagens e instruções aqui e em páginas relacionadas. Para mais informações sobre a mudança, consulte este anúncio. Para saber mais sobre o recente renomeamento dos serviços de segurança da Microsoft, consulte o blog Microsoft Ignite Security.

Esta página descreve como criar uma aplicação para obter acesso programático ao Defender para Aplicações cloud sem um utilizador. Se necessitar de acesso programático ao Defender para aplicações na nuvem em nome de um utilizador, consulte obter acesso com o contexto do utilizador. Se não tiver a certeza de que acesso necessita, consulte a página de tokens da API de Gestão.

O Microsoft Defender for Cloud Apps expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs irão ajudá-lo a automatizar fluxos de trabalho e inovar com base nas capacidades do Defender para apps cloud. O acesso a API requer autenticação OAuth2.0. Para mais informações, consulte o Código de Autorização 2.0 Flow.

Em geral, terá de tomar as seguintes medidas para utilizar as APIs:

  • Crie uma aplicação Azure Ative Directory (Azure AD).
  • Obtenha um token de acesso usando esta aplicação.
  • Use o token para aceder ao Defender para Apps Cloud API.

Este artigo explica como criar uma aplicação AD Azure, obter um token de acesso ao Microsoft Defender para Aplicações Cloud e validar o token.

Criar uma aplicação

  1. Inscreva-se no Azure com um utilizador que tem a função de Administrador Global.

  2. Navegar para Azure Ative DirectoryRegistos da AppNovo registo.

    Imagem de Microsoft Azure e navegação para registo de aplicações

  3. No formulário de inscrição, escolha um nome para a sua inscrição e, em seguida, selecione Registar-se.

  4. Para ativar a sua aplicação para aceder ao Defender para aplicações na nuvem e atribuí-la 'Leia todos os alertas' na sua página de aplicação, selecione Permissões APIAdicionar permissãoAPIs que a minha organização utiliza,tipo Microsoft Cloud App Security, e, em seguida, selecione Microsoft Cloud App Security.

    Nota

    Microsoft Cloud App Security não aparece na lista original. Comece a escrever o seu nome na caixa de texto para vê-lo aparecer. Certifique-se de escrever este nome, mesmo que o produto agora se chame Defender para Cloud Apps.

    adicionar permissão

    • Selecione permissões de aplicaçãoInvestigation.Reade, em seguida, selecione Adicionar permissões.

      permissão de aplicativo

      Tem de selecionar as permissões relevantes. Investigação.Ler é apenas um exemplo. Para outros âmbitos de permissão, consulte os âmbitos de permissão suportados

      • Para determinar qual a permissão necessária, veja a secção permissões na API que está interessada em ligar.
  5. Selecione Grant consentimento administrativo.

    Nota

    Sempre que adicionar uma permissão, tem de selecionar o consentimento de administração grant para que a nova permissão entre em vigor.

    Conceder permissões

  6. 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 secreto gerado. Não conseguirá recuperar este valor depois de sair.

    Imagem de criar chave de aplicativo

  7. Escreva a sua identificação de inscrição e a sua identificação de inquilino. Na sua página de candidatura, vá ao Overview e copie o ID da Aplicação (cliente) e o ID do Diretório (inquilino).

    Imagem do id de aplicativo criado

  8. Apenas para o Microsoft Defender para parceiros de aplicações na nuvem. Desaprote a sua app para ser multi-arrendada (disponível em todos os inquilinos após o consentimento). Isto é necessário para aplicações de terceiros (por exemplo, se criar uma app que se destina a funcionar no inquilino de vários clientes). Isto não é necessário se criar um serviço que pretende executar apenas no seu inquilino (por exemplo, se criar uma aplicação para o seu próprio uso que só interage com os seus próprios dados). Para definir a sua aplicação para ser multi-arrendado:

    • Vá à Autenticação, e adicione como o URI de redirecionamento.

    • Na parte inferior da página, nos tipos de conta suportados,selecione as Contas em qualquer pedido de diretório organizacional para a sua aplicação multi-inquilino.

    Precisa que o seu pedido seja aprovado em cada inquilino onde pretende usá-lo. Isto porque a sua aplicação interage o Defender for Cloud Apps em nome do seu cliente.

    Você (ou o seu cliente se estiver a escrever uma aplicação de terceiros) precisa de selecionar o link de consentimento e aprovar a sua aplicação. O consentimento deve ser feito com um utilizador 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 000000000-0000-0000-0000-0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

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

Âmbitos de permissão suportados

Nome de permissão Description Ações suportadas
Investigação.ler Realizar todas as ações apoiadas em atividades e alertas, exceto alertas de encerramento.
Ver gamas IP mas não adicionar, atualizar ou excluir.

Realizar todas as ações de entidades.
Lista de atividades, busca, feedback
Lista de alertas, buscar, marcar como lido/não lido
Entidades listam, vão buscar, vão buscar árvore
Lista de sub-redes
Investigação.gerir Realize todas as ações de investigação.read para além de gerir alertas e intervalos de IP. Lista de atividades, busca, feedback
Lista de alertas, buscar, marcar como lido/não lido, fechar
Entidades listam, vão buscar, vão buscar árvore
Lista de sub-redes, criar/atualizar/eliminar
Discovery.read Realizar todas as ações apoiadas em atividades e alertas, exceto alertas de encerramento.
Lista relatórios e categorias de descobertas.
Lista de alertas, buscar, marcar como lido/não lido
Relatórios da lista de descobertas, categorias de relatórios de listas
Discovery.gere Permissões discovery.read
Feche os alertas, carreie ficheiros de descoberta e gere scripts de blocos
Lista de alertas, buscar, marcar como lido/não lido, fechar
Relatórios da lista de descobertas, categorias de relatórios de listas
Upload de ficheiros de descoberta, gerar script de bloco
Definições.ler Intervalos IP lista. Lista de sub-redes
Definições.gerem Listar e gerir as gamas IP. Lista de sub-redes, criar/atualizar/eliminar

Obter um token de acesso

Para obter mais informações sobre os tokens AD da Azure, consulte o tutorial AZURE AD.

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 seguinte código foi testado com NuGet Microsoft.IdentityModel.Clients.ActiveDirectory 3.19.8.

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

  2. Instalar NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.

  3. Adicione o seguinte:

    using Microsoft.IdentityModel.Clients.ActiveDirectory;
    
  4. Copiar e colar o seguinte código na sua aplicação (não se esqueça de atualizar as três tenantId, appId, appSecret variáveis:

    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 MCASResourceId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
    
    AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
    ClientCredential clientCredential = new ClientCredential(appId, appSecret);
    AuthenticationResult authenticationResult = auth.AcquireTokenAsync(MCASResourceId, clientCredential).GetAwaiter().GetResult();
    string token = authenticationResult.AccessToken;
    

Utilizar Python

Consulte a Microsoft Authentication Library (MSAL) para Python.

Use Curl

Nota

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

  1. Abra um pedido de comando e desembrote CLIENT_ID para o seu ID de aplicação Azure.
  2. Desconfiem CLIENT_SECRET ao segredo da sua aplicação Azure.
  3. Desconfiem TENANT_ID ao ID do inquilino Azure do cliente que pretende utilizar a sua app para aceder ao Defender para aplicações cloud.
  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

Terá 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 tem o token correto:

  1. Copie e cole o token que obteve no passo anterior no JWT para descodificá-lo.
  2. Validar que obtém uma reivindicação de "papéis" com as permissões desejadas
  3. Na imagem a seguir, pode ver um token descodificado adquirido a partir de uma aplicação com permissões para todos os papéis do Microsoft Defender para aplicações cloud:

Imagem de validação simbólica

Use o token para aceder ao Microsoft Defender para Aplicações cloud API

  1. Escolha a API que pretende utilizar. Para obter mais informações, consulte Defender for Cloud Apps APIs.
  2. Desacorde o cabeçalho de autorização no pedido http que envia para "Bearer {token}" (O Portador é o esquema de autorização).
  3. O tempo de validade do token é de uma hora. Pode enviar mais do que um pedido com o mesmo sinal.

Segue-se um exemplo de envio de um pedido para obter uma lista de alertas utilizando 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

Ver também