Acessar a API do Microsoft Defender para Aplicativos de Nuvem com o contexto do usuário

Artigo
08/22/2024

Esta página descreve como criar um aplicativo para obter acesso programático ao Defender para Aplicativos de Nuvem em nome de um usuário.

Se você precisar de acesso programático ao Microsoft Defender para Aplicativos de Nuvem sem um usuário, consulte Acessar o Microsoft Defender para Aplicativos em Nuvem com contexto de aplicativo.

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

O Microsoft Defender para Aplicativos de Nuvem expõe grande parte de seus dados e ações por meio de um conjunto de APIs programáticas. Essas APIs permitem automatizar fluxos de trabalho e inovar com base nos recursos do Microsoft Defender para Aplicativos de Nuvem. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, confira Fluxo de Código de Autorização OAuth 2.0.

No geral, é necessário executar as seguintes etapas para utilizar as APIs:

Criar um aplicativo do Microsoft Entra
Obter um token de acesso usando este aplicativo
Usar o token para acessar a API do Defender para Aplicativos de Nuvem

Esta página explica como criar um aplicativo Microsoft Entra, obter um token de acesso ao Microsoft Defender para Aplicativos de Nuvem e validar o token.

Observação

Ao acessar a API do Microsoft Defender para Aplicativos de Nuvem em nome de um usuário, você precisará da permissão correta do Aplicativo e da permissão do usuário. Se você não estiver familiarizado com as permissões de usuário no Microsoft Defender para Aplicativos de Nuvem, consulte Gerenciar o acesso de administrador.

Dica

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

Criar um aplicativo

No centro de administração do Microsoft Entra, registre um novo aplicativo. Para obter mais informações, consulte Início rápido: registrar um aplicativo no centro de administração do Microsoft Entra.

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

Nome: digite um nome de aplicativo relevante que é exibido aos usuários do aplicativo.

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

Tipos de conta compatíveis	Descrição
Contas somente neste diretório organizacional	Selecione esta opção se você está criando um aplicativo de linha de negócios (LOB). Essa opção não estará disponível se você não estiver registrando o aplicativo em um diretório. Essa opção é mapeada para o locatário único somente do Microsoft Entra. Essa é a opção padrão, a menos que você esteja registrando o aplicativo fora de um diretório. Nos casos em que o aplicativo é registrado fora de um diretório, o padrão é o Microsoft Entra multilocatário e as contas pessoais da Microsoft.
Contas em qualquer diretório organizacional	Selecione essa opção se você deseja direcionar para todos os clientes comerciais e educacionais. Essa opção é mapeada para somente um multilocatário do Microsoft Entra. Se você registrou o aplicativo como Microsoft Entra de locatário único, poderá atualizá-lo para ser Microsoft Entra multilocatário e voltar a ser de locatário único por meio do painel Autenticação.
Contas em qualquer diretório organizacional e contas pessoais da Microsoft	Selecione esta opção para direcionar o conjunto mais amplo de clientes. Essa opção é mapeada para contas Microsoft Entra multilocatário e contas Microsoft pessoais. Se você registrou o aplicativo como Microsoft Entra multilocatário e contas pessoais da Microsoft, não será possível alterar isso na interface do usuário. Em vez disso, você deve usar o editor de manifesto de aplicativo para alterar os tipos de conta com suporte.

URI de redirecionamento (opcional): selecione o tipo de aplicativo que você está compilando, **Web, ou Cliente público (dispositivo móvel e desktop) e insira o URI de redirecionamento (ou a URL de resposta) para o aplicativo.
- 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 aplicativos cliente públicos, informe o URI usado pelo Microsoft Entra ID para retornar respostas de token. Insira um valor específico para o aplicativo, por exemplo, myapp://auth.
Para ver exemplos específicos de aplicativos da Web ou aplicativos nativos, confira nossos inícios rápidos.

Ao terminar, selecione Registrar.

Permita que seu Aplicativo acesse o Microsoft Defender para Aplicativos de Nuvem e atribua-lhe a permissão 'Ler alertas':
- Na página do aplicativo, selecione Permissões de API>Adicionar permissões>APIs que minha organização usa>, digite Microsoft Defender para Aplicativos de Nuvem e selecione Microsoft Defender para Aplicativos de Nuvem.
- Observação: o Microsoft Defender para Aplicativos de Nuvem não aparece na lista original. Comece a escrever seu nome na caixa de texto para vê-lo aparecer. Certifique-se de digitar esse nome, mesmo que o produto agora se chame Defender para Aplicativos de Nuvem.
- Escolha Permissões delegadas>Investigation.Read> e selecione Adicionar permissões
- Observação importante: Selecione as permissões relevantes. Investigation.Read é apenas um exemplo. Para outros escopos de permissão, consulte Escopos de permissão com suporte
  - Para determinar de qual permissão você precisa, exiba a seção Permissões na API que você está interessado em chamar.
- Selecione Conceder consentimento do administrador
  
  Observação: sempre que você adicionar permissão, deverá selecionar Conceder consentimento de administrador para que a nova permissão entre em vigor.
Anote a ID do aplicativo e a ID do locatário:
- Na página do aplicativo, vá para Visão geral e copie as seguintes inmaneirações:

Escopos de permissão com suporte

Nome da permissão	Descrição	Ações com suporte
Investigation.read	Execute todas as ações com suporte em atividades e alertas, exceto alertas de fechamento. Exibir intervalos de IP, mas não adicionar, atualizar ou excluir. Executar todas as ações de entidades.	Lista de atividades, busca, feedback Lista de alertas, buscar, marcar como lido/não lido Lista de entidades, busca, árvore de busca Lista de sub-redes
Investigation.manage	Execute todas as ações investigation.read, além de gerenciar alertas e intervalos de IP.	Lista de atividades, busca, feedback Lista de alertas, buscar, marcar como lido/não lido, fechar Lista de entidades, busca, árvore de busca Lista de sub-redes, criar/atualizar/excluir
Discovery.read	Execute todas as ações com suporte em atividades e alertas, exceto alertas de fechamento. Listar relatórios e categorias de descoberta.	Lista de alertas, buscar, marcar como lido/não lido Relatórios de lista de descoberta, categorias de relatório de lista
Discovery.manage	Permissões Discovery.read Feche alertas, carregue arquivos de descoberta e gere scripts de bloco	Lista de alertas, buscar, marcar como lido/não lido, fechar Relatórios de lista de descoberta, categorias de relatório de lista Upload de arquivos de descoberta, gerar script de bloco
Settings.read	Listar intervalos de IP.	Lista de sub-redes
Settings.manage	Listar e gerenciar intervalos de IP.	Lista de sub-redes, criar/atualizar/excluir

Obter um token de acesso

Para obter mais informações sobre os tokens do Microsoft Entra, consulte o tutorial do Microsoft Entra

Usando C#

Copie/cole a seguinte classe em seu aplicativo.
Use o método AcquireUserTokenAsync com sua ID de aplicativo, ID de locatário e autenticação para adquirir um token.

Observação

Embora o exemplo de código a seguir demonstre como adquirir um token usando o fluxo de nome de usuário e senha, a Microsoft recomenda que você use fluxos de autenticação mais seguros em um 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 você tem um token correto:

Copie/cole no JWT o token que você obteve na etapa anterior para decodificá-lo
Valide se você recebe uma declaração 'scp' com as permissões de aplicativo desejadas
Na captura de tela abaixo é possível ver um token decodificado adquirido do aplicativo no tutorial:

Usar o token para acessar a API do Microsoft Defender para Aplicativos de Nuvem

Escolha a API que você deseja usar. Para obter mais informações, confira API do Defender para Aplicativos de Nuvem.
Defina o cabeçalho Authorization na solicitação HTTP enviada para "Bearer {token}" (Bearer é o esquema de autorização)
O tempo de expiração do token é de 1 hora (é possível enviar mais de uma solicitação com o mesmo token)

Exemplo de envio de uma solicitação 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

Compartilhar via