Partager via

Comment s’authentifier auprès de la bibliothèque d’authentification Microsoft (MSAL) dans les applications

  • Article

Pour vous authentifier par programmation auprès de votre cluster, vous devez demander un jeton d’accès à partir de Microsoft Entra ID spécifique à Azure Data Explorer. Ce jeton d’accès sert de preuve d’identité lors de l’émission de demandes à votre cluster. Vous pouvez utiliser l’un des flux MSAL (Microsoft Authentication Library) pour créer un jeton d’accès.

Cet article explique comment utiliser MSAL pour authentifier des principaux auprès de votre cluster. L’utilisation directe de MSAL pour authentifier les principaux est principalement pertinente dans les applications web qui nécessitent l’authentification au nom de (OBO) ou l’authentification SPA (Single Page Application). Dans d’autres cas, nous vous recommandons d’utiliser les bibliothèques clientes Kusto, car elles simplifient le processus d’authentification.

Dans cet article, découvrez les principaux scénarios d’authentification, les informations à fournir pour une authentification réussie et l’utilisation de MSAL pour l’authentification.

Scénarios d’authentification

Les principaux scénarios d’authentification sont les suivants :

  • Authentification de l’utilisateur : utilisée pour vérifier l’identité des utilisateurs humains.

  • Authentification de l’application : permet de vérifier l’identité d’une application qui doit accéder aux ressources sans intervention humaine à l’aide des informations d’identification configurées.

  • Authentification au nom de l’utilisateur (OBO) : permet à une application d’échanger un jeton pour cette application avec un jeton pour accéder à un service Kusto. Ce flux doit être implémenté avec MSAL.

  • Authentification par application monopage (SPA) : permet aux applications web SPA côté client de connecter des utilisateurs et d’obtenir des jetons pour accéder à votre cluster. Ce flux doit être implémenté avec MSAL.

Pour l’authentification utilisateur et application, nous vous recommandons d’utiliser les bibliothèques clientes Kusto. Pour l’authentification OBO et SPA, les bibliothèques clientes Kusto ne peuvent pas être utilisées.

Paramètres d’authentification

Pendant le processus d’acquisition de jetons, le client doit fournir les paramètres suivants :

Nom du paramètre Description
ID de ressource ID de ressource pour lequel émettre le jeton d’accès Microsoft Entra. L’ID de ressource est l’URI du cluster sans informations de port et chemin d’accès.

Exemple : L’ID de ressource du help cluster est https://help.kusto.windows.net.
ID de locataire Microsoft Entra Microsoft Entra ID est un service multilocataire, et chaque organisation peut créer un objet appelé répertoire qui contient des objets liés à la sécurité tels que des comptes d’utilisateur et des applications. Microsoft Entra ID fait souvent référence au répertoire en tant que locataire. Chaque locataire a un ID de locataire sous la forme d’un GUID. Dans de nombreux cas, le nom de domaine de l’organisation peut également être utilisé pour identifier le locataire Microsoft Entra.

Exemple : une organisation « Contoso » peut avoir l’ID 12345678-a123-4567-b890-123a456b789c de locataire et le nom contoso.comde domaine .
URI de l’autorité Microsoft Entra Point de terminaison utilisé pour l’authentification. L’annuaire Microsoft Entra ou le locataire détermine l’URI de l’autorité Microsoft Entra. L’URI est https://login.microsoftonline.com/{tenantId} {tenantId} l’emplacement où se trouve l’ID de locataire ou le nom de domaine.

Exemple : Par exemple, https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Remarque

Le point de terminaison de service Microsoft Entra change dans les clouds nationaux. Lors de l’utilisation d’un service Azure Data Explorer déployé dans un cloud national, définissez le point de terminaison de service Microsoft Entra national correspondant.

Effectuer l’authentification utilisateur avec MSAL

L’exemple de code suivant montre comment utiliser MSAL pour obtenir un jeton d’autorisation pour votre cluster. L’autorisation est effectuée de manière à lancer l’interface utilisateur de connexion interactive. Il appRedirectUri s’agit de l’URL vers laquelle l’ID Microsoft Entra redirige une fois l’authentification terminée. MSAL extrait le code d’autorisation de cette redirection.

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = PublicClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithRedirectUri("<appRedirectUri>")
    .Build();

var result = authClient.AcquireTokenInteractive(
    new[] { $"{kustoUri}/.default" } // Define scopes for accessing Azure Data Explorer cluster
).ExecuteAsync().Result;

var bearerToken = result.AccessToken;

var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

Remarque

  • Nous vous recommandons d’utiliser les bibliothèques clientes Kusto dans la mesure du possible. Ces bibliothèques simplifient le processus d’authentification en vous permettant de fournir des propriétés d’authentification dans le chaîne de connexion Kusto.
  • Avec les bibliothèques clientes Kusto, les jetons Microsoft Entra sont stockés dans un cache de jetons local sur l’ordinateur de l’utilisateur pour réduire le nombre de fois où ils sont invités à entrer des informations d’identification. Le fichier cache est %APPDATA%\Kusto\userTokenCache.data et est accessible uniquement par l’utilisateur connecté.

Effectuer l’authentification d’application avec MSAL

L’exemple de code suivant montre comment utiliser MSAL pour obtenir un jeton d’autorisation pour votre cluster. Dans ce flux, aucune invite n’est présentée. L’application doit être inscrite auprès de l’ID Microsoft Entra et avoir une clé d’application ou un certificat X509v2 émis par l’ID Microsoft Entra. Pour configurer une application, consultez Provisionner une application Microsoft Entra.

var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = ConfidentialClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithClientSecret("<appKey>") // Can be replaced by .WithCertificate to authenticate with an X.509 certificate
    .Build();

var result = authClient.AcquireTokenForClient(
    new[] { $"{kustoUri}/.default" } // Define scopes for accessing Azure Data Explorer cluster
).ExecuteAsync().Result;
var bearerToken = result.AccessToken;

var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", bearerToken));

Remarque

Nous vous recommandons d’utiliser les bibliothèques clientes Kusto dans la mesure du possible. Ces bibliothèques simplifient le processus d’authentification en vous permettant de fournir des propriétés d’authentification dans le chaîne de connexion Kusto.

Effectuer l’authentification au nom de (OBO)

L’authentification au nom est pertinente lorsque votre application ou service web agit comme médiateur entre l’utilisateur ou l’application et votre cluster.

Dans ce scénario, une application est envoyée un jeton d’accès Microsoft Entra pour une ressource arbitraire. Ensuite, l’application utilise ce jeton pour acquérir un nouveau jeton d’accès Microsoft Entra pour la ressource Azure Data Explorer. Ensuite, l’application peut accéder à votre cluster pour le compte du principal indiqué par le jeton d’accès Microsoft Entra d’origine. Ce flux est appelé flux d’authentification OAuth 2.0 pour le compte. Il nécessite généralement plusieurs étapes de configuration avec l’ID Microsoft Entra et, dans certains cas, peut nécessiter un consentement spécial de l’administrateur du locataire Microsoft Entra.

Pour effectuer l’authentification au nom de l’utilisateur :

  1. Provisionnez une application Microsoft Entra.

  2. Établissez une relation d’approbation entre l’application et votre cluster. Pour ce faire, suivez les étapes décrites dans Configurer les autorisations déléguées.

  3. Dans votre code de serveur, utilisez MSAL pour effectuer l’échange de jetons.

    var kustoUri = "https://<clusterName>.<region>.kusto.windows.net";

var authClient = ConfidentialClientApplicationBuilder.Create("<appId>")
    .WithAuthority($"https://login.microsoftonline.com/<appTenant>")
    .WithClientSecret("<appKey>") // Can be replaced by .WithCertificate to authenticate with an X.509 certificate
    .Build();

var result = authClient.AcquireTokenOnBehalfOf(
    new[] { $"{kustoUri}/.default" }, // Define scopes for accessing your cluster
    new UserAssertion("<userAccessToken>") // Encode the "original" token that will be used for exchange
).ExecuteAsync().Result;
var accessTokenForAdx = result.AccessToken;

  4. Utilisez le jeton pour exécuter des requêtes. Par exemple :

    var request = WebRequest.Create(new Uri(kustoUri));
request.Headers.Set(HttpRequestHeader.Authorization, string.Format(CultureInfo.InvariantCulture, "{0} {1}", "Bearer", accessTokenForAdx));

Effectuer l’authentification par application monopage (SPA)

Pour l’authentification pour un client web SPA, utilisez le flux de code d’autorisation OAuth.

Dans ce scénario, l’application est redirigée pour se connecter à l’ID Microsoft Entra. Ensuite, l’ID Microsoft Entra redirige vers l’application avec un code d’autorisation dans l’URI. Ensuite, l’application envoie une demande au point de terminaison du jeton pour obtenir le jeton d’accès. Le jeton est valide pendant 24 heures pendant laquelle le client peut le réutiliser en acquérant le jeton en mode silencieux.

Plateforme d’identités Microsoft a des didacticiels détaillés pour différents cas d’usage tels que React, Angular et JavaScript.

Pour configurer l’authentification pour un client web :

  1. Provisionnez une application Microsoft Entra.

  2. Configurez l’application comme décrit dans MSAL.js 2.0 avec le flux de code d’authentification.

  3. Utilisez la bibliothèque MSAL.js 2.0 pour connecter un utilisateur et s’authentifier auprès de votre cluster. Plateforme d’identités Microsoft a des didacticiels détaillés pour différents cas d’usage tels que React, Angular et JavaScript.

    L’exemple suivant utilise la bibliothèque MSAL.js pour accéder à Azure Data Explorer.

    import * as msal from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "<AAD client application ID>",
    authority: "https://login.microsoftonline.com/<AAD tenant ID>",
  },
};

const msalInstance = new msal.PublicClientApplication(msalConfig);
const myAccounts = msalInstance.getAllAccounts();

// If no account is logged in, redirect the user to log in.
if (myAccounts === undefined || myAccounts.length === 0) {
  try {
    await msalInstance.loginRedirect({
      scopes: ["https://help.kusto.windows.net/.default"],
    });
  } catch (err) {
    console.error(err);
  }
}
const account = myAccounts[0];
const name = account.name;
window.document.getElementById("main").innerHTML = `Hi ${name}!`;

// Get the access token required to access the specified Azure Data Explorer cluster.
const accessTokenRequest = {
  account,
  scopes: ["https://help.kusto.windows.net/.default"],
};
let acquireTokenResult = undefined;
try {
  acquireTokenResult = await msalInstance.acquireTokenSilent(accessTokenRequest);
} catch (error) {
  if (error instanceof InteractionRequiredAuthError) {
    await msalInstance.acquireTokenRedirect(accessTokenRequest);
  }
}

const accessToken = acquireTokenResult.accessToken;

// Make requests to the specified cluster with the token in the Authorization header.
const fetchResult = await fetch("https://help.kusto.windows.net/v2/rest/query", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    db: "Samples",
    csl: "StormEvents | count",
  }),
});
const jsonResult = await fetchResult.json();

// The following line extracts the first cell in the result data.
const count = jsonResult.filter((x) => x.TableKind === "PrimaryResult")[0].Rows[0][0];

Contenu connexe