Ondersteuning voor verificatiestromen in MSAL

  • Artikel

De Microsoft Authentication Library (MSAL) ondersteunt verschillende toekenningen van autorisatie en de bijbehorende tokenstromen voor gebruik in uiteenlopende soorten toepassingen en scenario's.

Verificatiestroom Schakelt in Ondersteunde soorten toepassingen
Autorisatiecode Gebruikersaanmelding en toegang tot web-API's namens de gebruiker. Desktop
Mobiel
App met één pagina (SPA) (vereist PKCE)
Web
Clientreferenties Toegang tot web-API's door de identiteit te gebruiken van de toepassing zelf. Doorgaans gebruikt voor server-naar-servercommunicatie en geautomatiseerde scripts waarvoor geen gebruikersinteractie is vereist. Daemon
Apparaatcode Gebruikersaanmelding en toegang tot web-API's namens de gebruiker op apparaten met beperkte invoer, zoals smart-tv's en IoT-apparaten. Ook gebruikt door opdrachtregelinterface-toepassingen (CLI-toepassingen). Desktop, mobiel
Impliciete toekenning Gebruikersaanmelding en toegang tot web-API's namens de gebruiker. De impliciete toekenningsstroom wordt niet meer aanbevolen - gebruik in plaats daarvan de autorisatiecode met PKCE. * App met één pagina (SPA)
* Web
Namens (OBO) Toegang vanuit een upstream web-API naar een downstream web-API namens de gebruiker. De identiteit en gedelegeerde machtigingen van de gebruiker worden via de upstream-API doorgegeven aan de downstream-API. Web-API
Gebruikersnaam/wachtwoord (ROPC) Hiermee kan een toepassing gebruikers aanmelden door hun wachtwoord rechtstreeks te verwerken. De ROPC-stroom wordt NIET aanbevolen. Desktop, mobiel
Geïntegreerde Windows-verificatie (IWA) Hiermee kunnen toepassingen op domeincomputers of aan Microsoft Entra gekoppelde computers op de achtergrond een token verkrijgen (zonder tussenkomst van de gebruikersinterface). Desktop, mobiel

Tokens

Uw toepassing kan een of meer verificatiestromen gebruiken. Elke stroom gebruikt bepaalde tokentypen voor verificatie, autorisatie en het vernieuwen van tokens, en sommige gebruiken ook een autorisatiecode.

Verificatiestroom of actie Vereist Id-token Toegangstoken Token vernieuwen Autorisatiecode
Stroom voor autorisatiecode Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken Verificatiestroom werkt voor vernieuwingstoken Autorisatiecode werkt
Clientreferenties Verificatiestroom werkt voor toegangstoken (alleen voor apps)
Stroom voor apparaatcode Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken Verificatiestroom werkt voor vernieuwingstoken
Impliciete stroom Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken
Namens-stroom toegangstoken Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken Verificatiestroom werkt voor vernieuwingstoken
Gebruikersnaam/wachtwoord (ROPC) gebruikersnaam, wachtwoord Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken Verificatiestroom werkt voor vernieuwingstoken
Hybride OIDC-stroom Verificatiestroom werkt voor id-token Autorisatiecode werkt
Inwisseling van token vernieuwen vernieuwingstoken Verificatiestroom werkt voor id-token Verificatiestroom werkt voor toegangstoken Verificatiestroom werkt voor vernieuwingstoken

Interactieve en niet-interactieve verificatie

Verschillende van deze stromen ondersteunen interactieve en niet-interactieve tokenverwerving.

  • Interactief: de autorisatieserver kan de gebruiker vragen gegevens in te voeren. Als u zich bijvoorbeeld wilt aanmelden, meervoudige verificatie (MFA) wilt uitvoeren of toestemming wilt verlenen voor meer machtigingen voor toegang tot resources.
  • Niet-interactief (stil): de gebruiker wordt mogelijk niet om invoer gevraagd. Ook wel tokenverwerving op de achtergrond genoemd. De toepassing probeert een token op te halen via een methode waarin de autorisatieserver de gebruiker mogelijk niet vraagt gegevens in te voeren.

Uw MSAL-toepassing moet eerst proberen een token te verwerven op de achtergrond en pas terugvallen op de interactieve methode als de niet-interactieve poging mislukt. Raadpleeg Tokens verkrijgen en opslaan in cache met de Microsoft Authentication Library (MSAL) voor meer informatie over dit patroon.

Autorisatiecode

Het verlenen van de OAuth 2.0-autorisatiecode kan worden gebruikt door web-apps, apps met één pagina (toepassing met één pagina) en systeemeigen apps (mobiel en desktop) voor toegang tot beveiligde resources, zoals web-API's.

Wanneer gebruikers zich aanmelden bij webtoepassingen, ontvangt de toepassing een autorisatiecode. Die kan deze inwisselen voor een toegangstoken om web-API's aan te roepen.

In het volgende diagram ziet u de toepassing:

  1. Vraagt een autorisatiecode aan die is ingewisseld voor een toegangstoken
  2. Gebruikt het toegangstoken om een web-API aan te roepen, Microsoft Graph

Diagram van autorisatiecodestroom.

Beperkingen voor de autorisatiecode

  • Voor toepassingen met één pagina is Proof Key for Code Exchange (PKCE) vereist bij het gebruik van de stroom voor het verlenen van autorisatiecode. PKCE wordt ondersteund door MSAL.

  • Voor de OAuth 2.0-specificatie moet u een autorisatiecode gebruiken om slechts één keer een toegangstoken in te wisselen.

    Als u meerdere keren probeert een toegangstoken te verkrijgen met dezelfde autorisatiecode, wordt er een fout geretourneerd die lijkt op de volgende fout van het Microsoft Identity-platform. Sommige bibliotheken en frameworks vragen automatisch de autorisatiecode voor u aan en het handmatig aanvragen van een code in dergelijke gevallen leidt ook tot deze fout.

    AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

Clientreferenties

Met de OAuth 2.0-clientreferentiestroom hebt u toegang tot door het web gehoste resources met behulp van de identiteit van een toepassing. Dit type toekenning wordt meestal gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker. Deze typen toepassingen worden vaak daemons of serviceaccounts genoemd.

Met de stroom voor het verlenen van clientreferenties kan een webservice (een vertrouwelijke client) de eigen referenties gebruiken, in de plaats van een gebruiker te imiteren, om te verifiëren bij het aanroepen van een andere webservice. In dit scenario is de client doorgaans een webservice in de middelste laag, een daemon-service of een website. Voor een hoger zekerheidsniveau laat het Microsoft Identity-platform ook toe dat de aanroepende service een certificaat gebruikt als referentie (in plaats van een gedeeld geheim).

Toepassingsgeheimen

In het volgende diagram ziet u de toepassing:

  1. Hiermee verkrijgt u een token met behulp van referenties voor het toepassingsgeheim of wachtwoord
  2. Gebruikt het token om aanvragen van de resource te maken

Diagram van vertrouwelijke client met wachtwoord.

Certificaten

In het volgende diagram ziet u de toepassing:

  1. Hiermee verkrijgt u een token met behulp van certificaatreferenties
  2. Gebruikt het token om aanvragen van de resource te maken

Diagram van vertrouwelijke client met certificaat.

Deze clientreferenties moeten als volgt zijn:

  • Geregistreerd bij Microsoft Entra-id
  • Doorgegeven bij het maken van het vertrouwelijke clienttoepassingsobject in uw code

Beperkingen voor clientreferenties

De stroom voor vertrouwelijke clients wordt niet ondersteund op mobiele platforms zoals Android, iOS of UWP. Mobiele toepassingen worden beschouwd als openbare clienttoepassingen die de vertrouwelijkheid van hun referenties niet kunnen garanderen.

Apparaatcode

Met de OAuth 2.0-apparaatcodestroom kunnen gebruikers zich aanmelden bij ingevoerde apparaten, zoals slimme tv's, IoT-apparaten en printers. Voor interactieve verificatie met Microsoft Entra ID is een webbrowser vereist. Als het apparaat of besturingssysteem geen webbrowser biedt, kan de stroom voor apparaatcodes de gebruiker een ander apparaat laten gebruiken, zoals een computer of mobiele telefoon, om zich interactief aan te melden.

Door de stroom voor apparaatcodes te gebruiken, verkrijgt de toepassing tokens via een proces in twee stappen dat is ontworpen voor deze apparaten en besturingssystemen. Voorbeelden van dergelijke toepassingen zijn toepassingen die worden uitgevoerd op IoT-apparaten en opdrachtregelinterface (CLI)-hulpprogramma's.

In het volgende diagram ziet u het volgende:

  1. Wanneer de gebruiker moet worden geverifieerd, biedt de app een code. De gebruiker wordt dan gevraagd een ander apparaat te gebruiken, zoals een smartphone met internetverbinding, om een URL te bezoeken (bijvoorbeeld https://microsoft.com/devicelogin). De gebruiker wordt vervolgens gevraagd de code in te voeren en door te gaan via een normale verificatie-ervaring, waaronder toestemmingsprompts en meervoudige verificatie, indien nodig.
  2. Na een geslaagde verificatie ontvangt de opdrachtregel-app de vereiste tokens via een upstream-kanaal en gebruikt deze om de vereiste web-API-aanroepen uit te voeren.

Diagram van apparaatcodestroom.

Beperkingen voor de apparaatcode

  • De stroom voor apparaatcodes is alleen beschikbaar voor openbare clienttoepassingen.
  • Wanneer u een openbare clienttoepassing in MSAL initialiseert, gebruikt u een van deze instantie-indelingen:
    • Tenant: https://login.microsoftonline.com/{tenant}/, waar {tenant} bevindt zich de tenant-id of een domeinnaam die is gekoppeld aan de tenant.
    • Werk- en schoolaccounts: https://login.microsoftonline.com/organizations/.

Impliciete toekenning

De impliciete toekenningsstroom is vervangen door de autorisatiecodestroom door PKCE als voorkeursstroom en veiligere tokentoekenstroom voor toepassingen aan de clientzijde met één pagina (SPA's). Het wordt niet meer aanbevolen om de impliciete toekenningsstroom te gebruiken. Als u een toepassing met één pagina bouwt, gebruikt u in plaats daarvan de stroom voor autorisatiecodes met PKCE.

Web-apps met één pagina die zijn geschreven in JavaScript (inclusief frameworks zoals Angular, Vue.js of React.js), worden gedownload van de server en de bijhorende code wordt rechtstreeks in de browser uitgevoerd. Omdat hun code aan clientzijde wordt uitgevoerd in de browser en niet op een webserver, hebben deze verschillende beveiligingskenmerken dan traditionele webtoepassingen op de server. Vóór de beschikbaarheid van Proof Key for Code Exchange (PKCE) voor de stroom voor autorisatiecodes werd de stroom voor impliciete toekenning gebruikt door SPA's om de reactiesnelheid en efficiëntie te verbeteren bij het verkrijgen van toegangstokens.

Met de impliciete toekenningsstroom van OAuth 2.0 kan de app toegangstokens ophalen van het Microsoft Identity Platform zonder een exchange van referenties voor de back-endserver uit te voeren. Met de stroom voor impliciete toekenning kan een app zich aanmelden bij de gebruiker, een sessie onderhouden en tokens ophalen voor andere web-API's vanuit de JavaScript-code die is gedownload en uitgevoerd door de gebruikersagent (meestal een webbrowser).

Diagram van de stroom voor impliciete toekenning

Beperkingen voor impliciete toekenning

De stroom voor impliciete toekenning omvat geen toepassingsscenario's die platformoverschrijdende JavaScript-frameworks gebruiken, zoals Electron of React Native. Dergelijke platformoverschrijdende frameworks vereisen bijkomende mogelijkheden voor interactie met de systeemeigen desktop- en mobiele platforms waarop deze worden uitgevoerd.

De lengte van de tokens die via de impliciete stroommodus worden uitgegeven, is beperkt omdat ze worden geretourneerd naar de browser via een URL (waar response_modequery of fragment is). Sommige browsers beperken de lengte van de URL in de browserbalk en kunnen falen als deze te lang is. Deze impliciete stroomtokens bevatten dan ook géén claims voor groups of wids.

Namens (OBO)

De OAuth 2.0-stroom namens de verificatiestroom wordt gebruikt wanneer een toepassing een service of web-API aanroept die op zijn beurt een andere service of web-API moet aanroepen. Het idee is de gedelegeerde gebruikersidentiteit en machtigingen door te geven via de aanvraagketen. Om de service in de middelste laag geverifieerde aanvragen te laten uitvoeren naar de downstreamservice, moet deze namens de gebruiker een toegangstoken beveiligen vanuit het Microsoft Identity-platform.

In het volgende diagram ziet u het volgende:

  1. verkrijgt de toepassing een toegangstoken voor de web-API.
  2. Een client (een web-, desktop- of mobiele toepassing of een toepassing met één pagina) roept een beveiligde web-API aan, waarbij het toegangstoken wordt toegevoegd als bearer-token in de verificatieheader van de HTTP-aanvraag. De web-API verifieert de gebruiker.
  3. Wanneer de client de web-API aanroept, vraagt de web-API een ander token aan namens de gebruiker.
  4. De beveiligde web-API gebruikt dit token om een downstream-web-API aan te roepen namens de gebruiker. De web-API kan later ook tokens aanvragen voor andere downstream-API's (maar nog steeds namens dezelfde gebruiker).

Diagram van on-behalf-of-flow.

Gebruikersnaam/wachtwoord (ROPC)

Waarschuwing

De stroom voor wachtwoordreferenties van de eigenaar van de resource (ROPC) wordt NIET aanbevolen. ROPC vereist een hoge mate van vertrouwen en blootstelling van de referenties. Gebruik ROPC uitsluitend als het niet mogelijk is een veiligere stroom te gebruiken. Raadpleeg Wat is de oplossing voor het groeiende probleem van wachtwoorden? voor meer informatie.

Met de OAuth 2.0-referenties voor het wachtwoord van de resource-eigenaar (ROPC) kan een toepassing zich aanmelden bij de gebruiker door het wachtwoord rechtstreeks te verwerken. U kunt de stroom gebruikersnaam/wachtwoord gebruiken in uw desktoptoepassing om een token te verkrijgen op de achtergrond. Er is geen gebruikersinterface vereist tijdens het gebruik van de toepassing.

Sommige toepassingsscenario's zoals DevOps kunnen ROPC nuttig vinden. Maar u moet dit vermijden in elke toepassing waarin u een interactieve gebruikersinterface biedt voor de gebruikersaanmelding.

In het volgende diagram ziet u de toepassing:

  1. Hiermee verkrijgt u een token door de gebruikersnaam en het wachtwoord naar de id-provider te verzenden
  2. Roept een web-API aan met behulp van het token

Diagram van de gebruikersnaam/wachtwoordstroom.

Als u een token wilt verkrijgen op de achtergrond op Windows-computers die lid zijn van een domein, raden we u de geïntegreerde Windows-verificatie (IWA) aan in plaats van ROPC. Voor andere scenario's gebruikt u de stroom voor apparaatcodes.

Beperkingen voor ROPC

De volgende beperkingen zijn van toepassing op de toepassingen die de ROPC-stroom gebruiken:

  • Eenmalige aanmelding wordt niet ondersteund.
  • Meervoudige verificatie (MFA) wordt niet ondersteund.
    • Neem contact op met uw tenantbeheerder voordat u deze stroom gebruikt. MFA is een veelgebruikte functie.
  • Voorwaardelijke toegang wordt niet ondersteund.
  • ROPC werkt alleen voor werk- en schoolaccounts.
  • Persoonlijke Microsoft-accounts (MSA) worden niet ondersteund door ROPC.
  • ROPC wordt ondersteund in .NET Desktop- en ASP.NET Core-toepassingen.
  • ROPC wordt niet ondersteund in Universeel Windows-platform (UWP)-toepassingen.
  • ROPC in Azure AD B2C wordt alleen ondersteund voor lokale accounts.

Geïntegreerde Windows-verificatie (IWA)

MSAL ondersteunt geïntegreerde Windows-verificatie (IWA) voor desktop- en mobiele toepassingen die worden uitgevoerd op windows-computers die lid zijn van een domein of microsoft Entra. Door IWA te gebruiken, verkrijgen deze toepassingen een token op de achtergrond zonder tussenkomst van de gebruikersinterface.

In het volgende diagram ziet u de toepassing:

  1. Hiermee verkrijgt u een token met geïntegreerde Windows-verificatie
  2. Gebruikt het token om aanvragen van de resource te maken

Diagram van geïntegreerde Windows-verificatie.

Beperkingen voor IWA

Compatibiliteit

Geïntegreerde Windows-verificatie (IWA) is ingeschakeld voor .NET-desktop-, .NET- en Windows Universal Platform-apps.

IWA biedt alleen ondersteuning voor AD FS-federatieve gebruikers: gebruikers die zijn gemaakt in Active Directory en worden ondersteund door Microsoft Entra-id. Gebruikers die rechtstreeks in Microsoft Entra ID zijn gemaakt zonder Active Directory-backing (beheerde gebruikers) kunnen deze verificatiestroom niet gebruiken.

Meervoudige verificatie (MFA)

De niet-interactieve (stille) verificatie van IWA kan mislukken als MFA is ingeschakeld in de Microsoft Entra-tenant en er een MFA-uitdaging wordt uitgegeven door Microsoft Entra ID. Als IWA mislukt, moet u terugvallen op een interactieve verificatiemethode zoals eerder is beschreven.

Microsoft Entra ID maakt gebruik van AI om te bepalen wanneer tweeledige verificatie is vereist. De tweeledige verificatiemethode is doorgaans vereist wanneer een gebruiker zich aanmeldt vanuit een ander land/een andere regio, wanneer deze is verbonden met een bedrijfsnetwerk zonder een VPN te gebruiken en soms wanneer deze is verbonden via een VPN. Omdat de configuratie- en uitdagingsfrequentie van MFA mogelijk buiten uw beheer valt als ontwikkelaar, moet uw toepassing het mislukken van de tokenverzameling van IWA op de achtergrond probleemloos kunnen verwerken.

URI-beperkingen van de instantie

De instantie die is doorgegeven bij het bouwen van de openbare clienttoepassing, moet een van de volgende zijn:

  • https://login.microsoftonline.com/{tenant}/ - Deze instantie geeft een toepassing met één tenant aan waarvan de aanmeldingsdoelgroep is beperkt tot de gebruikers in de opgegeven Microsoft Entra-tenant. De waarde {tenant} kan de tenant-id zijn in het GUID-formulier of de domeinnaam die is gekoppeld aan de tenant.
  • https://login.microsoftonline.com/organizations/ - Deze instantie geeft een toepassing met meerdere tenants aan waarvan de aanmeldingsdoelgroep gebruikers is in een Microsoft Entra-tenant.

Autoriteitswaarden mogen /common of /consumers NIET bevatten, omdat persoonlijke Microsoft-accounts (MSA) niet worden ondersteund door IWA.

Toestemmingsvereisten

Omdat IWA een stroom is op de achtergrond:

  • Moet de gebruiker van uw toepassing eerder toestemming hebben gegeven om de toepassing te kunnen gebruiken.

    OF

  • moet de tenantbeheerder eerder toestemming hebben gegeven voor alle gebruikers in de tenant om de toepassing te kunnen gebruiken.

Om aan beide vereisten te voldoen, moet een van deze bewerkingen zijn voltooid:

  • U, als toepassingsontwikkelaar, hebt Toekenning geselecteerd voor uzelf in Azure Portal.
  • Een tenantbeheerder heeft Beheerderstoestemming verlenen/intrekken geselecteerd voor {tenantdomein} op het tabblad API-machtigingen van de app-registratie in Azure Portal. Raadpleeg Machtigingen toevoegen voor toegang tot uw web-API.
  • U hebt een manier opgegeven voor gebruikers om toestemming te geven voor de toepassing; zie toestemming van de gebruiker.
  • U hebt een manier opgegeven voor de tenantbeheerder om toestemming te geven voor de toepassing; zie Beheer istrator-toestemming.

Raadpleeg Machtigingen en toestemming voor meer informatie over toestemming.

Volgende stap

Meer informatie over het verkrijgen en opslaan van caching van de tokens die in deze stromen worden gebruikt:

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