Acesse a API do Microsoft Defender for Cloud Apps com contexto de usuário

Artigo
08/19/2024

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

Se você precisar de acesso programático ao Microsoft Defender for Cloud Apps sem um usuário, consulte Access Microsoft Defender for Cloud Apps with application context.

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

O Microsoft Defender for Cloud Apps 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 for Cloud Apps. O acesso à API requer autenticação OAuth2.0. Para obter mais informações, consulte Fluxo de código de autorização do OAuth 2.0.

Em geral, você precisa seguir as seguintes etapas para usar as APIs:

Criar um aplicativo Microsoft Entra
Obter um token de acesso usando este aplicativo
Use o token para acessar a API do Defender for Cloud Apps

Esta página explica como criar um aplicativo Microsoft Entra, obter um token de acesso ao Microsoft Defender for Cloud Apps e validar o token.

Nota

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

Gorjeta

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 uma aplicação

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

Quando a página Registar uma aplicação for apresentada, introduza as informações de registo da aplicação:

Nome - Insira um nome de aplicativo significativo que seja exibido para os usuários do aplicativo.

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). Essa opção não estará disponível se você não estiver registrando o aplicativo em um diretório. Esta opção é mapeada para um único inquilino apenas do Microsoft Entra. Esta é a opção predefinida, a menos que esteja a registar a aplicação fora de um diretório. Nos casos em que o aplicativo está registrado fora de um diretório, o padrão é contas multilocatárias e pessoais da Microsoft do Microsoft Entra.
Contas em qualquer diretório organizacional	Selecione esta opção se quiser visar todos os clientes comerciais ou pedagógicos. Esta opção é mapeada para um multilocatário somente Microsoft Entra. Se você registrou o aplicativo como locatário único somente do Microsoft Entra, poderá atualizá-lo para ser multilocatário do Microsoft Entra e voltar para um único locatário por meio do painel 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 é mapeada para contas multilocatárias e pessoais da Microsoft Entra. Se você registrou o aplicativo como multilocatário do Microsoft Entra e contas pessoais da Microsoft, não poderá alterar isso na interface do usuário. Em vez disso, tem de utilizar o editor de manifesto de aplicação para alterar os tipos de conta suportados.

URI de redirecionamento (opcional) - Selecione o tipo de aplicativo que você está criando, **Web ou cliente público (móvel ou desktop) e, em seguida, insira o URI de redirecionamento (ou URL de resposta) para seu aplicativo.
- 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 aplicativos cliente públicos, forneça o URI usado pelo ID do Microsoft Entra para retornar 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.

Permita que seu Aplicativo acesse o Microsoft Defender for Cloud Apps e atribua-lhe a permissão 'Ler alertas':
- Na página do seu aplicativo, selecione Permissões>de API Adicionar APIs de permissão>que minha organização usa>, digite Microsoft Cloud App Security e selecione Microsoft Cloud App Security.
- Observação: o Microsoft Cloud App Security 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 for Cloud Apps.
- Escolha Permissões>delegadas Investigação.Leia> 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 suportados
  - Para determinar de qual permissão você precisa, consulte a seção Permissões na API que você está interessado em chamar.
- Selecione Conceder consentimento de administrador
  
  Nota: Sempre que adicionar permissão, tem de selecionar Conceder consentimento de administrador para que a nova permissão entre em vigor.
Anote o ID do aplicativo e o ID do locatário:
- Na página do seu aplicativo, vá para Visão geral e copie as seguintes informações:

Escopos de permissão suportados

Nome da permissão	Description	Ações suportadas
Investigação.read	Execute todas as ações suportadas em atividades e alertas, exceto alertas de fechamento. Visualize intervalos de IP, mas não adicione, atualize ou exclua. Executar todas as ações das entidades.	Lista de atividades, busca, feedback Lista de alertas, buscar, marcar como lido/não lido Lista de entidades, buscar, buscar árvore Lista de sub-redes
Investigação.gerenciar	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, buscar, buscar árvore Lista de sub-redes, criar/atualizar/excluir
Descoberta.ler	Execute todas as ações suportadas 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
Descoberta.gerenciar	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 arquivo de descoberta, gerar script de bloco
Configurações.ler	Listar intervalos de IP.	Lista de sub-redes
Configurações.gerenciar	Listar e gerenciar intervalos de IP.	Lista de sub-redes, criar/atualizar/excluir

Obter um token de acesso

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

Utilizar 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 adquira um token.

Nota

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 desejadas do aplicativo
Na captura de tela abaixo, você pode ver um token decodificado adquirido do aplicativo no tutorial:

Use o token para acessar a API do Microsoft Defender for Cloud Apps

Escolha a API que deseja usar. Para obter mais informações, consulte API do Defender for Cloud Apps.
Defina o cabeçalho Authorization na solicitação HTTP enviada para "Bearer {token}" (Portador é o esquema de Autorização)
O tempo de expiração do token é de 1 hora (você pode 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

Partilhar via