Pré-requisitos para acessar a API de relatório do Azure Active Directory

  • Artigo
  • 5 minutos para o fim da leitura

As APIs de relatório do Azure AD fornecem acesso programático aos dados através de um conjunto de APIs baseadas em REST. Você pode chamar essas APIs a partir de várias ferramentas e linguagens de programação.

A API de relatório usa OAuth para autorizar o acesso às APIs da Web.

Para preparar seu acesso à API de relatório, você precisa:

  1. Atribuir funções
  2. Requisitos de licença
  3. Registrar um aplicativo
  4. Conceder permissões
  5. Reunir definições de configuração

Atribuir funções

Para obter acesso aos dados de relatórios por meio da API, você precisa ter uma das seguintes funções atribuídas:

  • Leitor de segurança

  • Administrador de Segurança

  • Administrador Global

Requisitos de licença

Para acessar os relatórios de entrada de um locatário, um locatário do Azure AD deverá ter a licença Azure AD Premium associada. A licença Azure AD Premium P1 (ou superior) é necessária para acessar os relatórios de entrada de qualquer locatário do Azure Active Directory. Como alternativa, se o tipo de diretório for Azure AD B2C, os relatórios de entrada poderão ser acessados por meio da API sem nenhum requisito de licença adicional.

Registrar um aplicativo

O registro é necessário mesmo se você estiver acessando a API de relatório usando um script. O registro fornece um ID de Aplicativo, que é necessário para as chamadas de autorização e permite que seu código receba tokens.

Para configurar seu diretório para acessar a API de relatórios do Microsoft Azure Active Directory, você deve entrar no Portal do Azure com uma conta de administrador do Azure que também é membro da função de diretório Administrador Global no seu Locatário do Azure AD.

Importante

Aplicativos em execução sob credenciais com privilégios de administrador podem ser muito poderosos, portanto, certifique-se de manter o ID do aplicativo e as credenciais secretas em um local seguro.

Para registrar um aplicativo do Microsoft Azure Active Directory:

  1. No portal do Azure, selecione Azure Active Directory do painel de navegação à esquerda.

    Screenshot shows Azure Active Directory selected from the Azure portal menu.

  2. Na página Azure Active Directory, selecione Registros de aplicativo.

    Screenshot shows App registrations selected from the Manage menu.

  3. Na página Registros de aplicativo, selecione Novo registro.

    Screenshot shows New registration selected.

  4. A página Registro de um aplicativo:

    Screenshot shows the Register an application page where you can enter the values in this step.

    a. Na caixa de texto Nome, digite Reporting API application.

    b. Para Tipos de contas com suporte, selecione Contas somente nesta organização.

    c. Em Redirecionar URL, selecione a caixa de texto Web e digite https://localhost.

    d. Selecione Registrar.

Conceder permissões

Para acessar a API de relatório do Azure Active Directory, conceda ao aplicativo as duas permissões a seguir:

API Permissão
Microsoft Graph Ler dados do diretório
Microsoft Graph Ler todos os dados de log de auditoria

Screenshot shows where you can select Add a permission in the A P I permissions pane.

A seção a seguir lista as etapas de configuração da API.

Para conceder ao seu aplicativo permissões para usar as APIs:

  1. Escolha Permissões de API e clique em Adicionar uma permissão.

    Screenshot shows the A P I Permissions page where you can select Add a permission.

  2. Na página Solicitar permissões de API, localize Microsoft Graph.

    Screenshot shows the Request A P I permissions page where you can select Azure Active Directory Graph.

  3. Na página Permissões necessárias, selecione Permissões de Aplicativo. Marque a caixa de seleção Diretório e, em seguida, selecione Directory.ReadAll. Marque a caixa de seleção AuditLog e, em seguida, selecione AuditLog.Read.All. Selecione Adicionar Permissões.

    Screenshot shows the Request A P I permissions page where you can select Application permissions.

  4. Na página Aplicativo de API de Relatório – Permissões de API, selecione Conceder consentimento do administrador.

    Screenshot shows the Reporting A P I Application A P I permissions page where you can select Grant admin consent.

Reunir definições de configuração

Esta seção mostra como obter as seguintes configurações de seu diretório:

  • Nome de domínio
  • ID do Cliente
  • Certificado ou segredo do cliente

Você precisa desses valores ao configurar chamadas para a API de relatórios. É recomendável usar um certificado porque é mais seguro.

Obter seu nome de domínio

Para obter seu nome de domínio:

  1. No Portal do Azure Microsoft, no painel de navegação esquerdo, selecione Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get domain name.

  2. Na página do Active Directory do Azure, selecione Nomes de domínio personalizados.

    Screenshot shows Custom domain names selected from Azure Active Directory.

  3. Copie o nome do domínio da lista de domínios.

Obtenha a ID do cliente do aplicativo

Para obter a ID do cliente do aplicativo:

  1. No Portal do Azure, no painel de navegação esquerdo, clique em Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get application's client ID.

  2. Selecione seu aplicativo na página Registros de aplicativo.

  3. Na página do aplicativo, navegue até ID do aplicativo e selecione clique para copiar.

    Screenshot shows the Reporting A P I Application page where you can copy the Application I D.

Obter seu segredo do cliente do aplicativo

Para obter seu segredo do cliente do aplicativo:

  1. No Portal do Azure, no painel de navegação esquerdo, clique em Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to get application's client secret.

  2. Selecione seu aplicativo na página Registros de aplicativo.

  3. Selecione Certificados e Segredos na página Aplicativo de API, na seção Segredos do Cliente, clique em + Novo Segredo do Cliente.

    Screenshot shows the Certificates & secrets page where you can add a client secret.

  4. Na página Adicionar um segredo do cliente, acrescente:

    a. Na caixa de texto Descrição, digite Reporting API.

    b. Como Expira, selecione Em 2 anos.

    c. Clique em Save (Salvar).

    d. Copie o valor da chave.

Carregue o certificado do seu aplicativo

Para carregar o certificado:

  1. No Portal do Azure Microsoft, no painel de navegação esquerdo, selecione Azure Active Directory.

    Screenshot shows Azure Active Directory selected from the Azure portal menu to upload the certificate.

  2. Na página Azure Active Directory, selecione Registro do aplicativo.

  3. Na página do aplicativo, selecione o seu aplicativo.

  4. Selecione Certificados & Segredos.

  5. Selecione Carregar certificado.

  6. Selecione o ícone de arquivo, acesse um certificado e, em seguida, selecione Adicionar.

    Screenshot shows uploading the certificate.

Solucionar problemas de erros na API de relatório

Esta seção lista as mensagens de erro comuns que você pode encontrar ao acessar relatórios de atividades usando a API do Microsoft Graph e as etapas para a resolução.

Erro: Falha ao obter as funções de usuário do Microsoft Graph

Entre em sua conta usando os botões de entrada na interface do usuário do Graph Explorer para evitar obter um erro ao tentar entrar usando o Graph Explorer.

Graph Explorer

Erro: Falha ao fazer a verificação da licença Premium do Microsoft Graph

Se você encontrar essa mensagem de erro ao tentar acessar entradas usando o Explorador do Graph, escolha Modificar permissões em sua conta na barra de navegação à esquerda e selecione Tasks.ReadWrite e Directory.Read.All.

Modify permissions UI

Erro: O locatário não é B2C ou não tem uma licença Premium

O acesso a relatórios de entrada requer uma licença do Azure Active Directory Premium 1 (P1). Se essa mensagem de erro for exibida quando você acessar as entradas, verifique se o locatário está licenciado com uma licença do Azure AD P1.

Erro: As funções permitidas não incluem Usuário.

Evite erros ao tentar acessar os logs de auditoria ou ao entrar usando a API. Verifique se sua conta faz parte da função Leitor de Segurança ou Leitor de Relatório em seu locatário do Azure Active Directory.

Erro: O aplicativo não tem a permissão 'Ler dados do diretório' do AAD

Erro: O aplicativo não tem a permissão “Ler todos os dados do log de auditoria” da API do Microsoft Graph

Siga as etapas nos Pré-requisitos para acessar a API de relatório do Azure Active Directory para garantir que seu aplicativo esteja em execução com o conjunto certo de permissões.

Próximas etapas