Tutorial: Obtenha dados utilizando o Diretório Ativo Azure reportando API com certificadosTutorial: Get data using the Azure Active Directory reporting API with certificates

As APIs de relatórios Azure Active Directory (Azure AD) proporcionam acesso programático aos dados através de um conjunto de APIs baseadas em REST.The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. Pode chamar estas APIs a partir de várias linguagens e ferramentas de programação.You can call these APIs from a variety of programming languages and tools. Se pretender aceder à AZure AD Reporting API sem intervenção do utilizador, tem de configurar o seu acesso à utilização de certificados.If you want to access the Azure AD Reporting API without user intervention, you must configure your access to use certificates.

Neste tutorial, você aprende a usar um certificado de teste para aceder à API do Ms Graph para reportagem.In this tutorial, you learn how to use a test certificate to access the MS Graph API for reporting. Não recomendamos a utilização de certificados de teste num ambiente de produção.We don't recommend using test certificates in a production environment.

Pré-requisitosPrerequisites

  1. Para aceder aos dados de inscrição, certifique-se de que tem um inquilino do Azure Ative Directory com uma licença premium (P1/P2).To access sign-in data, make sure you have an Azure Active Directory tenant with a premium (P1/P2) license. Veja como começar com o Azure Ative Directory Premium para atualizar a sua edição do Azure Ative Directory.See Getting started with Azure Active Directory Premium to upgrade your Azure Active Directory edition. Note que se não tiver quaisquer dados de atividades antes da atualização, levará alguns dias para que os dados apareçam nos relatórios depois de atualizar para uma licença premium.Note that if you did not have any activities data prior to the upgrade, it will take a couple of days for the data to show up in the reports after you upgrade to a premium license.

  2. Criar ou mudar para uma conta de utilizador no administrador global, administrador de segurança, leitor de segurança ou função de leitor de relatórios para o arrendatário.Create or switch to a user account in the global administrator, security administrator, security reader or report reader role for the tenant.

  3. Preencha os pré-requisitos para aceder ao Azure Ative Directory reportando API.Complete the prerequisites to access the Azure Active Directory reporting API.

  4. Faça o download e instale o Azure AD PowerShell V2.Download and install Azure AD PowerShell V2.

  5. Instale MSCloudIdUtils.Install MSCloudIdUtils. Este módulo disponibiliza vários cmdlets de utilitário, incluindo:This module provides several utility cmdlets including:

    • As bibliotecas ADAL necessárias para a autenticaçãoThe ADAL libraries needed for authentication
    • Tokens de acesso de utilizador, chaves de aplicação e certificados, através da ADALAccess tokens from user, application keys, and certificates using ADAL
    • Graph API que processa resultados paginadosGraph API handling paged results
  6. Se for a primeira vez que utiliza o módulo executar Install-MSCloudIdUtilsModule, caso contrário, importe-o utilizando o comando PowerShell do módulo de importação.If it's your first time using the module run Install-MSCloudIdUtilsModule, otherwise import it using the Import-Module PowerShell command. A sua sessão deve ser semelhante a este ecrã:  Windows PowerShellYour session should look similar to this screen: Windows PowerShell

  7. Utilize o comando New-SelfSignedCertificate PowerShell para criar um certificado de teste.Use the New-SelfSignedCertificate PowerShell commandlet to create a test certificate.

    $cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
    
  8. Utilize o comando de Certificado de Exportação para exportá-lo para um ficheiro de certificado.Use the Export-Certificate commandlet to export it to a certificate file.

    Export-Certificate -Cert $cert -FilePath "C:\Reporting\MSGraph_ReportingAPI.cer"
    
    

Obter dados com a API de relatórios do Azure Active Directory com certificadosGet data using the Azure Active Directory reporting API with certificates

  1. Navegue até ao portal Azure, selecione Azure Ative Directory, em seguida, selecione as inscrições da App e escolha a sua aplicação na lista.Navigate to the Azure portal, select Azure Active Directory, then select App registrations and choose your application from the list.

  2. Selecione Certificados & segredos na secção Gerir a lâmina de registo da aplicação e selecione o Certificado de Upload.Select Certificates & secrets under Manage section on Application registration blade and select Upload Certificate.

  3. Selecione o ficheiro de certificado do passo anterior e selecione Adicionar.Select the certificate file from the previous step and select Add.

  4. Note o ID do formulário de aplicação e a impressão digital do certificado que acabou de registar na sua aplicação.Note the Application ID, and the thumbprint of the certificate you just registered with your application. Para encontrar a impressão digital, a partir da sua página de aplicação no portal, vá a Certificados & segredos na secção Manage.To find the thumbprint, from your application page in the portal, go to Certificates & secrets under Manage section. A impressão digital estará na lista de certificados.The thumbprint will be under the Certificates list.

  5. Abra o manifesto de aplicação no editor manifesto inline e verifique se a propriedade keyCredentials é atualizada com as informações do seu novo certificado, conforme mostrado abaixo -Open the application manifest in the inline manifest editor and verify the keyCredentials property is updated with your new certificate information as shown below -

    "keyCredentials": [
         {
             "customKeyIdentifier": "$base64Thumbprint", //base64 encoding of the certificate hash
             "keyId": "$keyid", //GUID to identify the key in the manifest
             "type": "AsymmetricX509Cert",
             "usage": "Verify",
             "value":  "$base64Value" //base64 encoding of the certificate raw data
         }
     ]
    
  6. Agora, você pode obter um token de acesso para a MS Graph API usando este certificado.Now, you can get an access token for the MS Graph API using this certificate. Utilize o cmdlet Get-MSCloudIdMSGraphAccessTokenFromCert do módulo MSCloudIdUtils PowerShell, passando no ID da aplicação e na impressão digital que obteve a partir do passo anterior.Use the Get-MSCloudIdMSGraphAccessTokenFromCert cmdlet from the MSCloudIdUtils PowerShell module, passing in the Application ID and the thumbprint you obtained from the previous step.

    A screenshot mostra uma janela PowerShell com um comando que cria um token de acesso.

  7. Utilize o token de acesso no seu script PowerShell para consultar a API do gráfico.Use the access token in your PowerShell script to query the Graph API. Utilize o cmdlet Invoke-MSCloudIdMSGraphQuery do MSCloudIDUtils para enumerar os signins e o ponto final do directórioAudits.Use the Invoke-MSCloudIdMSGraphQuery cmdlet from the MSCloudIDUtils to enumerate the signins and directoryAudits endpoint. Este cmdlet lida com resultados com várias páginas e envia esses resultados para o gasoduto PowerShell.This cmdlet handles multi-paged results, and sends those results to the PowerShell pipeline.

  8. Consultar o directórioAudits ponto final para recuperar os registos de auditoria.Query the directoryAudits endpoint to retrieve the audit logs.

    A screenshot mostra uma janela PowerShell com um comando para consultar o ponto final do directórioAudits usando o token de acesso de mais cedo neste procedimento.

  9. Consultar o ponto final dos signins para recuperar os registos de inscrição.Query the signins endpoint to retrieve the sign-in logs.

    A screenshot mostra uma janela PowerShell com um comando para consultar o ponto final do signins usando o token de acesso de início neste procedimento.

  10. Pode agora optar por exportar estes dados para um CSV e economizar para um sistema SIEM.You can now choose to export this data to a CSV and save to a SIEM system. Também pode encapsular o script numa tarefa agendada para obter dados do Azure AD a partir do seu inquilino periodicamente, sem ter de armazenar chaves de aplicação no código de origem.You can also wrap your script in a scheduled task to get Azure AD data from your tenant periodically without having to store application keys in the source code.

Passos seguintesNext steps