Introduzione ad Azure Active Directory Identity Protection e a Microsoft GraphGet started with Azure Active Directory Identity Protection and Microsoft Graph

Microsoft Graph è l'endpoint API unificato di Microsoft e la posizione in cui risiedono le API di Azure Active Directory Identity Protection .Microsoft Graph is the Microsoft unified API endpoint and the home of Azure Active Directory Identity Protection APIs. La prima API, identityRiskEvents, consente di eseguire una query in Microsoft Graph per ottenere un elenco di eventi di rischio e informazioni associate.The first API, identityRiskEvents, allows you to query Microsoft Graph for a list of risk events and associated information. Questo articolo fornisce un'introduzione all'esecuzione di query su questa API.This article gets you started querying this API. Per una presentazione più approfondita, la documentazione completa e l'accesso a Graph Explorer, vedere il sito di Microsoft Graph.For an in-depth introduction, full documentation, and access to the Graph Explorer, see the Microsoft Graph site.

La procedura per accedere ai dati di Identity Protection tramite Microsoft Graph si articola in quattro passaggi:There are four steps to accessing Identity Protection data through Microsoft Graph:

  1. Recuperare il nome di dominio.Retrieve your domain name.
  2. Creare una nuova registrazione di app.Create a new app registration.
  3. Usare questo segreto e qualche altra informazione per eseguire l'autenticazione in Microsoft Graph, dove si riceverà un token di autenticazione.Use this secret and a few other pieces of information to authenticate to Microsoft Graph, where you receive an authentication token.
  4. Usare questo token per inviare richieste all'endpoint API e ottenere dati di Identity Protection.Use this token to make requests to the API endpoint and get Identity Protection data back.

Ecco gli elementi che occorre avere prima di iniziare:Before you get started, you’ll need:

  • Privilegi di amministratore per creare l'applicazione in Azure ADAdministrator privileges to create the application in Azure AD
  • Nome di dominio del tenant, ad esempio contoso.onmicrosoft.comThe name of your tenant's domain (for example, contoso.onmicrosoft.com)

Recuperare il nome di dominioRetrieve your domain name

  1. Accedere al portale di Azure come amministratore.Sign in to your Azure portal as an administrator.

  2. Nel riquadro di spostamento a sinistra fare clic su Active Directory.On the left navigation pane, click Active Directory.

    Creazione di un'applicazione

  3. Nella sezione Gestisci fare clic su Proprietà.In the Manage section, click Properties.

    Creazione di un'applicazione

  4. Copiare il nome di dominio.Copy your domain name.

Creare una nuova registrazione di appCreate a new app registration

  1. Nella sezione Gestisci della pagina Active Directory fare clic su Registrazioni per l'app.On the Active Directory page, in the Manage section, click App registrations.

    Creazione di un'applicazione

  2. Nel menu in alto fare clic su Registrazione nuova applicazione.In the menu on the top, click New application registration.

    Creazione di un'applicazione

  3. Nella pagina Crea seguire questa procedura:On the Create page, perform the following steps:

    Creazione di un'applicazione

    a.a. Nella casella di testo Nome digitare un nome per l'applicazione, ad esempio Applicazione API evento di rischio AADIP.In the Name textbox, type a name for your application (e.g.: AADIP Risk Event API Application).

    b.b. Come Tipo selezionare Applicazione Web e/o API Web.As Type, select Web Application And / Or Web API.

    c.c. Nella casella di testo URL di accesso digitare http://localhost.In the Sign-on URL textbox, type http://localhost.

    d.d. Fare clic su Crea.Click Create.

  4. Per aprire la pagina Impostazioni, fare clic sulla registrazione di app appena creata nell'elenco delle applicazioni.To open the Settings page, in the applications list, click your newly created app registration.

  5. Copiare ID applicazione.Copy the Application ID.

Concedere all'applicazione le autorizzazioni per l'uso dell'APIGrant your application permission to use the API

  1. Nella pagina Impostazioni fare clic su Autorizzazioni necessarie.On the Settings page, click Required permissions.

    Creazione di un'applicazione

  2. Nella pagina Autorizzazioni necessarie fare clic su Aggiungi sulla barra degli strumenti in alto.On the Required permissions page, in the toolbar on the top, click Add.

    Creazione di un'applicazione

  3. Nella pagina Aggiungi accesso all'API fare clic su Selezionare un'API.On the Add API access page, click Select an API.

    Creazione di un'applicazione

  4. Nella pagina Selezionare un'API selezionare Microsoft Graph e quindi fare clic su Seleziona.On the Select an API page, select Microsoft Graph, and then click Select.

    Creazione di un'applicazione

  5. Nella pagina Aggiungi accesso all'API fare clic su Selezionare le autorizzazioni.On the Add API access page, click Select permissions.

    Creazione di un'applicazione

  6. Nella pagina Abilita accesso fare clic su Legge tutte le informazioni sugli eventi di rischio dell'identità e quindi su Seleziona.On the Enable Access page, click Read all identity risk information, and then click Select.

    Creazione di un'applicazione

  7. Nella pagina Aggiungi accesso all'API fare clic su Fatto.On the Add API access page, click Done.

    Creazione di un'applicazione

  8. Nella pagina Autorizzazioni necessarie fare clic su Concedi autorizzazioni e quindi su .On the Required Permissions page, click Grant Permissions, and then click Yes.

    Creazione di un'applicazione

Ottenere una chiave di accessoGet an access key

  1. Nella pagina Impostazioni fare clic su Chiavi.On the Settings page, click Keys.

    Creazione di un'applicazione

  2. Nel pagina Chiavi seguire questa procedura:On the Keys page, perform the following steps:

    Creazione di un'applicazione

    a.a. Nella casella di testo Descrizione chiave digitare una descrizione, ad esempio AADIP Risk Event.In the Key description textbox, type a description (for example, AADIP Risk Event).

    b.b. Come Durata selezionare Tra 1 anno.As Duration, select In 1 year.

    c.c. Fare clic su Save.Click Save.

    d.d. Copiare il valore della chiave e quindi incollarlo in una posizione sicura.Copy the key value, and then paste it into a safe location.

    Nota

    Se si perde la chiave, si dovrà tornare a questa sezione e crearne una nuova.If you lose this key, you will have to return to this section and create a new key. Mantenere la chiave segreta, perché chiunque ne fosse a conoscenza potrà accedere ai dati.Keep this key a secret: anyone who has it can access your data.

Autenticarsi in Microsoft Graph ed eseguire query sull'API eventi di rischio per le identitàAuthenticate to Microsoft Graph and query the Identity Risk Events API

A questo punto saranno disponibili:At this point, you should have:

  • Il nome di dominio del tenantThe name of your tenant's domain

  • L'ID clientThe client ID

  • La chiaveThe key

Per autenticarsi, inviare una richiesta POST a https://login.microsoft.com includendo nel corpo i parametri seguenti:To authenticate, send a post request to https://login.microsoft.com with the following parameters in the body:

Se la richiesta riesce, verrà restituito un token di autenticazione.If successful, this returns an authentication token.
Per chiamare l'API, creare un'intestazione con il parametro seguente:To call the API, create a header with the following parameter:

`Authorization`=”<token_type> <access_token>"

Quando si esegue l'autenticazione, è possibile trovare il tipo di token e il token di accesso nel token restituito.When authenticating, you can find the token type and access token in the returned token.

Inviare questa intestazione come richiesta all'URL dell'API seguente: https://graph.microsoft.com/beta/identityRiskEventsSend this header as a request to the following API URL: https://graph.microsoft.com/beta/identityRiskEvents

La risposta, se la richiesta riesce, è una raccolta di eventi di rischio per le identità e di dati associati nel formato JSON OData, che può essere analizzato e gestito secondo le esigenze.The response, if successful, is a collection of identity risk events and associated data in the OData JSON format, which can be parsed and handled as you see fit.

Di seguito è riportato il codice di esempio per autenticarsi e chiamare l'API con PowerShell.Here’s sample code for authenticating and calling the API using PowerShell.
Aggiungere semplicemente l'ID client, la chiave privata e il dominio del tenant.Just add your client ID, the secret key, and the tenant domain.

$ClientID       = "<your client ID here>"        # Should be a ~36 hex character string; insert your info here
$ClientSecret   = "<your client secret here>"    # Should be a ~44 character string; insert your info here
$tenantdomain   = "<your tenant domain here>"    # For example, contoso.onmicrosoft.com

$loginURL       = "https://login.microsoft.com"
$resource       = "https://graph.microsoft.com"

$body       = @{grant_type="client_credentials";resource=$resource;client_id=$ClientID;client_secret=$ClientSecret}
$oauth      = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body

Write-Output $oauth

if ($oauth.access_token -ne $null) {
    $headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

    $url = "https://graph.microsoft.com/beta/identityRiskEvents"
    Write-Output $url

    $myReport = (Invoke-WebRequest -UseBasicParsing -Headers $headerParams -Uri $url)

    foreach ($event in ($myReport.Content | ConvertFrom-Json).value) {
        Write-Output $event
    }

} else {
    Write-Host "ERROR: No Access Token"
} 

Passaggi successiviNext steps

È appena stata creata la prima chiamata a Microsoft Graph.Congratulations, you just made your first call to Microsoft Graph!
Ora è possibile eseguire query per ottenere un elenco di eventi di rischio per le identità e usare i dati come si preferisce.Now you can query identity risk events and use the data however you see fit.

Per altre informazioni su Microsoft Graph e su come creare applicazioni usando l'API Graph, vedere la documentazione e molto altro nel sito di Microsoft Graph.To learn more about Microsoft Graph and how to build applications using the Graph API, check out the documentation and much more on the Microsoft Graph site. Assicurarsi inoltre di creare un segnalibro alla pagina dell'API Azure AD Identity Protection che include l'elenco di tutte le API Identity Protection disponibili in Graph.Also, make sure to bookmark the Azure AD Identity Protection API page that lists all of the Identity Protection APIs available in Graph. In questa pagina sono visualizzate le nuove modalità aggiunte via via per l'utilizzo di Identity Protection tramite l'API.As we add new ways to work with Identity Protection via API, you’ll see them on that page.

Per informazioni correlate, vedere:For related information, see: