Share via

Cara mengautentikasi dengan Microsoft Authentication Library (MSAL) di aplikasi

  • Artikel

Untuk mengautentikasi secara terprogram dengan kluster, Anda perlu meminta token akses dari ID Microsoft Entra khusus untuk Azure Data Explorer. Token akses ini bertindak sebagai bukti identitas saat mengeluarkan permintaan ke kluster Anda. Anda dapat menggunakan salah satu alurMicrosoft Authentication Library (MSAL) untuk membuat token akses.

Artikel ini menjelaskan cara menggunakan MSAL untuk mengautentikasi prinsipal ke kluster Anda. Penggunaan langsung MSAL untuk mengautentikasi prinsipal terutama relevan dalam aplikasi web yang memerlukan autentikasi Atas Nama (OBO) atau autentikasi Aplikasi Halaman Tunggal (SPA). Untuk kasus lain, sebaiknya gunakan pustaka klien Kusto saat menyederhanakan proses autentikasi.

Dalam artikel ini, pelajari tentang skenario autentikasi utama, informasi yang akan diberikan untuk autentikasi yang berhasil, dan penggunaan MSAL untuk autentikasi.

Skenario autentikasi

Skenario autentikasi utama adalah sebagai berikut:

  • Autentikasi pengguna: Digunakan untuk memverifikasi identitas pengguna manusia.

  • Autentikasi aplikasi: Digunakan untuk memverifikasi identitas aplikasi yang perlu mengakses sumber daya tanpa intervensi manusia dengan menggunakan kredensial yang dikonfigurasi.

  • Autentikasi atas nama (OBO): Memungkinkan aplikasi untuk bertukar token dengan aplikasi tersebut dengan token untuk mengakses layanan Kusto. Alur ini harus diimplementasikan dengan MSAL.

  • Autentikasi aplikasi halaman tunggal (SPA): Memungkinkan aplikasi web SPA sisi klien untuk memasukkan pengguna dan mendapatkan token untuk mengakses kluster Anda. Alur ini harus diimplementasikan dengan MSAL.

Untuk autentikasi pengguna dan aplikasi, sebaiknya gunakan pustaka klien Kusto. Untuk autentikasi OBO dan SPA, pustaka klien Kusto tidak dapat digunakan.

Parameter autentikasi

Selama proses akuisisi token, klien perlu memberikan parameter berikut:

Nama parameter Deskripsi
ID Sumber Daya ID sumber daya untuk mengeluarkan token akses Microsoft Entra. ID sumber daya adalah URI kluster tanpa informasi dan jalur port.

Contoh: ID sumber daya untuk help kluster adalah https://help.kusto.windows.net.
ID penyewa Microsoft Entra Microsoft Entra ID adalah layanan multipenyewa, dan setiap organisasi dapat membuat objek yang disebut direktori yang menyimpan objek terkait keamanan seperti akun pengguna dan aplikasi. Microsoft Entra ID sering mengacu pada direktori sebagai penyewa. Setiap penyewa memiliki ID penyewa dalam bentuk GUID. Dalam banyak kasus, nama domain organisasi mungkin juga digunakan untuk mengidentifikasi penyewa Microsoft Entra.

Contoh: Organisasi "Contoso" mungkin memiliki ID 12345678-a123-4567-b890-123a456b789c penyewa dan nama contoso.comdomain .
URI otoritas Microsoft Entra Titik akhir yang digunakan untuk autentikasi. Direktori Microsoft Entra, atau penyewa, menentukan URI otoritas Microsoft Entra. URI adalah https://login.microsoftonline.com/{tenantId} tempat {tenantId} ID penyewa atau nama domain.

Contoh: Misalnya, https://login.microsoftonline.com/12345678-a123-4567-b890-123a456b789c.

Catatan

Titik akhir layanan Microsoft Entra berubah di cloud nasional. Saat bekerja dengan layanan Azure Data Explorer yang disebarkan di cloud nasional, atur titik akhir layanan Microsoft Entra cloud nasional yang sesuai.

Melakukan autentikasi pengguna dengan MSAL

Sampel kode berikut menunjukkan cara menggunakan MSAL untuk mendapatkan token otorisasi untuk kluster Anda. Otorisasi dilakukan dengan cara yang meluncurkan UI masuk interaktif. appRedirectUri adalah URL yang Microsoft Entra ID dialihkan setelah autentikasi berhasil diselesaikan. MSAL mengekstrak kode otorisasi dari pengalihan ini.

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));

Catatan

  • Sebaiknya gunakan pustaka klien Kusto jika memungkinkan. Pustaka ini menyederhanakan proses autentikasi dengan memungkinkan Anda menyediakan properti autentikasi di string koneksi Kusto.
  • Dengan pustaka klien Kusto, token Microsoft Entra disimpan dalam cache token lokal pada komputer pengguna untuk mengurangi berapa kali mereka dimintai kredensial. File cache adalah %APPDATA%\Kusto\userTokenCache.data dan hanya dapat diakses oleh pengguna yang masuk.

Melakukan autentikasi aplikasi dengan MSAL

Sampel kode berikut menunjukkan cara menggunakan MSAL untuk mendapatkan token otorisasi untuk kluster Anda. Dalam alur ini, tidak ada perintah yang disajikan. Aplikasi harus terdaftar dengan ID Microsoft Entra dan memiliki kunci aplikasi atau sertifikat X509v2 yang dikeluarkan oleh ID Microsoft Entra. Untuk menyiapkan aplikasi, lihat Menyediakan aplikasi 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));

Catatan

Sebaiknya gunakan pustaka klien Kusto jika memungkinkan. Pustaka ini menyederhanakan proses autentikasi dengan memungkinkan Anda menyediakan properti autentikasi di string koneksi Kusto.

Melakukan autentikasi Atas Nama (OBO)

Autentikasi atas nama relevan ketika aplikasi web atau layanan Anda bertindak sebagai mediator antara pengguna atau aplikasi dan kluster Anda.

Dalam skenario ini, aplikasi dikirim token akses Microsoft Entra untuk sumber daya arbitrer. Kemudian, aplikasi menggunakan token tersebut untuk memperoleh token akses Microsoft Entra baru untuk sumber daya Azure Data Explorer. Kemudian, aplikasi dapat mengakses kluster Anda atas nama prinsipal yang ditunjukkan oleh token akses Microsoft Entra asli. Alur ini disebut alur autentikasi atas nama OAuth 2.0. Ini umumnya memerlukan beberapa langkah konfigurasi dengan ID Microsoft Entra, dan dalam beberapa kasus mungkin memerlukan persetujuan khusus dari administrator penyewa Microsoft Entra.

Untuk melakukan autentikasi atas nama:

  1. Menyediakan aplikasi Microsoft Entra.

  2. Membangun hubungan kepercayaan antara aplikasi dan kluster Anda. Untuk melakukannya, ikuti langkah-langkah dalam Mengonfigurasi izin yang didelegasikan.

  3. Dalam kode server Anda, gunakan MSAL untuk melakukan pertukaran token.

    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. Gunakan token untuk menjalankan kueri. Contohnya:

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

Melakukan autentikasi Aplikasi Halaman Tunggal (SPA)

Untuk autentikasi untuk klien web SPA, gunakan alur kode otorisasi OAuth.

Dalam skenario ini, aplikasi dialihkan untuk masuk ke ID Microsoft Entra. Kemudian, ID Microsoft Entra mengalihkan kembali ke aplikasi dengan kode otorisasi di URI. Kemudian, aplikasi membuat permintaan ke titik akhir token untuk mendapatkan token akses. Token berlaku selama 24 jam di mana klien dapat menggunakannya kembali dengan memperoleh token secara tersembunyi.

platform identitas Microsoft memiliki tutorial terperinci untuk kasus penggunaan yang berbeda seperti React, Angular, dan JavaScript.

Untuk menyiapkan autentikasi untuk klien web:

  1. Menyediakan aplikasi Microsoft Entra.

  2. Konfigurasikan aplikasi seperti yang dijelaskan di MSAL.js 2.0 dengan alur kode autentikasi.

  3. Gunakan pustaka MSAL.js 2.0 untuk memasukkan pengguna dan mengautentikasi ke kluster Anda. platform identitas Microsoft memiliki tutorial terperinci untuk kasus penggunaan yang berbeda seperti React, Angular, dan JavaScript.

    Contoh berikut menggunakan pustaka MSAL.js untuk mengakses 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];

Konten terkait