Aceda ao Microsoft Defender para Apps cloud API com contexto de 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 em nome de um utilizador.
Se necessitar de acesso programático ao Microsoft Defender para aplicações na nuvem sem utilizador, consulte o Access Microsoft Defender for Cloud Apps com o contexto de aplicação.
Se não tiver a certeza de que acesso necessita, leia a página Introduçã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. Estas APIs permitir-lhe-ão automatizar fluxos de trabalho e inovar com base nas capacidades do Microsoft Defender para aplicações 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:
- Criar uma aplicação AAD
- Obtenha um token de acesso usando esta aplicação
- Use o token para aceder ao Defender para Apps Cloud API
Esta página explica como criar uma aplicação AAD, obter um token de acesso ao Microsoft Defender para Apps cloud e validar o token.
Nota
Ao aceder ao Microsoft Defender para aplicações cloud API em nome de um utilizador, necessitará da permissão correta da Aplicação e da permissão do utilizador. Se não estiver familiarizado com as permissões do utilizador no Microsoft Defender para aplicações cloud, consulte o acesso de administração.
Dica
Se tiver a permissão para realizar uma ação no portal, tem a permissão para realizar a ação na API.
Criar uma aplicação
Inscreva-se no Azure com uma conta de utilizador que tem a função de Administrador Global.
Navegar para Azure Ative DirectoryRegistos da AppNovo registo.

Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da aplicação:
Nome - Introduza um nome de aplicação significativo que será apresentado aos utilizadores da aplicação.
Tipos de conta suportados - Selecione as contas que quer que a sua aplicação suporte.
Tipos de conta suportados Description Contas apenas neste diretório organizacional Selecione esta opção se estiver a criar uma aplicação de linha de negócio (LOB). Esta opção não está disponível se não estiver a registar o pedido num diretório.
Esta opção mapeia para o inquilino único do Azure AD.
Esta é a opção predefinida, a menos que esteja a registar a aplicação fora de um diretório. Nos casos em que a aplicação é registada fora de um diretório, a predefinição é contas da Microsoft pessoais e de multi-inquilino do Azure AD.Contas em qualquer diretório organizacional Selecione esta opção se quiser visar todos os clientes comerciais ou pedagógicos.
Esta opção mapeia para um multi-inquilino único do Azure AD.
Se você registrou a app como Azure AD apenas um inquilino único, você pode atualizá-la para ser Azure AD multi-inquilino e de volta para inquilino único através do painel de autenticação.Contas em qualquer diretório organizacional e contas Microsoft pessoais Selecione esta opção para visar o maior conjunto de clientes.
Esta opção mapeia para contas da Microsoft pessoais e de multi-inquilino do Azure AD.
Se registou a aplicação como multi-inquilino e contas pessoais da Microsoft, não pode alterar isso na UI. Em vez disso, tem de utilizar o editor de manifesto de aplicação para alterar os tipos de conta suportados.Redirecionar URI (opcional) - Selecione o tipo de aplicação que está a construir, Web ou cliente público (ambiente de trabalho móvel)e, em seguida, introduza o URI de redirecionamento (ou URL de resposta) para a sua aplicação.
- Para aplicações Web, indique o URL base da sua aplicação. Por exemplo,
http://localhost:31544pode ser o URL de uma aplicação Web em execução no seu computador local. Os utilizadores utilizariam este URL para iniciar sessão numa aplicação de cliente Web. - Para aplicações cliente públicas, indique o URI utilizado pelo Azure AD para devolver respostas de token. Introduza um valor específico para a aplicação, por exemplo
myapp://auth.
Para ver exemplos específicos de aplicações Web ou nativas, veja os nossos inícios rápidos.
Quando terminar, selecione Registar.
- Para aplicações Web, indique o URL base da sua aplicação. Por exemplo,
Permita que a sua aplicação aceda ao Microsoft Defender para aplicações cloud e atribua-a a permissão 'Ler alertas':
Na sua página de aplicação, selecione Permissões APIAdicionar permissãoAPIs a minha organização utiliza o tipo Microsoft Cloud App Security e, em seguida, selecione Microsoft Cloud App Security.
Nota:Microsoft Cloud App Security não consta da 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.

Escolha permissões delegadasInvestigação.Ler selecione Permissões adicionar

Nota importante: Selecione 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, consulte a secção permissões na API que está interessada em ligar.
Selecione o consentimento de administração grant
Nota:Sempre que adicionar permissão, deve selecionar o consentimento de administração grant para que a nova permissão entre em vigor.

Escreva a sua ID de inscrição e a sua iD do seu inquilino:
Na sua página de aplicações, vá ao Overview e copie as seguintes informações:

Â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 mais informações sobre AAD fichas, consulte o tutorial da AD Azure
Utilizar C#
Copiar/Colar a classe abaixo na sua aplicação.
Utilize o método AcquireUserTokenAsync com o seu ID de aplicação, ID do inquilino, nome de utilizador e senha para adquirir um token.
namespace MCAS { using System.Net.Http; using System.Text; using System.Threading.Tasks; using Newtonsoft.Json.Linq; public static class MCASUtils { private const string Authority = "https://login.microsoftonline.com"; private const string MCASId = "05a65629-4c1b-48c1-a78b-804c4abdd4af"; public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId) { using (var httpClient = new HttpClient()) { var urlEncodedBody = $"resource={MCASId}&client_id={appId}&grant_type=password&username={username}&password={password}"; var stringContent = new StringContent(urlEncodedBody, Encoding.UTF8, "application/x-www-form-urlencoded"); using (var response = await httpClient.PostAsync($"{Authority}/{tenantId}/oauth2/token", stringContent).ConfigureAwait(false)) { response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false); var jObject = JObject.Parse(json); return jObject["access_token"].Value<string>(); } } } } }
Validar o token
Verifique se tem um token correto:
Copiar/colar em JWT o token que você conseguiu no passo anterior para descodificá-lo
Valide que obtém uma reclamação 'scp' com as permissões de aplicação desejadas
Na imagem abaixo pode ver um token descodificado adquirido a partir da aplicação no tutorial:

Use o token para aceder ao Microsoft Defender para Aplicações cloud API
Escolha a API que pretende utilizar. Para mais informações, consulte Defender for Cloud Apps API.
Desacorde o cabeçalho de autorização no pedido HTTP que envia para "Bearer {token}" (O Portador é o regime de Autorização)
O tempo de expiração do token é de 1 hora (pode enviar mais de um pedido com o mesmo token)
Exemplo de envio de um pedido 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