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.

Importante

Microsoft consiglia di gestire Azure AD usando l'interfaccia di amministrazione di Azure AD nel portale di Azure invece di usare il portale di Azure classico citato nel presente articolo.Microsoft recommends that you manage Azure AD using the Azure AD admin center in the Azure portal instead of using the Azure classic portal referenced in this article.

Per l'accesso ai dati di Identity Protection tramite Microsoft Graph sono disponibili tre passaggi:There are three steps to accessing Identity Protection data through Microsoft Graph:

  1. Aggiungere un'applicazione con un segreto client.Add an application with a client secret.
  2. 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.
  3. 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)

Aggiungere un'applicazione con un segreto clientAdd an application with a client secret

  1. Accedere al portale di Azure classico come amministratore.Sign in to your Azure classic portal as an administrator.
  2. Nel riquadro di spostamento sinistro fare clic su Active Directory.On on the left navigation pane, click Active Directory.

    Creazione di un'applicazione

  3. Nell'elenco Directory selezionare la directory per la quale si desidera abilitare l'integrazione delle directory.From the Directory list, select the directory for which you want to enable directory integration.
  4. Scegliere Applicazionidal menu in alto.In the menu on the top, click Applications.

    Creazione di un'applicazione

  5. Fare clic su Add nella parte inferiore della pagina.Click Add at the bottom of the page.

    Creazione di un'applicazione

  6. Nella finestra di dialogo Come procedere fare clic su Aggiungi un'applicazione che l'organizzazione sta sviluppando.On the What do you want to do dialog, click Add an application my organization is developing.

    Creazione di un'applicazione

  7. Nella finestra di dialogo Informazioni sull'applicazione seguire questa procedura:On the Tell us about your application dialog, 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. Fare clic su Avanti.Click Next.

  8. Nella finestra di dialogo Proprietà dell'app seguire questa procedura:On the App properties dialog, perform the following steps:

    Creazione di un'applicazione

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

    b.b. Nella casella di testo URI ID app digitare http://localhost.In the App ID URI textbox, type http://localhost.

    c.c. Fare clic su Completa.Click Complete.

A questo punto è possibile configurare l'applicazione.Your can now configure your application.

Creazione di un'applicazione

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

  1. Nella pagina dell'applicazione scegliere Configuradal menu in alto.On your application's page, in the menu on the top, click Configure.

    Creazione di un'applicazione

  2. Nella sezione Autorizzazioni per altre applicazioni fare clic su Aggiungi applicazione.In the permissions to other applications section, click Add application.

    Creazione di un'applicazione

  3. Nella finestra di dialogo Autorizzazioni per altre applicazioni seguire questa procedura:On the permissions to other applications dialog, perform the following steps:

    Creazione di un'applicazione

    a.a. Selezionare Microsoft Graph.Select Microsoft Graph.

    b.b. Fare clic su Complete.Click Complete.

  4. Fare clic su Autorizzazioni applicazione: 0 e quindi selezionare Legge tutte le informazioni sugli eventi di rischio dell'identità.Click Application Permissions: 0, and then select Read all identity risk event information.

    Creazione di un'applicazione

  5. Fare clic su Salva nella parte inferiore della pagina.Click Save at the bottom of the page.

    Creazione di un'applicazione

Ottenere una chiave di accessoGet an access key

  1. Nella sezione Chiavi della pagina dell'applicazione selezionare 1 anno come durata.On your application's page, in the keys section, select 1 year as duration.

    Creazione di un'applicazione

  2. Fare clic su Salva nella parte inferiore della pagina.Click Save at the bottom of the page.

    Creazione di un'applicazione

  3. Nella sezione Chiavi copiare il valore della chiave appena creata e quindi incollarla in una posizione sicura.in the keys section, copy the value of your newly created key, and then paste it into a safe location.

    Creazione di un'applicazione

    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.

  4. Nella sezione Proprietà copiare l'ID client e conservarlo in un luogo sicuro.In the properties section, copy the Client ID, and then paste it into a safe location.

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:

  • L'ID client copiato in precedenzaThe client ID you copied above
  • La chiave copiata in precedenzaThe key you copied above
  • Il nome di dominio del tenantThe name of your tenant's domain

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:

Nota

È necessario fornire i valori per i parametri client_id e client_secret.You need to provide values for the client_id and the client_secret parameter.

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 see fit.

Ecco 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 e il dominio del tenant.Just add your client ID, key, and 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.

Risorse aggiuntiveAdditional resources