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

  1. Inscreva-se no Azure com uma conta de 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. 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:31544 pode 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.

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

      adicionar permissão

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

      permissões de aplicação

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

      Imagem de permissões grant

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

      Imagem do id de aplicativo criado

Â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:

    Imagem de validação simbólica

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
    

Ver também