Permintaan Http Yang Ditandatangani

MSAL.js menyediakan kelas SignedHttpRequest untuk memudahkan pembuatan permintaan HTTP yang ditandatangani (SHR) bagi payload (misalnya, token) yang diperoleh di luar alur MSAL.js. Ini memungkinkan aplikasi memanfaatkan enkripsi dan cache yang sama dengan yang digunakan MSAL.js untuk bukti kepemilikan token akses pada payload aplikasi itu sendiri.

Catatan: Kelas SignedHttpRequest ini ditujukan untuk kasus penggunaan tingkat lanjut di mana fungsionalitas bukti kepemilikan token akses bawaan tidak dapat digunakan. Contoh kasus penggunaan ini mencakup token akses Microsoft Entra ID atau MSA yang diperoleh di luar alur dari MSAL.js, serta token akses beban kerja.

Requirements

Untuk menggunakan SignedHttpRequest API, aplikasi harus:

1. Teruskan thumbprint kunci publik yang dikembalikan ke server yang mengeluarkan payload, dan server tersebut harus menyematkan thumbprint di dalam payload yang ditandatangani. Ini biasanya JWT yang ditandatangani.
2. Berikan payload dan thumbprint kunci publik asli ke MSAL.
3. Server sumber daya yang dituju oleh SHR harus memahami cara mendekode dan memvalidasi SHR serta muatan internalnya.

Parameter Microsoft Entra

Untuk token yang dikeluarkan oleh Microsoft Entra ID atau MSA, aplikasi harus menyertakan parameter kueri tambahan dalam permintaan token mereka:

• req_cnf : String yang dikodekan dalam Base64 yang menyertakan thumbprint kunci publik.
• token_type: Atur ke pop untuk menunjukkan ini adalah alur bukti kepemilikan.

Sample

Penggunaan Aplikasi

api.ts

import { SignedHttpRequest } from "@azure/msal-browser";

const resourceRequestUri = "https://api.contoso.com/my-api";
const resourceRequestMethod = "GET";

// Instantiate the token binding class. There may be configuration options possible in the future.
const signedHttpRequest = new SignedHttpRequest({
    resourceRequestUri, 
    resourceRequestMethod
});

// Use MSAL to generate and cache the keys, and return the public key thumbprint to the app.
const publicKeyThumbprint = await signedHttpRequest.generatePublicKeyThumbprint();

// Application acquires the payload to the be signed, providing the public key.
// This payload can be cached by the application, if desired.
const payload = await fetchAccessTokenWithoutMsal(publicKeyThumbprint);

// Application invokes custom business logic to acquire nonce (optional)
const nonce = await fetchServerNonce();

// Use MSAL to generate the pop token for the payload.
// This popToken should be used immediately and not be cached by the application.
const popToken = await signedHttpRequest.signRequest(payload, publicKeyThumbprint, { nonce });

// Initiate http request using pop token
const headers = new Headers();
headers.append("Authorization", `PoP ${popToken}`);

const options = {
    method: resourceRequestMethod,
    headers
};

const response = await fetch(resourceRequestUri, options);
const json = await response.json();

// Delete keys from cache
await signedHttpRequest.removeKeys(publicKeyThumbprint);

Server Nonces

SignedHttpRequest API akan mendukung kemampuan untuk mengatur klaim kustom di SHR, termasuk nonce, seperti melalui server nonce. Untuk memperoleh server nonce, lakukan langkah-langkah berikut:

1. Buatlah sidik jari kunci publik dan peroleh payload yang terikat.
2. Panggil SignedHttpRequest.signRequest() tanpa memberikan nilai nonce. Ini akan menghasilkan sebuah SHR dengan klaim nonce yang dihasilkan pustaka (saat ini guid).
3. Panggil permintaan jaringan menggunakan SHR ke server sumber daya.
4. Server sumber daya akan merespons dengan pesan kesalahan serta nilai nonce baru untuk digunakan dalam header.
5. Aplikasi akan perlu mengurai header ini dan memanggil kembali SignedHttpRequest.signRequest(), kali ini dengan meneruskan nilai nonce yang telah diurai (di masa mendatang, MSAL akan menyediakan fungsi pembantu untuk mengurai header).
6. Kirim ulang permintaan jaringan menggunakan SHR ke server sumber daya.