Tutorial: Obtenha dados usando o Azure Ative Directory reportando API com certificados

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. Pode chamar estas APIs a partir de várias linguagens e ferramentas de programação. Se pretender aceder à AZure AD Reporting API sem intervenção do utilizador, deve configurar o seu acesso à utilização de certificados.

Neste tutorial, você aprende a usar um certificado de teste para aceder ao ms Graph API para reportagem. Não recomendamos a utilização de certificados de teste num ambiente de produção.

Pré-requisitos

  1. Para aceder aos dados de inscrição, certifique-se de que tem um inquilino Azure Ative Directory com uma licença premium (P1/P2). Veja como começar com Azure Ative Directory Premium para atualizar a sua edição Azure Ative Directory. 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 após o upgrade para uma licença premium.

  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ório para o inquilino.

  3. Preencha os pré-requisitos para aceder à API Azure Ative Directory reportando.

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

  5. Instale MSCloudIdUtils. Este módulo disponibiliza vários cmdlets de utilitário, incluindo:

    • As bibliotecas ADAL necessárias para a autenticação
    • Tokens de acesso de utilizador, chaves de aplicação e certificados, através da ADAL
    • Graph API que processa resultados paginados
  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 . A sua sessão deve ser semelhante a este ecrã: Windows PowerShell

  7. Utilize o comando PowerShell new-SelfSigned Para criar um certificado de teste.

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

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

Obter dados com a API de relatórios do Azure Active Directory com certificados

  1. Navegue para o portal do Azure, selecione Azure Ative Directory, em seguida, selecione Registos de aplicações e escolha a sua candidatura na lista.

  2. Selecione segredos de certificados & na secção Gerir a lâmina de registo de aplicação e selecione o Certificado de Upload.

  3. Selecione o ficheiro de certificado do passo anterior e selecione 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. Para encontrar a impressão digital, a partir da sua página de aplicação no portal, aceda aos segredos de Certificados & na secção Manage. A impressão digital estará na lista de certificados .

  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 -

    "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 sinal de acesso para a ms Graph API usando este certificado. Utilize o cmdlet Get-MSCloudIdMSGraphAccessTokenFromCert do módulo MSCloudIdUtils PowerShell, passando no ID da aplicação e na impressão digital que obteve do passo anterior.

    Screenshot shows a PowerShell window with a command that creates an access token.

  7. Use o token de acesso no seu script PowerShell para consultar o Graph API. Utilize o cmdlet Invoke-MSCloudIdMSGraphQuery do MSCloudIDUtils para enumerar os signins e o ponto final do directórioAudits. Este cmdlet lida com resultados com várias páginas e envia esses resultados para o gasoduto PowerShell.

  8. Consultar o directórioAudits ponto final para recuperar os registos de auditoria.

    Screenshot shows a PowerShell window with a command to query the directoryAudits endpoint using the access token from earlier in this procedure.

  9. Consultar o ponto final dos signins para recuperar os registos de inscrição.

    Screenshot shows a PowerShell window with a command to query the signins endpoint using the access token from earlier in this procedure.

  10. Pode agora optar por exportar estes dados para um CSV e economizar para um sistema SIEM. 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.

Passos seguintes