Esercitazione: Ottenere dati con l'API di creazione report di Azure Active Directory con certificati

Le API di creazione report di Azure Active Directory (Azure AD) forniscono l'accesso ai dati dal codice tramite un set di API basate su REST. È possibile chiamare queste API da numerosi linguaggi di programmazione e strumenti. Se si vuole accedere all'API di creazione report di Azure AD senza l'intervento dell'utente, è necessario configurare l'accesso per l'uso di certificati.

In questa esercitazione si apprenderà come usare un certificato di test per accedere all'API Graph Microsoft e creare report. Non è consigliabile usare certificati di test in un ambiente di produzione.

Prerequisiti

  1. Per accedere ai dati di accesso, assicurarsi di avere un tenant di Azure AD con una licenza Premium (P1/P2). Vedere Introduzione ad Azure Active Directory Premium per aggiornare l'edizione di Azure AD. Se prima dell'aggiornamento non sono presenti dati sulle attività, saranno necessari un paio di giorni prima della visualizzazione dei dati nei report dopo l'aggiornamento a una licenza Premium.

  2. Creare o passare a un account utente nel ruolo Amministratore globale, Amministratore della sicurezza, Lettore di sicurezza o Lettore di report per il tenant.

  3. Completare i prerequisiti di accesso all'API di creazione report di Azure Active Directory.

  4. Scaricare e installare Azure AD PowerShell V2.

  5. Installare MSCloudIdUtils. Questo modulo offre diversi cmdlet di utilità, tra cui:

    • Librerie di Microsoft Authentication Library necessarie per l'autenticazione
    • Token di accesso da utenti, chiavi dell'applicazione e certificati tramite Microsoft Authentication Library
    • API Graph che gestisce i risultati di paging
  6. Se è la prima volta che si usa il modulo, eseguire Install-MSCloudIdUtilsModule; in caso contrario, è possibile importarlo tramite il comando Import-Module di PowerShell. La sessione dovrebbe essere simile a questa schermata: Windows PowerShell

  7. Usare il cmdlet New-SelfSignedCertificate di PowerShell per creare un certificato di test.

    $cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
    
  8. Usare il cmdlet Export-Certificate per esportarlo in un file del certificato.

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

Ottenere dati con l'API di creazione report di Azure Active Directory con certificati

  1. Passare al portale> diAzure Active Directory>Registrazioni app e scegliere l'applicazione dall'elenco.

  2. Nell'area Registrazione applicazione selezionare Certificati & segreti nella sezione Gestisci e quindi selezionare Carica certificato.

  3. Selezionare il file di certificato del passaggio precedente e selezionare Aggiungi.

  4. Prendere nota dell'ID applicazione e dell'identificazione personale del certificato registrato con l'applicazione. Per trovare l'identificazione personale, dalla pagina dell'applicazione nel portale passare a Segreti certificati & nella sezione Gestisci. L'identificazione personale sarà visualizzata nell'elenco Certificati.

  5. Aprire il manifesto dell'applicazione nell'editor manifesto inline e verificare che la proprietà keyCredentials sia aggiornata con le nuove informazioni del certificato usando lo schema seguente.

    "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. A questo punto è possibile ottenere un token di accesso per l'API Graph usando questo certificato. Usare il cmdlet Get-MSCloudIdMSGraphAccessTokenFromCert dal modulo MSCloudIdUtils di PowerShell passando l'ID dell'applicazione e l'identificazione personale ottenuta nel passaggio precedente.

    Screenshot mostra una finestra di PowerShell con un comando che crea un token di accesso.

  7. Usare il token di accesso nello script di PowerShell per eseguire una query sull'API Graph. Usare il cmdlet Invoke-MSCloudIdMSGraphQuery di MSCloudIDUtils per enumerare l'endpoint signins e directoryAudits . Questo cmdlet gestisce i risultati di multi-paging e li invia alla pipeline di PowerShell.

  8. Eseguire una query sull'endpoint directoryAudits per recuperare i log di controllo.

    Screenshot che mostra una finestra di PowerShell con un comando per eseguire una query sull'endpoint directoryAudits usando il token di accesso ottenuto in precedenza in questa procedura.

  9. Eseguire una query sull'endpoint signins per recuperare i log di accesso.

    Screenshot che mostra una finestra di PowerShell con un comando per eseguire una query sull'endpoint signins usando il token di accesso ottenuto in precedenza in questa procedura.

  10. È ora possibile scegliere di esportare i dati in un file CSV e salvarlo in un sistema SIEM. È anche possibile eseguire il wrapping dello script in un'attività pianificata per ottenere periodicamente i dati di Azure AD dal tenant senza dover archiviare le chiavi dell'applicazione nel codice sorgente.

Passaggi successivi