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

Bereiken zijn de machtigingen waartoe een web-API toegang kan aanvragen door clienttoepassingen. Clienttoepassingen vragen de toestemming van de gebruiker voor deze bereiken bij het indienen van verificatieaanvragen voor toegang tot de 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 bereiken 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 bereiken zijn de Microsoft Graph-machtigingen.

Bereiken voor een web-API configureren

Wanneer uw toepassing een toegangstoken moet aanvragen met specifieke machtigingen voor een resource-API, geeft u de bereiken 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://11111111-1111-1111-1111-111111111111/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:

11111111-1111-1111-1111-111111111111/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 bereiken kunnen uw gebruikers incrementele toestemming geven voor bereiken.

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 bereiken https://graph.microsoft.com/User.Read en https://graph.microsoft.com/Calendar.Read aan te vragen.

Tokens op de achtergrond 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 krijgt een token op de achtergrond een ander token met meer bereiken op basis van 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 fout of uitzondering voor de gebruikersinterface retourneert, probeert u een token op een andere manier 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 web-apps, omdat deze een code inwisselt die de toepassing heeft verkregen door zich aan te melden bij de gebruiker en toestemming te geven voor meer bereiken. 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-Verbinding maken 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 met de browser minder.

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-stroom (OBO) voor een web-API om een API aan te roepen namens de gebruiker. De toepassing wordt geïdentificeerd met clientreferenties om een token te verkrijgen op basis van een gebruikersverklaring (bijvoorbeeld SAML of een JWT-token). Deze stroom wordt gebruikt door toepassingen die toegang nodig hebben tot resources van een bepaalde gebruiker in service-naar-service-aanroepen. 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 Verbinding maken toepassing maakt doorgaans gebruik van dit mechanisme, waarmee de gebruiker zich kan aanmelden met behulp van OpenID Verbinding maken en vervolgens namens de gebruiker toegang krijgt 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 bereiken 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 resource. 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.
  • De 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 bereiken 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

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: