Resources en bereiken

Microsoft identity platform maakt gebruik van een bereikgericht model voor toegang tot resources. Hier verwijst een resource naar elke toepassing die een ontvanger kan zijn van een toegangstoken (zoals MS Graph API of uw eigen web-API) en een bereik (ook wel 'machtiging' genoemd) verwijst naar elk aspect van een resource waaraan een toegangstoken rechten verleent.

Aanvragen voor toegangstokens in MSAL.js zijn bedoeld als per resource per scope. Dit betekent dat een toegangstoken dat is aangevraagd voor resource A met bereik scp1:

  • kan niet worden gebruikt voor toegang tot resource A met bereik scp2, en,
  • kan niet worden gebruikt om bron B van welk bereik dan ook te openen.

De beoogde ontvanger van een toegangstoken wordt vertegenwoordigd door de aud claim. Als de waarde voor de aud claim niet overeenkomt met de URI van de resource-APP-id, moet het token als ongeldig worden beschouwd. Op dezelfde manier worden de machtigingen die een toegangstoken verleent, vertegenwoordigd door de scp claim. Zie Toegangstokenclaims voor meer informatie.

Standaardbereiken

Standaard worden de scopes openid, profile en offline_access door MSAL.js aan elk verzoek toegevoegd. Deze machtigingen zijn nodig om een vernieuwingstoken en de id-tokenclaims te ontvangen die worden gebruikt om het accountobject met gebruikersgegevens te vullen.

Werken met meerdere resources

Wanneer u toegang hebt tot meerdere resources, start u een afzonderlijke tokenaanvraag voor elk:

// "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" ]
});

Houd er rekening mee dat u voor dezelfde resource meerdere machtigingen kunt aanvragen (bijvoorbeeld User.Read, User.Write en Calendar.Read voor MS Graph API).

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

Als u per ongeluk meerdere resources in uw tokenaanvraag doorgeeft, wordt het token dat u ontvangt alleen uitgegeven voor de eerste resource.

// 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" ]
});

In Microsoft Entra ID worden de scopes (machtigingen) die rechtstreeks voor de app-registratie zijn ingesteld, statische scopes genoemd. Andere bereiken die alleen in de code zijn gedefinieerd, worden dynamische bereiken genoemd. Dit heeft gevolgen voor de aanmeldingsmethoden (bijvoorbeeld loginPopup, loginRedirect) en acquireToken (bijvoorbeeldacquireTokenPopup, acquireTokenRedirect, acquireTokenSilent) van MSAL.js. Overweeg het volgende:

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

In het bovenstaande codefragment wordt de gebruiker gevraagd om toestemming zodra deze een id-token en een toegangstoken met het bereik User.Readverifieert en ontvangt. Als ze later om een toegangstokenUser.Readvragen, worden ze niet opnieuw om toestemming gevraagd (met andere woorden, ze kunnen een token op de achtergrond verkrijgen).

Aan de andere kant heeft de gebruiker in de authenticatiefase geen toestemming gegeven voor Mail.Read en zal daarom om toestemming worden gevraagd wanneer een toegangstoken voor de scope Mail.Read wordt aangevraagd. Het ontvangen token zal alle scopes bevatten waarvoor eerder toestemming is gegeven (voor die specifieke resource), vandaar de term incrementele toestemming.

Houd rekening met een iets ander geval:

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

In het bovenstaande codefragment ontvangt de gebruiker, ook al geeft die toestemming voor zowel de machtigingen User.Read als api://<myCustomApiClientId>/My.Scope, alleen een toegangstoken voor MS Graph API, in overeenstemming met het per resource per machtiging-principe. Omdat ze echter al toestemming hebben gegeven aan api://<myCustomApiClientId>/My.Scope, kunnen ze later alsnog stilzwijgend een Access Token voor die resource/scope verkrijgen.

In Microsoft Entra ID leeft toestemming na de levensduur van de toepassing. Dit betekent dat, wanneer u een toegangstoken voor een resource aanvraagt, alle bereiken waarvoor u eerder toestemming hebt gegeven voor die resource, worden geretourneerd, ongeacht het bereik dat op dat moment is aangevraagd. Met andere woorden, als u toestemming geeft voor User.Read en Mail.Read vandaag en morgen een nieuw exemplaar van uw toepassing uitvoert waarin alleen een toegangstokenUser.Read wordt aangevraagd, ontvangt u nog steeds een token dat is uitgegeven voor zowel alsUser.ReadMail.Read. Raadpleeg machtigingen en toestemming voor meer informatie.

  • Last updated on