Aceder Microsoft Defender para Aplicativos de Nuvem API com contexto de utilizador

Artigo
11/28/2024

Esta página descreve como criar uma aplicação para obter acesso programático a Defender para Aplicativos de Nuvem em nome de um utilizador.

Se precisar de acesso programático Microsoft Defender para Aplicativos de Nuvem sem um utilizador, veja Access Microsoft Defender para Aplicativos de Nuvem com o contexto da aplicação.

Se não tiver a certeza de que acesso precisa, leia a página Introdução.

Microsoft Defender para Aplicativos de Nuvem expõe grande parte dos seus dados e ações através de um conjunto de APIs programáticas. Essas APIs permitem-lhe automatizar fluxos de trabalho e inovar com base nas capacidades Microsoft Defender para Aplicativos de Nuvem. 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:

Criar uma aplicação Microsoft Entra
Obter um token de acesso com esta aplicação
Utilizar o token para aceder à API Defender para Aplicativos de Nuvem

Esta página explica como criar uma aplicação Microsoft Entra, obter um token de acesso para Microsoft Defender para Aplicativos de Nuvem e validar o token.

Observação

Ao aceder à API Microsoft Defender para Aplicativos de Nuvem em nome de um utilizador, precisará da permissão de Aplicação e da permissão de utilizador corretas. Se não estiver familiarizado com as permissões de utilizador no Microsoft Defender para Aplicativos de Nuvem, veja Gerir o acesso de administrador.

Dica

Se tiver permissão para efetuar uma ação no portal, tem a permissão para executar a ação na API.

Criar um aplicativo

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

Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:

Nome – introduza um nome de aplicação relevante que seja apresentado aos utilizadores da aplicação.

Tipos de conta com suporte: selecione as contas às quais você gostaria que seu aplicativo desse suporte.

Tipos de conta com suporte	Descrição
Contas apenas neste diretório organizacional	Selecione esta opção se você está criando um aplicativo de linha de negócios (LOB). Esta opção não está disponível se não estiver a registar a aplicação num diretório. Esta opção mapeia para Microsoft Entra inquilino único. Essa é a opção padrão, a menos que você esteja registrando o aplicativo fora de um diretório. Nos casos em que a aplicação está registada fora de um diretório, a predefinição é Microsoft Entra contas Microsoft multi-inquilino e pessoais.
Contas em qualquer diretório organizacional	Selecione essa opção se você deseja direcionar para todos os clientes corporativos e educacionais. Esta opção mapeia para um multi-inquilino só de Microsoft Entra. Se registou a aplicação como Microsoft Entra inquilino único, pode atualizá-la para ser Microsoft Entra multi-inquilino e regressar ao inquilino único através do painel Autenticação.
Contas em qualquer diretório organizacional e contas pessoais da Microsoft	Selecione essa opção para direcionar ao conjunto mais amplo de clientes. Esta opção mapeia para Microsoft Entra contas Microsoft multi-inquilino e pessoais. Se registou a aplicação como Microsoft Entra contas Microsoft multi-inquilino e pessoais, não poderá alterá-la na IU. Em vez disso, use o editor de manifesto do aplicativo para alterar os tipos de conta com suporte.

URI de Redirecionamento (opcional) – selecione o tipo de aplicação que está a criar, **Web ou Cliente público (móvel & ambiente de trabalho) e, em seguida, introduza o URI de redirecionamento (ou URL de resposta) para a sua aplicação.
- Para aplicativos Web, informe a URL base do aplicativo. Por exemplo, http://localhost:31544 pode ser uma URL para um aplicativo Web em execução no seu computador local. Os usuários usariam essa URL para entrar em um aplicativo cliente Web.
- Para aplicações cliente públicas, forneça o URI utilizado pelo Microsoft Entra ID para devolver respostas de tokens. Insira um valor específico para o aplicativo, por exemplo, myapp://auth.
Para ver exemplos específicos de aplicativos Web ou aplicativos nativos, confira os inícios rápidos.

Ao terminar, selecione Registrar.

Permita que a aplicação aceda a Microsoft Defender para Aplicativos de Nuvem e atribua-lhe a permissão "Alertas de leitura":
- Na página da sua aplicação, selecione Permissões> da API Adicionar APIs depermissão> quea minha 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 para Aplicativos de Nuvem.
- Selecione Permissões> delegadasInvestigação.Ler> selecione Adicionar permissões
- Nota importante: selecione 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.
- Selecione Conceder consentimento do administrador
  
  Nota: sempre que adicionar permissão, tem de selecionar Conceder consentimento do administrador para que a nova permissão entre em vigor.
Anote o ID da aplicação e o ID do inquilino:
- Na página da aplicação, aceda a Descrição geral e copie as seguintes informações:

Â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 Microsoft Entra tutorial

Utilizar C#

Copie/Cole a seguinte classe na sua aplicação.
Utilize o método AcquireUserTokenAsync com o ID da aplicação, o ID do inquilino e a autenticação para adquirir um token.

Observação

Embora o seguinte exemplo de código demonstre como adquirir um token com o fluxo de nome de utilizador e palavra-passe, a Microsoft recomenda que utilize fluxos de autenticação mais seguros num ambiente de produção.

namespace MDA
{
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json.Linq;

    public static class MDAUtils
    {
        private const string Authority = "https://login.microsoftonline.com";

        private const string MDAId = "05a65629-4c1b-48c1-a78b-804c4abdd4af";
        private const string Scope = "Investigation.read";

        public static async Task<string> AcquireUserTokenAsync(string username, string password, string appId, string tenantId)
        {
            using (var httpClient = new HttpClient())
            {
                var urlEncodedBody = $"scope={MDAId}/{Scope}&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:

Copie/cole no JWT o token que obteve no passo anterior para o descodificar
Confirme que obtém uma afirmação "scp" com as permissões de aplicação pretendidas
Na captura de ecrã abaixo, pode ver um token descodificado adquirido na aplicação no tutorial:

Utilizar o token para aceder à API Microsoft Defender para Aplicativos de Nuvem

Escolha a API que pretende utilizar. Para obter mais informações, veja Defender para Aplicativos de Nuvem API.
Defina o cabeçalho Autorização no pedido HTTP que envia para "Portador {token}" (Portador é o esquema de Autorização)
A Hora de expiração do token é de 1 hora (pode enviar mais do que um pedido com o mesmo token)

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

Compartilhar via