Ressources et étendues

Plateforme d'identités Microsoft utilise un modèle centré sur l’étendue pour accéder aux ressources. Ici, une ressource fait référence à n’importe quelle application qui peut être destinataire d’un jeton d’accès (tel que MS API Graph ou votre propre API web), et une étendue (appelée « autorisation ») fait référence à n’importe quel aspect d’une ressource qu’un jeton d’accès accorde des droits.

Les requêtes de jeton d’accès dans MSAL.js sont conçues pour être propres à chaque ressource et à chaque étendue. Cela signifie qu’un jeton d’accès demandé pour la ressource A avec la portée scp1:

  • ne peut pas être utilisé pour accéder à la ressource A avec l'étendue scp2, et
  • ne peut pas être utilisé pour accéder à la ressource B d’une étendue quelconque.

Le destinataire prévu d’un jeton d’accès est représenté par la aud revendication ; si la valeur de la aud revendication ne correspond pas à l’URI d’ID d’application de ressource, le jeton doit être considéré comme non valide. De même, les autorisations accordées par un jeton d’accès sont représentées par la scp revendication. Pour plus d'informations, consultez Revendications de token d'accès.

Étendues par défaut

Par défaut, MSAL.js ajoutera les étendues openid, profile et offline_access à chaque requête. Ces étendues sont requises pour recevoir un token d'actualisation et les revendications de token d'ID utilisées pour renseigner l'objet de compte avec les informations de l'utilisateur.

Utilisation de plusieurs ressources

Lorsque vous devez accéder à plusieurs ressources, lancez une demande de jeton distincte pour chacune d’elles :

// "User.Read" stands as shorthand for "graph.microsoft.com/User.Read"
const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read" ]
});
const customApiToken = await msalInstance.acquireTokenSilent({
     scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
});

N’oubliez pas que vous pouvez demander plusieurs étendues pour la même ressource (par exempleUser.Read, User.Write et Calendar.Read pour MS API Graph).

const graphToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "User.Write", "Calendar.Read" ] // all MS Graph API scopes
});

Si vous transmettez par erreur plusieurs ressources dans votre demande de jeton, le jeton que vous recevrez sera émis uniquement pour la première ressource.

// you will only receive a token for MS GRAPH API's "User.Read" scope here
const myToken = await msalInstance.acquireTokenSilent({
     scopes: [ "User.Read", "api://<myCustomApiClientId>/My.Scope" ]
});

Dans Microsoft Entra ID, les étendues (autorisations) définies directement sur l’inscription de l’application sont appelées étendues statiques. Les autres étendues définies uniquement dans le code sont appelées étendues dynamiques. Cela a des implications sur les méthodes login (c.-à-d. loginPopup, loginRedirect) et acquireToken (c.-à-d. acquireTokenPopup, acquireTokenRedirect, acquireTokenSilent) de MSAL.js. Tenez compte des éléments suivants :

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail and fallback to an interactive method prompting a consent screen
 // after consent, the received token will be issued for "openid", "profile" ,"User.Read" and "Mail.Read" combined
 msalInstance.acquireTokenSilent(tokenRequest);

Dans l’extrait de code ci-dessus, l’utilisateur est invité à donner son consentement une fois qu’il s’authentifie et reçoit un jeton d’ID et un jeton d’accès avec l’étendue User.Read. Plus tard, s’ils demandent un jeton d’accès pour User.Read, ils ne seront plus demandés de consentement (en d’autres termes, ils peuvent acquérir un jeton en mode silencieux).

En revanche, l’utilisateur n’a pas consenti à Mail.Read lors de la phase d’authentification ; par conséquent, il lui sera demandé de donner son consentement lors de la demande d’un jeton d’accès pour la portée Mail.Read. Le jeton reçu contiendra toutes les étendues précédemment consentées (pour cette ressource spécifique), d’où le terme consentement incrémentiel.

Considérez un cas légèrement différent :

 const loginRequest = {
      scopes: [ "openid", "profile", "User.Read" ],
      extraScopesToConsent: [ "api://<myCustomApiClientId>/My.Scope"]
 };
 const tokenRequest = {
      scopes: [ "Mail.Read" ]
 };
 const anotherTokenRequest = {
      scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
 }
 // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
 msalInstance.loginPopup(loginRequest);
 // will fail with InteractionRequiredError due to lack of consent for "Mail.Read" scope. You should fallback to an interactive method in this case.
 msalInstance.acquireTokenSilent(tokenRequest);
 // will succeed and return an Access Token with scope "api://<myCustomApiClientId>/My.Scope"
 msalInstance.acquireTokenSilent(anotherTokenRequest);

Dans l’extrait de code ci-dessus, même si l’utilisateur consent à la fois User.Read et api://<myCustomApiClientId>/My.Scope aux étendues, il reçoit uniquement un jeton d’accès pour MS API Graph, conformément au principe par ressource par étendue. Toutefois, étant donné qu’ils ont déjà consenti à api://<myCustomApiClientId>/My.Scope, ils peuvent acquérir un jeton d’accès pour cette ressource/étendue silencieusement ultérieurement .

Dans Microsoft Entra ID, le consentement vit au-delà de la durée de vie de l’application. Cela signifie que, lorsque vous demandez un jeton d’accès pour une ressource, toutes les étendues que vous avez précédemment consentées à cette ressource seront retournées, quelle que soit l’étendue demandée au moment. En d’autres termes, si vous donnez aujourd’hui votre consentement à User.Read et Mail.Read et exécutez demain une nouvelle instance de votre application en demandant un jeton d’accès pour User.Read uniquement, vous recevrez toujours un jeton émis pour tous deuxUser.Read et Mail.Read. Pour plus d’informations, reportez-vous aux autorisations et au consentement.

  • Last updated on