Procedura: eseguire l'autenticazione con AAD per l'accesso Esplora dati di AzureHow-To Authenticate with AAD for Azure Data Explorer Access

Il modo consigliato per accedere ad Azure Esplora dati consiste nell'eseguire l'autenticazione al servizio di Azure Active Directory (talvolta chiamato anche Azure ado semplicemente AAD).The recommended way to access Azure Data Explorer is by authenticating to the Azure Active Directory service (sometimes also called Azure AD, or simply AAD). In questo modo si garantisce che Azure Esplora dati non veda mai le credenziali della directory dell'entità di accesso, usando un processo in due fasi:Doing so guarantees that Azure Data Explorer never sees the accessing principal's directory credentials, by using a two-stage process:

  1. Nel primo passaggio il client comunica con il servizio AAD, ne esegue l'autenticazione e richiede un token di accesso emesso in modo specifico per l'endpoint di Azure Esplora dati specifico a cui il client intende accedere.In the first step, the client communicates with the AAD service, authenticates to it, and requests an access token issued specifically for the particular Azure Data Explorer endpoint the client intends to access.
  2. Nel secondo passaggio il client invia richieste ad Azure Esplora dati, fornendo il token di accesso acquisito nel primo passaggio come una prova di identità in Azure Esplora dati.In the second step the client issues requests to Azure Data Explorer, providing the access token acquired in the first step as a proof of identity to Azure Data Explorer.

Azure Esplora dati esegue quindi la richiesta per conto dell'entità di sicurezza per cui AAD ha emesso il token di accesso e tutti i controlli di autorizzazione vengono eseguiti usando questa identità.Azure Data Explorer then executes the request on behalf of the security principal for which AAD issued the access token, and all authorization checks are performed using this identity.

Nella maggior parte dei casi, è consigliabile usare uno degli SDK di Azure Esplora dati per accedere al servizio a livello di codice, poiché eliminano la maggior parte delle difficoltà di implementazione del flusso precedente (e molto altro).In most cases, the recommendation is to use one of Azure Data Explorer SDKs to access the service programmatically, as they remove much of the hassle of implementing the flow above (and much else). Vedere, ad esempio, .NET SDK.See, for example, the .NET SDK. Le proprietà di autenticazione vengono quindi impostate dalla stringa di connessione kusto.The authentication properties are then set by the Kusto connection string. Se ciò non è possibile, leggere le informazioni dettagliate su come implementare questo flusso manualmente.If that is not possible, please read on for detailed information on how to implement this flow yourself.

Gli scenari principali di autenticazione sono:The main authenticating scenarios are:

  • Applicazione client che autentica un utente che ha eseguito l'accesso.A client application authenticating a signed-in user. In questo scenario, un'applicazione interattiva (client) attiva un prompt di AAD all'utente per le credenziali, ad esempio nome utente e password.In this scenario, an interactive (client) application triggers an AAD prompt to the user for credentials (such as username and password). Vedere autenticazione utente,See user authentication,

  • Applicazione "non responsabile".A "headless" application. In questo scenario un'applicazione è in esecuzione senza che sia presente alcun utente per fornire le credenziali, ma l'applicazione viene autenticata come "stessa" in AAD usando alcune credenziali con cui è stato configurato.In this scenario an application is running with no user present to provide credentials, and instead the application authenticates as "itself" to AAD using some credentials it has been configured with. Vedere autenticazione delle applicazioni.See application authentication.

  • Autenticazione per conto dell' utente.On-behalf-of authentication. In questo scenario, talvolta denominato scenario "servizio Web" o "app Web", l'applicazione ottiene un token di accesso AAD da un'altra applicazione e quindi lo "converte" in un altro token di accesso AAD che può essere usato con Esplora dati di Azure.In this scenario, sometimes called the "web service" or "web app" scenario, the application gets an AAD access token from another application, and then "converts" it to an another AAD access token that can be used with Azure Data Explorer. In altre parole, l'applicazione funge da Mediator tra l'utente o l'applicazione che ha fornito le credenziali e il servizio Esplora dati di Azure.In other words, the application acts as a mediator between the user or application that provided credentials and the Azure Data Explorer service. Vedere autenticazione per conto dell'utente.See on-behalf-of authentication.

Specifica della risorsa AAD per Azure Esplora datiSpecifying the AAD resource for Azure Data Explorer

Quando si acquisisce un token di accesso da AAD, il client deve indicare ad AAD la risorsa AAD a cui deve essere emesso il token.When acquiring an access token from AAD, the client must tell AAD which AAD resource the token should be issued to. La risorsa AAD di un endpoint di Azure Esplora dati è l'URI dell'endpoint, salvo le informazioni sulla porta e il percorso.The AAD resource of a Azure Data Explorer endpoint is the URI of the endpoint, barring the port information and the path. Ad esempio:For example:

https://help.kusto.windows.net

Specifica dell'ID tenant di AADSpecifying the AAD tenant ID

AAD è un servizio multi-tenant e ogni organizzazione può creare un oggetto denominato directory in AAD.AAD is a multi-tenant service, and every organization can create an object called directory in AAD. L'oggetto directory include oggetti correlati alla sicurezza, ad esempio gli account utente, le applicazioni e i gruppi.The directory object holds security-related objects such as user accounts, applications, and groups. AAD si riferisce spesso alla directory come tenant.AAD often refers to the directory as a tenant. I tenant di AAD sono identificati da un GUID (ID tenant).AAD tenants are identifies by a GUID (tenant ID). In molti casi, i tenant di AAD possono essere identificati anche dal nome di dominio dell'organizzazione.In many cases, AAD tenants can also be identified by the domain name of the organization.

Ad esempio, un'organizzazione denominata "contoso" potrebbe avere l'ID tenant 4da81d62-e0a8-4899-adad-4349ca6bfe24 e il nome di dominio contoso.com .For example, an organization called "Contoso" might have the tenant ID 4da81d62-e0a8-4899-adad-4349ca6bfe24 and the domain name contoso.com.

Specifica dell'autorità AADSpecifying the AAD authority

AAD include diversi endpoint per l'autenticazione:AAD has a number of endpoints for authentication:

  • Quando il tenant che ospita l'entità in fase di autenticazione è noto (in altre parole, quando si conosce la directory di AAD in cui si trova l'utente o l'applicazione), l'endpoint di AAD è https://login.microsoftonline.com/{tenantId} .When the tenant hosting the principal being authenticated is known (in other words, when one knows which AAD directory the user or application are in), the AAD endpoint is https://login.microsoftonline.com/{tenantId}. Qui, {tenantId} è l'ID tenant dell'organizzazione in AAD o il nome di dominio (ad esempio contoso.com ).Here, {tenantId} is either the organization's tenant ID in AAD, or its domain name (e.g. contoso.com).

  • Quando il tenant che ospita l'entità autenticata non è noto, è possibile usare l'endpoint "comune" sostituendo quello {tenantId} precedente con il valore common .When the tenant hosting the principal being authenticated is not known, the "common" endpoint can be used by replacing the {tenantId} above with the value common.

Nota

L'endpoint AAD usato per l'autenticazione è denominato anche URL dell'autorità AAD o semplicemente autorità di AAD.The AAD endpoint used for authentication is also called AAD authority URL or simply AAD authority.

Cache del token AADAAD token cache

Quando si usa Azure Esplora dati SDK, i token AAD vengono archiviati nel computer locale in una cache dei token per singolo utente (un file denominato %AppData%\Kusto\tokenCache.Data che può essere accessibile o decrittografato solo dall'utente che ha eseguito l'accesso). La cache viene verificata per i token prima di richiedere all'utente le credenziali, riducendo così notevolmente il numero di volte in cui un utente deve immettere le credenziali.When using the Azure Data Explorer SDK, the AAD tokens are stored on the local machine in a per-user token cache (a file called %APPDATA%\Kusto\tokenCache.data which can only be accessed or decrypted by the signed-in user.) The cache is inspected for tokens before prompting the user for credentials, thus greatly reducing the number of times a user has to enter credentials.

Nota

La cache dei token di AAD riduce il numero di richieste interattive a cui un utente può accedere Esplora dati Azure, ma non le riduce.The AAD token cache reduces the number of interactive prompts that a user would be presented with accessing Azure Data Explorer, but does not reduce them complete. Inoltre, gli utenti non possono prevedere in anticipo quando verranno richieste le credenziali.Additionally, users cannot anticipate in advance when they will be prompted for credentials. Ciò significa che non è necessario tentare di usare un account utente per accedere ad Azure Esplora dati se è necessario supportare gli accessi non interattivi (ad esempio, quando si pianificano le attività), perché quando viene richiesto all'utente che ha eseguito l'accesso le credenziali, la richiesta avrà esito negativo in caso di accesso non interattivo.This means that one must not attempt to use a user account to access Azure Data Explorer if there's a need to support non-interactive logons (such as when scheduling tasks for example), because when the time comes for prompting the logged on user for credentials that prompt will fail if running under non-interactive logon.

Autenticazione utenteUser authentication

Il modo più semplice per accedere ad Azure Esplora dati con l'autenticazione utente consiste nell'usare Azure Esplora dati SDK e impostare la Federated Authentication proprietà della stringa di connessione Esplora dati di Azure su true .The easiest way to access Azure Data Explorer with user authentication is to use the Azure Data Explorer SDK and set the Federated Authentication property of the Azure Data Explorer connection string to true. La prima volta che si usa l'SDK per inviare una richiesta al servizio, all'utente verrà visualizzato un modulo di accesso per immettere le credenziali di AAD e, in caso di esito positivo dell'autenticazione, la richiesta verrà inviata.The first time the SDK is used to send a request to the service the user will be presented with a sign-in form to enter the AAD credentials, and on successful authentication the request will be sent.

Le applicazioni che non usano Azure Esplora dati SDK possono comunque usare la libreria client di AAD (ADAL) invece di implementare il client del protocollo di sicurezza del servizio AAD.Applications that do not use the Azure Data Explorer SDK can still use the AAD client library (ADAL) instead of implementing the AAD service security protocol client. https://github.com/AzureADSamples/WebApp-WebAPI-OpenIDConnect-DotNetPer un esempio di questa operazione, vedere [] da un'applicazione .NET.Please see [https://github.com/AzureADSamples/WebApp-WebAPI-OpenIDConnect-DotNet] for an example of doing so from a .NET application.

Per autenticare gli utenti per l'accesso Esplora dati di Azure, a un'applicazione deve prima essere concessa l' Access Kusto autorizzazione delegata.To authenticate users for Azure Data Explorer access, an application must first be granted the Access Kusto delegated permission. Per informazioni dettagliate, vedere la Guida di Kusto al provisioning delle applicazioni di AAD .Please see Kusto guide to AAD applications provisioning for details.

Il breve frammento di codice seguente illustra l'uso di ADAL per acquisire un token utente AAD per accedere ad Azure Esplora dati (avvia l'interfaccia utente di accesso):The following brief code snippet demonstrates using ADAL to acquire an AAD user token to access Azure Data Explorer (launches logon UI):

// Create an HTTP request
WebRequest request = WebRequest.Create(new Uri("https://{serviceNameAndRegion}.kusto.windows.net"));

// Create Auth Context for AAD (common or tenant-specific endpoint):
AuthenticationContext authContext = new AuthenticationContext("AAD Authority URL");

// Acquire user token for the interactive user for Kusto:
AuthenticationResult result = authContext.AcquireTokenAsync("https://{serviceNameAndRegion}.kusto.windows.net", "your client app id",
    new Uri("your client app resource id"), new PlatformParameters(PromptBehavior.Auto)).GetAwaiter().GetResult();

// Extract Bearer access token and set the Authorization header on your request:
string bearerToken = result.AccessToken;
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

Autenticazione applicazioneApplication authentication

Il breve frammento di codice seguente illustra l'uso di ADAL per acquisire un token dell'applicazione AAD per accedere ad Azure Esplora dati.The following brief code snippet demonstrates using ADAL to acquire an AAD application token to access Azure Data Explorer. In questo flusso non viene visualizzata alcuna richiesta di conferma e l'applicazione deve essere registrata con AAD e dotata di credenziali necessarie per eseguire l'autenticazione dell'applicazione (ad esempio una chiave dell'app rilasciata da AAD o un certificato X509v2 che è stato pre-registrato con AAD).In this flow no prompt is presented, and the application must be registered with AAD and equipped with credentials needed to perform application authentication (such as an app key issued by AAD, or an X509v2 certificate that has been pre-registered with AAD).

// Create an HTTP request
WebRequest request = WebRequest.Create(new Uri("https://{serviceNameAndRegion}.kusto.windows.net"));

// Create Auth Context for AAD (common or tenant-specific endpoint):
AuthenticationContext authContext = new AuthenticationContext("AAD Authority URL");

// Acquire application token for Kusto:
ClientCredential applicationCredentials = new ClientCredential("your application client ID", "your application key");
AuthenticationResult result =
        authContext.AcquireTokenAsync("https://{serviceNameAndRegion}.kusto.windows.net", applicationCredentials).GetAwaiter().GetResult();

// Extract Bearer access token and set the Authorization header on your request:
string bearerToken = result.AccessToken;
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

Autenticazione per conto diOn-behalf-of authentication

In questo scenario un'applicazione è stata inviata a un token di accesso AAD per una risorsa arbitraria gestita dall'applicazione e usa tale token per acquisire un nuovo token di accesso di AAD per la risorsa Esplora dati di Azure in modo che l'applicazione possa accedere a kusto per conto dell'entità di protezione indicata dal token di accesso AAD originale.In this scenario an application was sent an AAD access token for some arbitrary resource managed by the application, and it uses that token to acquire a new AAD access token for the Azure Data Explorer resource so that the application could access Kusto on behalf of the principal indicated by the original AAD access token.

Questo flusso è denominato flusso di scambio del token OAuth2.This flow is called the OAuth2 token exchange flow. In genere richiede più passaggi di configurazione con AAD e, in alcuni casi (a seconda della configurazione del tenant AAD), potrebbe richiedere un consenso speciale da parte dell'amministratore del tenant di AAD.It generally requires multiple configuration steps with AAD, and in some cases (depending on the AAD tenant configuration) might require special consent from the administrator of the AAD tenant.

Passaggio 1: stabilire una relazione di trust tra l'applicazione e il servizio Azure Esplora datiStep 1: Establish trust relationship between your application and the Azure Data Explorer service

  1. Aprire il portale di Azure e verificare di avere eseguito l'accesso al tenant corretto (vedere l'angolo superiore/destro per l'identità usata per accedere al portale).Open the Azure portal and make sure that you are signed-in to the correct tenant (see top/right corner for the identity used to sign-in to the portal).

  2. Nel riquadro risorse fare clic su Azure Active Directory, quindi registrazioni app.On the resources pane, click Azure Active Directory, then App registrations.

  3. Individuare l'applicazione che usa il flusso per conto di e aprirlo.Locate the application that uses the on-behalf-of flow and open it.

  4. Fare clic su autorizzazioni API, quindi aggiungere un'autorizzazione.Click API permissions, then Add a permission.

  5. Cercare l'applicazione denominata Azure Esplora dati e selezionarla.Search for the application named Azure Data Explorer and select it.

  6. Selezionare user_impersonation/Access kusto.Select user_impersonation / Access Kusto.

  7. Fare clic su Aggiungi autorizzazione.Click Add permission.

Passaggio 2: eseguire lo scambio di token nel codice del serverStep 2: Perform token exchange in your server code

// Create Auth Context for AAD (common or tenant-specific endpoint):
AuthenticationContext authContext = new AuthenticationContext("AAD Authority URL");

// Exchange your token for a Kusto token.
// You will need to provide your application's client ID and secret to authenticate your application
var tokenForKusto = authContext.AcquireTokenAsync(
    "https://{serviceNameAndRegion}.kusto.windows.net",
    new ClientCredential(customerAadWebApplicationClientId, customerAAdWebApplicationSecret),
    new UserAssertion(customerAadWebApplicationToken)).GetAwaiter().GetResult();

Passaggio 3: fornire il token per la libreria client di Kusto ed eseguire queryStep 3: Provide the token to Kusto client library and execute queries

var kcsb = new KustoConnectionStringBuilder(string.Format(
    "https://{0}.kusto.windows.net;fed=true;UserToken={1}",
    clusterName,
    tokenForKusto.AccessToken));
var client = KustoClientFactory.CreateCslQueryProvider(kcsb);
var queryResult = client.ExecuteQuery(databaseName, query, null);

Autenticazione e autorizzazione per client Web (JavaScript)Web Client (JavaScript) authentication and authorization

Configurazione dell'applicazione AADAAD application configuration

Nota

Oltre ai passaggi standard che è necessario seguire per configurare un'app AAD, è anche necessario abilitare il flusso implicito OAuth nell'applicazione AAD.In addition to the standard steps you need to follow in order to setup an AAD app, you should also enable oauth implicit flow in your AAD application. È possibile ottenere questo risultato selezionando manifesto dalla pagina dell'applicazione nel portale di Azure e impostare oauth2AllowImplicitFlow su true.You can achieve that by selecting manifest from your application page in the azure portal, and set oauth2AllowImplicitFlow to true.

DettagliDetails

Quando il client è un codice JavaScript in esecuzione nel browser dell'utente, viene usato il flusso di concessione implicita.When the client is a JavaScript code running in the user's browser, the implicit grant flow is used. Il token che concede l'accesso all'applicazione client al servizio Esplora dati di Azure viene fornito immediatamente dopo un'autenticazione riuscita come parte dell'URI di reindirizzamento (in un frammento URI); in questo flusso non è stato fornito alcun token di aggiornamento, pertanto il client non può memorizzare nella cache il token per periodi prolungati di tempo e riutilizzarlo.The token granting the client application access to the Azure Data Explorer service is provided immediately following a successful authentication as part of the redirect URI (in a URI fragment); no refresh token is given in this flow, so the client can't cache the token for prolonged periods of time and reuse it.

Come nel flusso di Native client, devono essere presenti due applicazioni AAD (server e client) con una relazione configurata.Like in the native client flow, there should be two AAD applications (Server and Client) with a configured relationship between them.

AdalJs richiede l'ottenimento di un id_token prima che vengano eseguite access_token chiamate.AdalJs requires getting an id_token before any access_token calls are made.

Il token di accesso viene ottenuto chiamando il AuthenticationContext.login() metodo e access_tokens vengono ottenuti chiamando Authenticationcontext.acquireToken() .Access token is obtains by calling the AuthenticationContext.login() method, and access_tokens are obtained by calling Authenticationcontext.acquireToken().

  • Creare un AuthenticationContext con la configurazione corretta:Create an AuthenticationContext with the right configuration:
var config = {
    tenant: "microsoft.com",
    clientId: "<Web AAD app with current website as reply URL. for example, KusDash uses f86897ce-895e-44d3-91a6-aaeae54e278c>",
    redirectUri: "<where you'd like AAD to redirect after authentication succeeds (or fails).>",
    postLogoutRedirectUri: "where you'd like AAD to redirect the browser after logout."
};

var authContext = new AuthenticationContext(config);
  • Chiamare authContext.login() prima di provare a acquireToken() se non è stato effettuato l'accesso.Call authContext.login() before trying to acquireToken() if you are not logged in. un modo efficace per sapere se è stato eseguito l'accesso o meno è chiamare authContext.getCachedUser() e verificare se restituisce false )a good way ot know if you're logged in or not is to call authContext.getCachedUser() and see if it returns false)
  • Chiamare authContext.handleWindowCallback() ogni volta che viene caricata la pagina.Call authContext.handleWindowCallback() whenever your page loads. Questo è il frammento di codice che intercetta il Reindirizzamento da AAD ed estrae il token dall'URL del frammento e lo memorizza nella cache.This is the piece of code that intercepts the redirect back from AAD and pulls the token out of the fragment URL and caches it.
  • Chiamare authContext.acquireToken() per ottenere il token di accesso effettivo, ora che si dispone di un token ID valido.Call authContext.acquireToken() to get the actual access token, now that you have a valid ID token. Il primo parametro di acquireToken sarà l'URL della risorsa dell'applicazione AAD del server kusto.The first parameter to acquireToken will be the Kusto server AAD application resource URL.
 authContext.acquireToken("<Kusto cluster URL>", callbackThatUsesTheToken);
  • in callbackThatUsesTheToken è possibile usare il token come bearer token nella richiesta di Esplora dati di Azure.in the callbackThatUsesTheToken you can use the token as a bearer token in the Azure Data Explorer request. ad esempio:for example:
var settings = {
    url: "https://" + clusterAndRegionName + ".kusto.windows.net/v1/rest/query",
    type: "POST",
    data: JSON.stringify({
        "db": dbName,
        "csl": query,
        "properties": null
    }),
    contentType: "application/json; charset=utf-8",
    headers: { "Authorization": "Bearer " + token },
    dataType: "json",
    jsonp: false,
    success: function(data, textStatus, jqXHR) {
        if (successCallback !== undefined) {
            successCallback(data.Tables[0]);
        }

    },
    error: function(jqXHR, textStatus, errorThrown) {
        if (failureCallback !==  undefined) {
            failureCallback(textStatus, errorThrown, jqXHR.responseText);
        }

    },
};

$.ajax(settings).then(function(data) {/* do something wil the data */});

Avviso: se si ottiene l'eccezione seguente o simile durante l'autenticazione:ReferenceError: AuthenticationContext is not definedWarning - if you get the following or similar exception when authenticating: ReferenceError: AuthenticationContext is not defined è probabile che non si disponga di AuthenticationContext nello spazio dei nomi globale.it's probably because you don't have AuthenticationContext in the global namespace. Sfortunatamente AdalJS dispone attualmente di un requisito non documentato che il contesto di autenticazione verrà definito nello spazio dei nomi globale.Unfortunately AdalJS currently has an undocumented requirement that the authentication context will be defined in the global namespace.