Requête HTTP signée

MSAL.js fournit la classe SignedHttpRequest pour faciliter la création de requêtes HTTP signées (SHR) pour des charges utiles (par exemple, des jetons) obtenues hors bande, en dehors de MSAL.js. Cela permet aux applications de tirer parti du même chiffrement et de la même mise en cache qu’utilise MSAL.js pour la preuve de possession du jeton d’accès pour leurs propres données.

Remarque : La SignedHttpRequest classe est destinée aux cas d’usage avancés où la fonctionnalité de preuve de possession du jeton d’accès intégré ne peut pas être utilisée. Parmi ces cas d’usage figuraient des jetons d’accès Microsoft Entra ID ou MSA obtenus hors bande via MSAL.js, ainsi que des jetons d’accès de charge de travail.

Exigences

Pour utiliser l’API SignedHttpRequest , une application doit :

1. Transférez l’empreinte numérique de clé publique retournée au serveur qui émet la charge utile, et ce serveur doit incorporer l’empreinte numérique à l’intérieur de la charge utile signée. Il s’agit généralement d’un JWT signé.
2. Fournissez à MSAL la charge utile et l’empreinte numérique de la clé publique d’origine.
3. Le serveur de ressources pour lequel le SHR est destiné doit comprendre comment décoder et valider la charge utile SHR et interne.

paramètres de Microsoft Entra

Pour les jetons émis par Microsoft Entra ID ou MSA, les applications doivent inclure des paramètres de requête supplémentaires dans leurs demandes de jetons :

• req_cnf : chaîne encodée en base64, y compris l’empreinte numérique de la clé publique.
• token_type: Défini sur pop afin d’indiquer qu’il s’agit d’un flux de preuve de possession.

Sample

Utilisation de l’application

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

Nonces du serveur

L’API SignedHttpRequest prend en charge la possibilité de définir des revendications personnalisées dans le SHR, y compris la nonce, par exemple via un serveur nonce. Pour obtenir un nonce de serveur, procédez comme suit :

1. Générez l’empreinte de la clé publique et récupérez la charge utile associée.
2. Appelez SignedHttpRequest.signRequest() sans fournir de valeur de nonce. Ceci générera un SHR avec une réclamation nonce généré par une bibliothèque (actuellement un GUID).
3. Appelez la requête réseau à l’aide du SHR sur le serveur de ressources.
4. Le serveur de ressources répond avec une erreur et une nouvelle nonce valeur à utiliser dans un en-tête.
5. L’application doit analyser cet en-tête et réinvoke SignedHttpRequest.signRequest(), cette fois en passant la valeur analysée nonce (à l’avenir, MSAL fournit une fonction d’assistance pour analyser l’en-tête).
6. Réinvoke la requête réseau à l’aide du SHR sur le serveur de ressources.