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 le 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 a dati di accesso, assicurarsi di avere un tenant di Azure Active Directory con una licenza Premium (P1/P2). vedere Procedura: Effettuare l'iscrizione alle edizioni Azure Active Directory Premium per aggiornare l'edizione di Azure Active Directory in uso. Si noti che se i dati sulle attività non fossero disponibili prima dell'aggiornamento, saranno necessari un paio di giorni per visualizzare i dati nei report dopo aver eseguito l'aggiornamento a una licenza Premium.

  2. Creare o passare a un account utente nel ruolo Amministratore globale, Amministratore della sicurezza, Ruolo con autorizzazioni di lettura per la sicurezza o Ruolo con autorizzazioni di lettura per i 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:

    • Le librerie ADAL necessarie per l'autenticazione
    • Token di accesso dell'utente, chiavi dell'applicazione e certificati con ADAL
    • 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 avrà un aspetto 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 di Azure, selezionare Azure Active Directory, quindi selezionare Registrazioni app e scegliere l'app dall'elenco.

  2. Selezionare Certificati e segreti nella sezione Gestisci nel pannello Registrazione dell'applicazione e selezionare Carica certificato.

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

  4. Si noti l'ID applicazione e l'identificazione personale del certificato appena registrato con l'applicazione. Per trovare l'identificazione personale, dalla pagina dell'applicazione nel portale passare a Certificati e segreti 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 da MSCloudIDUtils per enumerare l'endpoit 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 dell'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