Share via

Tokens verkrijgen en in de cache opslaan met de Microsoft Authentication Library (MSAL)

  • Artikel

Met toegangstokens kunnen clients veilig web-API's aanroepen die worden beveiligd door Azure. Er zijn verschillende manieren om een token te verkrijgen met behulp van de Microsoft Authentication Library (MSAL). Sommige vereisen gebruikersinteractie via een webbrowser, terwijl andere gebruikersinteractie niet vereisen. Meestal is de methode die wordt gebruikt voor het verkrijgen van een token afhankelijk van of de toepassing een openbare clienttoepassing (desktop of mobiel) of een vertrouwelijke clienttoepassing (web-app, web-API of daemon-app) is.

MSAL slaat een token op nadat het is verkregen. Uw toepassingscode moet eerst proberen om een token op de achtergrond op te halen uit de cache voordat hij een token op een andere wijze probeert te verkrijgen.

U kunt de tokencache ook wissen door de accounts uit de cache te verwijderen. Hiermee wordt echter niet de sessiecookie verwijderd die zich in de browser bevindt.

Bereiken bij het verkrijgen van tokens

Machtigingsbereiken zijn de machtigingen die een web-API blootgeeft waar clienttoepassingen toegang tot kunnen aanvragen. Clienttoepassingen vragen de toestemming van de gebruiker voor de gewenste machtigingen wanneer ze authenticatieverzoeken indienen om tokens te verkrijgen voor toegang tot web-API's. MET MSAL kunt u tokens verkrijgen voor toegang tot API's van het Microsoft Identity Platform. Het v2.0-protocol maakt gebruik van scopes in plaats van resource in de aanvragen. Op basis van de configuratie van de web-API van de tokenversie die wordt geaccepteerd, retourneert het v2.0-eindpunt het toegangstoken naar MSAL.

Voor verschillende methoden voor het verkrijgen van tokens van MSAL is een scopes-parameter vereist. De scopes-parameter is een lijst met tekenreeksen die de gewenste machtigingen en de aangevraagde resources declareren. Bekende scopes zijn de Microsoft Graph machtigingen.

Scopes aanvragen voor een web-API

Wanneer uw toepassing een toegangstoken moet verzoeken met specifieke machtigingen voor een resource-API, geeft u de scopes door die de app-ID-URI van de API in de indeling <app ID URI>/<scope> bevatten.

Enkele voorbeelden van bereikwaarden voor verschillende resources:

  • Microsoft Graph API: https://graph.microsoft.com/User.Read
  • Aangepaste Web-API: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

De indeling van de bereikwaarde varieert afhankelijk van de resource (de API) die het toegangstoken ontvangt en de aud-claimwaarden die worden geaccepteerd.

Alleen voor Microsoft Graph kan het user.read-bereik worden toegewezen aan https://graph.microsoft.com/User.Read en kunnen beide bereikindelingen door elkaar worden gebruikt.

Bepaalde web-API's zoals de Azure Resource Manager-API (https://management.core.windows.net/) verwachten een schuine slash (/) in de doelgroepclaim (aud) van het toegangstoken. Geef in dit geval het bereik door als https://management.core.windows.net//user_impersonation, inclusief de dubbele slash (//).

Andere API's verwachten mogelijk dat er geen schema of host is opgenomen in de bereikwaarde en verwachten alleen de app-id (een GUID) en de bereiknaam, bijvoorbeeld:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Tip

Als de downstreamresource niet onder uw beheer valt, moet u mogelijk verschillende indelingen voor bereikwaarden (bijvoorbeeld met/zonder schema en host) proberen als u 401 of andere fouten ontvangt bij het doorgeven van het toegangstoken aan de resource.

Naarmate de functies van uw toepassing of de bijbehorende vereisten veranderen, kunt u indien nodig aanvullende machtigingen aanvragen met behulp van de bereikparameter. Met dergelijke dynamische toepassingsbereiken kunnen uw gebruikers stapsgewijs toestemming geven voor machtigingen.

U kunt bijvoorbeeld de gebruiker aanmelden, maar in eerste instantie de toegang tot resources weigeren. Later kunt u hem de mogelijkheid geven om zijn agenda te bekijken door het agendabereik aan te vragen via de methode token verkrijgen en toestemming van de gebruiker verkrijgen om dit te doen. Bijvoorbeeld door de scopes https://graph.microsoft.com/User.Read en https://graph.microsoft.com/Calendar.Read aan te vragen.

Tokens geruisloos verkrijgen (vanuit de cache)

MSAL onderhoudt een tokencache (of twee caches voor vertrouwelijke clienttoepassingen) en slaat een token op nadat het is verkregen. In veel gevallen zal een poging om stilletjes een token te verkrijgen resulteren in een ander token met meer scopes, gebaseerd op een token in de cache. Het is ook in staat om een token te vernieuwen wanneer het bijna verloopt (omdat de tokencache ook een vernieuwingstoken bevat).

De broncode van de toepassing moet eerst proberen om een token op de achtergrond op te halen uit de cache. Als de methode-aanroep een "gebruikersinterface vereist" fout of uitzondering retourneert, probeer dan op een andere manier een token te verkrijgen.

Er zijn twee stromen waarbij u niet op de achtergrond een token moet verkrijgen:

  • Clientreferentiestroom, die geen gebruikmaakt van de gebruikerstokencache, maar een toepassingstokencache. Deze methode zorgt ervoor dat de tokencache van de toepassing wordt gecontroleerd voordat een aanvraag naar de beveiligingstokenservice (STS) wordt verzonden.
  • Autorisatiecodestroom in webapps, waarbij een code wordt ingewisseld die de toepassing heeft verkregen doordat de gebruiker zich aanmeldt en toestemming geeft voor meer toestemmingen. Omdat een code en niet een account als parameter wordt doorgegeven, kan de methode niet in de cache zoeken voordat de code wordt ingewisseld, waardoor een aanroep naar de service wordt aangeroepen.

Voor webtoepassingen die gebruikmaken van de OpenID Connect-autorisatiecodestroom, is het aanbevolen patroon in de controllers:

  • Instantieer een vertrouwelijke clienttoepassing met een tokencache met aangepaste serialisatie.
  • Het token verkrijgen met behulp van de autorisatiecodestroom

Tokens verkrijgen

De methode voor het verkrijgen van een token is afhankelijk van of het een openbare client- of vertrouwelijke clienttoepassing is.

Openbare clienttoepassingen

In openbare clienttoepassingen (desktop en mobiel) kunt u het volgende doen:

  • Tokens interactief ophalen door de gebruiker zich aan te laten melden via een gebruikersinterface of pop-upvenster.
  • Haal een token op de achtergrond op voor de aangemelde gebruiker met geïntegreerde Windows-verificatie (IWA/Kerberos) als de bureaubladtoepassing wordt uitgevoerd op een Windows-computer die is gekoppeld aan een domein of Azure.
  • Haal een token op met een gebruikersnaam en wachtwoord in .NET Framework-bureaubladclienttoepassingen (niet aanbevolen). Gebruik geen gebruikersnaam/wachtwoord in vertrouwelijke clienttoepassingen.
  • Haal een token op via de apparaatcodestroom in toepassingen die worden uitgevoerd op apparaten die geen webbrowser hebben. De gebruiker krijgt een URL en een code. De gebruiker gaat vervolgens naar een webbrowser op een ander apparaat waar hij de code invoert en zich aanmeldt. Microsoft Entra ID verzendt vervolgens een token terug naar het apparaat zonder browser.

Vertrouwelijke clienttoepassingen

Voor vertrouwelijke clienttoepassingen (web-app, web-API of een daemon-app zoals een Windows-service), kunt u;

  • Tokens verkrijgen voor de toepassing zelf en niet voor een gebruiker, met behulp van de clientreferentiestroom. Deze techniek kan worden gebruikt voor het synchroniseren van hulpprogramma's of hulpprogramma's die gebruikers in het algemeen verwerken en niet voor een specifieke gebruiker.
  • Gebruik de on behalf of flow (OBO) voor een web-API om namens de gebruiker een API aan te roepen. De toepassing wordt geïdentificeerd met clientreferenties om een token te verkrijgen op basis van een gebruikersverklaring (bijvoorbeeld SAML of een JWT-token). Dit proces wordt gebruikt door toepassingen die toegang nodig hebben tot resources van een bepaalde gebruiker in service-naar-service communicatie. Tokens moeten worden opgeslagen in de cache op sessiebasis, niet op basis van een gebruiker.
  • Verkrijg tokens met behulp van de autorisatiecodestroom in web-apps nadat de gebruiker zich heeft aangemeld via de URL van de autorisatieaanvraag. OpenID Connect-applicaties maken doorgaans gebruik van dit mechanisme, waarmee de gebruiker zich kan aanmelden met behulp van OpenID Connect en vervolgens namens hem toegang kan krijgen tot web-API's. Tokens kunnen worden opgeslagen in de cache van een gebruiker of op sessiebasis. Als tokens in de cache op basis van een gebruiker worden opgeslagen, raden we u aan om de levensduur van de sessie te beperken, zodat Microsoft Entra ID regelmatig de status van het beleid voor voorwaardelijke toegang kan controleren.

Verificatieresultaten

Wanneer uw client een toegangstoken aanvraagt, retourneert Microsoft Entra-id ook een verificatieresultaat met metagegevens over het toegangstoken. Deze informatie omvat de verlooptijd van het toegangstoken en de scopes waarvoor het geldig is. Met deze gegevens kan uw app intelligente caching van toegangstokens uitvoeren zonder het toegangstoken zelf te parseren. Het verificatieresultaat wordt weergegeven:

  • Het toegangstoken voor de web-API voor toegang tot resources. Deze tekenreeks is meestal een met Base64 gecodeerde JWT, maar de client mag nooit in het toegangstoken kijken. De indeling blijft niet gegarandeerd stabiel en kan worden versleuteld voor de bron. Mensen die code schrijven die afhankelijk is van de inhoud van het toegangstoken op de client, is een van de meest voorkomende bronnen van fouten en onderbreking van clientlogica.
  • Het id-token voor de gebruiker (een JWT).
  • Het token verloopt, waarbij de datum/tijd wordt aangegeven waarop het token verloopt.
  • Het tenant-ID bevat de tenant waarin de gebruiker is gevonden. Voor gastgebruikers (Microsoft Entra B2B-scenario's) is de tenant-id de gasttenant, niet de unieke tenant. Wanneer het token wordt geleverd in de naam van een gebruiker, bevat het verificatieresultaat ook informatie over deze gebruiker. Voor vertrouwelijke clientstromen waarbij tokens worden aangevraagd zonder gebruiker voor de toepassing, is deze gebruikersinformatie null.
  • De toepassingsgebieden waarvoor het token is uitgegeven.
  • De unieke id voor de gebruiker.

(Geavanceerd) Toegang tot de tokens in de cache van de gebruiker in achtergrond-apps en -services

U kunt de implementatie van de tokencache van MSAL gebruiken om achtergrond-apps, API's en services toe te staan de toegangstokencache te gebruiken om te blijven handelen namens gebruikers die niet aanwezig zijn. Dit is vooral handig als de achtergrond-apps en -services namens de gebruiker moeten blijven werken nadat de gebruiker de front-end web-app heeft afgesloten.

Tegenwoordig gebruiken de meeste achtergrondprocessen toepassingsmachtigingen wanneer ze met de gegevens van een gebruiker moeten werken zonder dat deze gebruiker zelf aanwezig is om te verifiëren of opnieuw te verifiëren. Omdat toepassingsmachtigingen vaak beheerderstoestemming vereisen, waarvoor uitbreiding van bevoegdheden is vereist, is onnodige wrijving opgetreden omdat de ontwikkelaar niet van plan was om machtigingen te verkrijgen die de gebruiker oorspronkelijk heeft toegestaan voor de app.

Dit codevoorbeeld op GitHub laat zien hoe u deze onnodige wrijving kunt voorkomen door toegang te krijgen tot de tokencache van MSAL vanuit achtergrond-apps:

Toegang tot de tokencache van de aangemelde gebruiker voor achtergrond-apps, API's en services

Notitie

Wanneer tokens interactief worden opgehaald met verificatiebroker, voert de verificatiebroker eerst cachezoekacties uit en retourneert het token in de cache indien beschikbaar (GitHub-probleem - acquireToken maakt gebruik van caching).

Zie ook

Verschillende platforms die worden ondersteund door MSAL, bevatten aanvullende informatie over de cache van tokens in de documentatie voor de bibliotheek van dat platform. Voorbeeld: