Aceder Microsoft Defender for Cloud Apps API com contexto de utilizador

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

Se precisar de acesso programático Microsoft Defender for Cloud Apps sem um utilizador, veja Access Microsoft Defender for Cloud Apps com o contexto da aplicação.

Se não tiver a certeza de que acesso precisa, leia a página Introduçã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. Essas APIs permitem-lhe automatizar fluxos de trabalho e inovar com base nas capacidades Microsoft Defender for Cloud Apps. 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 for Cloud Apps

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

Criar uma aplicação

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

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

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

   • Tipos de conta suportados – selecione as contas que pretende que a sua aplicação suporte.

     Tipos de conta suportados	Descrição
     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 a aplicação num diretório. Esta opção mapeia para Microsoft Entra inquilino único. 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 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 esta opção se quiser direcionar todos os clientes empresariais e educativos. 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 Microsoft pessoais	Selecione esta opção para direcionar o conjunto mais vasto 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, tem de utilizar o editor de manifestos da aplicação para alterar os tipos de conta suportados.

   • 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 aplicações Web, forneça 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 cliente Web.
     • Para aplicações cliente públicas, forneça o URI utilizado pelo Microsoft Entra ID para devolver respostas de tokens. Introduza um valor específico para a sua aplicação, como myapp://auth.

     Para ver exemplos específicos de aplicações Web ou aplicações nativas, veja os nossos inícios rápidos.

     Quando terminar, selecione Registar.

3. Permita que a aplicação aceda a Microsoft Defender for Cloud Apps 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 for Cloud Apps.

     

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

     

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

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.

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 for Cloud Apps

• Escolha a API que pretende utilizar. Para obter mais informações, veja Defender for Cloud Apps 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
  

Consulte também

• Gerir tokens de API
• fluxo de código de autorização plataforma de identidades da Microsoft e OAuth 2.0