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
Inscreva-se no Azure com um utilizador que tem a função de Administrador Global.
Navegar para Azure Ative DirectoryRegistos da AppNovo registo.

No formulário de inscrição, escolha um nome para a sua inscrição e, em seguida, selecione Registar-se.
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.

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

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

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.

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

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=trueOnde 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.
Crie uma nova aplicação de consola.
Instalar NuGet Microsoft.IdentityModel.Clients.ActiveDirectory.
Adicione o seguinte:
using Microsoft.IdentityModel.Clients.ActiveDirectory;Copiar e colar o seguinte código na sua aplicação (não se esqueça de atualizar as três
tenantId, appId, appSecretvariá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.
- Abra um pedido de comando e desembrote CLIENT_ID para o seu ID de aplicação Azure.
- Desconfiem CLIENT_SECRET ao segredo da sua aplicação Azure.
- Desconfiem TENANT_ID ao ID do inquilino Azure do cliente que pretende utilizar a sua app para aceder ao Defender para aplicações cloud.
- 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:
- Copie e cole o token que obteve no passo anterior no JWT para descodificá-lo.
- Validar que obtém uma reivindicação de "papéis" com as permissões desejadas
- 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:

Use o token para aceder ao Microsoft Defender para Aplicações cloud API
- Escolha a API que pretende utilizar. Para obter mais informações, consulte Defender for Cloud Apps APIs.
- Desacorde o cabeçalho de autorização no pedido http que envia para "Bearer {token}" (O Portador é o esquema de autorização).
- 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