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 fluxMSAL (Microsoft Authentication Library) pour créer un jeton d’accès.

Cet article explique comment utiliser MSAL pour authentifier les 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 OBO (On-behalf-of) ou l’authentification d’application monopage (SPA). Pour 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 scénarios d’authentification main, les informations à fournir pour une authentification réussie et l’utilisation de MSAL pour l’authentification.

Scénarios d’authentification

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

  • Authentification de l’utilisateur : permet de 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 d’informations d’identification configurées.

  • Authentification de la part de (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 d’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 des utilisateurs et des applications, 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 ni chemin d’accès.

Exemple : l’ID de ressource pour le help cluster est https://help.kusto.windows.net.
ID de locataire Microsoft Entra Microsoft Entra ID est un service multilocataire, et chaque organization 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 du organization peut également être utilisé pour identifier le locataire Microsoft Entra.

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

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

Notes

Le point de terminaison de service Microsoft Entra change dans les clouds nationaux. Lorsque vous utilisez un service Azure Data Explorer déployé dans un cloud national, définissez le point de terminaison de service Microsoft Entra cloud 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. appRedirectUri Est l’URL vers laquelle Microsoft Entra ID est redirigé 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));

Notes

  • 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, Microsoft Entra jetons sont stockés dans un cache de jetons local sur l’ordinateur de l’utilisateur pour réduire le nombre de fois où il est invité à 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 avec Microsoft Entra ID et avoir une clé d’application ou un certificat X509v2 émis par Microsoft Entra ID. 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));

Notes

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 de la part de (OBO)

L’authentification de la part de est pertinente lorsque votre application ou service web agit en tant que médiateur entre l’utilisateur ou l’application et votre cluster.

Dans ce scénario, une application reçoit 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 on-behalf-of OAuth 2.0. Il nécessite généralement plusieurs étapes de configuration avec l’ID de Microsoft Entra et, dans certains cas, peut nécessiter un consentement spécial de l’administrateur du locataire Microsoft Entra.

Pour effectuer l’authentification de la part de :

  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 d’application monopage (SPA)

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

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

Plateforme d'identités Microsoft propose des tutoriels 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 propose des tutoriels 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