Share via

Waarom bijwerken naar Microsoft Identity Platform (v2.0)?

  • Artikel

Bij het ontwikkelen van een nieuwe toepassing is het belangrijk om te weten wat de verschillen zijn tussen de eindpunten Microsoft identity platform (v2.0) en Azure Active Directory (v1.0). In dit artikel worden de belangrijkste verschillen tussen de eindpunten en enkele bestaande beperkingen voor Microsoft identity platform behandeld.

Wie kan zich aanmelden

Wie kan zich aanmelden met v1.0 en v2.0 eindpunten

  • Met het v1.0-eindpunt kunnen alleen werk- en schoolaccounts zich aanmelden bij uw toepassing (Azure AD)
  • Met het Microsoft identity platform-eindpunt kunnen werk- en schoolaccounts van Microsoft Entra-id en persoonlijke Microsoft-accounts (MSA), zoals hotmail.com, outlook.com en msn.com, zich aanmelden.
  • Beide eindpunten accepteren ook aanmeldingen van gastgebruikers van een Microsoft Entra directory voor toepassingen die zijn geconfigureerd als één tenant of voor toepassingen met meerdere tenants die zijn geconfigureerd om te verwijzen naar het tenantspecifieke eindpunt (https://login.microsoftonline.com/{TenantId_or_Name}).

Met het Microsoft identity platform-eindpunt kunt u apps schrijven die aanmeldingen accepteren van persoonlijke Microsoft-accounts en werk- en schoolaccounts. Dit biedt u de mogelijkheid om uw app volledig account-neutraal te schrijven. Als uw app bijvoorbeeld Microsoft Graph aanroept, zijn er extra functionaliteit en gegevens beschikbaar voor werkaccounts, zoals hun SharePoint-sites of mapgegevens. Maar voor veel acties, zoals het lezen van e-mail van een gebruiker, heeft dezelfde code toegang tot de e-mail voor zowel persoonlijke als werk- en schoolaccounts.

Voor Microsoft identity platform eindpunt kunt u de Microsoft Authentication Library (MSAL) gebruiken om toegang te krijgen tot de werelden van consumenten, onderwijs en ondernemingen. Het eindpunt Azure AD v1.0 accepteert alleen aanmeldingen van werk- en schoolaccounts.

Apps die het Azure AD v1.0-eindpunt gebruiken, zijn vereist om vooraf de vereiste OAuth 2.0-machtigingen op te geven, bijvoorbeeld:

Voorbeeld van de UI van toegangsmachtigingen

De machtigingen die rechtstreeks op de registratie van de toepassing zijn ingesteld, zijn statisch. Hoewel statische machtigingen van de app die in de Azure Portal de code mooi en eenvoudig houden, worden er enkele mogelijke problemen voor ontwikkelaars weergegeven:

  • De app moet alle machtigingen aanvragen die nodig zijn voor de eerste aanmelding van de gebruiker. Dit kan leiden tot een lange lijst met machtigingen waarmee eindgebruikers de toegang van de app bij de eerste aanmelding kunnen goedkeuren.

  • De app moet alle resources kennen die deze ooit eerder zou openen. Het was moeilijk om apps te maken die toegang hebben tot een willekeurig aantal resources.

Met het Microsoft identity platform-eindpunt kunt u de statische machtigingen negeren die zijn gedefinieerd in de app-registratiegegevens in de Azure Portal en machtigingen incrementeel aanvragen, wat betekent dat u vooraf een minimale set machtigingen hoeft te vragen en meer in de loop van de tijd toeneemt naarmate de klant aanvullende app-functies gebruikt. Hiervoor kunt u op elk gewenst moment de bereiken opgeven die uw app nodig heeft door de nieuwe bereiken in de scope-parameter op te slaan bij het aanvragen van een toegangstoken, zonder dat u ze vooraf hoeft te definiëren in de registratiegegevens van de toepassing. Als de gebruiker nog geen toestemming heeft gegeven voor nieuwe bereiken die aan de aanvraag zijn toegevoegd, wordt de gebruiker gevraagd alleen toestemming te geven voor de nieuwe machtigingen. Zie machtigingen, toestemming en bereiken voor meer informatie.

Het toestaan van een app om machtigingen dynamisch aan te vragen via de scope-parameter biedt ontwikkelaars volledige controle over de gebruikerservaring. U kunt uw toestemmingservaring ook vooraf laden en vragen om alle machtigingen in één eerste autorisatieaanvraag. Als voor uw app een groot aantal machtigingen is vereist, kunt u deze machtigingen van de gebruiker incrementeel verzamelen wanneer ze bepaalde functies van de app in de loop van de tijd proberen te gebruiken.

Beheerderstoestemming namens een organisatie vereist nog steeds de statische machtigingen die zijn geregistreerd voor de app, dus moet u deze machtigingen instellen voor apps in de app-registratieportal als u een beheerder nodig hebt om namens de hele organisatie toestemming te geven. Dit vermindert de cycli die de organisatiebeheerder nodig heeft om de toepassing in te stellen.

Bereiken, niet resources

Voor apps die het v1.0-eindpunt gebruiken, kan een app zich gedragen als een resource of een ontvanger van tokens. Een resource kan een aantal bereiken of oAuth2Permissions definiëren die het begrijpt, zodat client-apps tokens van die resource kunnen aanvragen voor een bepaalde set bereiken. Beschouw de Microsoft Graph API als voorbeeld van een resource:

  • Resource-id, of AppID URI: https://graph.microsoft.com/
  • Bereiken, of oAuth2Permissions: Directory.Read, Directory.Write, enzovoort.

Dit geldt voor het Microsoft identity platform-eindpunt. Een app kan zich nog steeds gedragen als een resource, bereiken definiëren en worden geïdentificeerd door een URI. Client-apps kunnen nog steeds toegang tot deze bereiken aanvragen. De manier waarop een client deze machtigingen aanvraagt, is echter gewijzigd.

Voor het v1.0-eindpunt heeft een OAuth 2.0-autorisatieaanvraag voor Azure AD er mogelijk als volgt uitziet:

GET https://login.microsoftonline.com/common/oauth2/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&resource=https://graph.microsoft.com/
...

Hier geeft de resourceparameter aan welke resource de client-app autorisatie aanvraagt. Azure AD berekende de machtigingen die door de app zijn vereist op basis van statische configuratie in de Azure Portal en dienovereenkomstig uitgegeven tokens.

Voor toepassingen die het Microsoft identity platform-eindpunt gebruiken, ziet dezelfde OAuth 2.0-autorisatieaanvraag er als volgt uit:

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&scope=https://graph.microsoft.com/directory.read%20https://graph.microsoft.com/directory.write
...

Hier geeft de bereikparameter aan voor welke resource en machtigingen de app autorisatie aanvraagt. De gewenste resource is nog steeds aanwezig in de aanvraag. Deze is opgenomen in elk van de waarden van de bereikparameter. Door de bereikparameter op deze manier te gebruiken, kan het Microsoft identity platform-eindpunt beter voldoen aan de OAuth 2.0-specificatie en wordt het beter afgestemd op algemene brancheprocedures. Het stelt apps ook in staat om incrementele toestemming te geven. U vraagt alleen machtigingen aan wanneer de toepassing deze nodig heeft in plaats van vooraf.

Bekende bereiken

Offline toegang

Voor apps die het Microsoft identity platform-eindpunt gebruiken, is mogelijk het gebruik van een nieuwe bekende machtiging voor apps vereist: het offline_access bereik. Alle apps moeten deze machtiging aanvragen als ze namens een gebruiker gedurende een langere periode toegang moeten krijgen tot resources, zelfs wanneer de gebruiker de app mogelijk niet actief gebruikt. Het offline_access bereik wordt weergegeven voor de gebruiker in toestemmingsdialoogvensters als Toegang tot uw gegevens op elk gewenst moment, waar de gebruiker mee moet akkoord gaan. Als u de offline_access machtiging aanvraagt, kan uw web-app OAuth 2.0-refresh_tokens ontvangen van het Microsoft identity platform-eindpunt. Vernieuwingstokens zijn langdurig en kunnen worden uitgewisseld voor nieuwe OAuth 2.0-toegangstokens voor langere toegangsperioden.

Als uw app het bereik niet aanvraagt offline_access, ontvangt deze geen vernieuwingstokens. Dus wanneer u een autorisatiecode inwisselt in de OAuth 2.0-autorisatiecodestroom, ontvangt u alleen een toegangstoken van het /token-eindpunt. Dat toegangstoken blijft gedurende een korte periode geldig (meestal één uur), maar verloopt uiteindelijk. Op dat moment moet uw app de gebruiker omleiden naar het /authorize eindpunt om een nieuwe autorisatiecode op te halen. Tijdens deze omleiding, afhankelijk van het type app, moet de gebruiker mogelijk referenties invoeren of opnieuw toestemming geven voor machtigingen.

Raadpleeg de naslaginformatie over het Microsoft identity platform protocol voor meer informatie over OAuth 2.0, refresh_tokens en access_tokens.

OpenID, profiel en e-mail

Historisch gezien biedt de meest eenvoudige OpenID Connect-aanmeldingsstroom met Microsoft identity platform veel informatie over de gebruiker in de resulterende id_token. De claims in een id_token kunnen de naam van de gebruiker, de gewenste gebruikersnaam, het e-mailadres, de object-id en meer bevatten.

De informatie waartoe het openid bereik toegang biedt tot uw app, is nu beperkt. Met openid het bereik kan uw app zich alleen aanmelden bij de gebruiker en een app-specifieke id voor de gebruiker ontvangen. Als u persoonlijke gegevens over de gebruiker in uw app wilt ophalen, moet uw app aanvullende machtigingen van de gebruiker aanvragen. Met twee nieuwe bereiken email en profilekunt u aanvullende machtigingen aanvragen.

  • Met email het bereik heeft uw app toegang tot het primaire e-mailadres van de gebruiker via de email claim in de id_token, ervan uitgaande dat de gebruiker een adresseerbaar e-mailadres heeft.
  • Het profile bereik biedt uw app toegang tot alle andere basisinformatie over de gebruiker, zoals hun naam, voorkeursnaam, object-id, enzovoort, in de id_token.

Met deze bereiken kunt u uw app coderen op minimale openbaarmakingsmode, zodat u de gebruiker alleen kunt vragen om de set informatie die uw app nodig heeft om de taak ervan uit te voeren. Zie de naslaginformatie over Microsoft identity platform bereik voor meer informatie over deze bereiken.

Tokenclaims

Het Microsoft identity platform eindpunt geeft standaard een kleinere set claims in de tokens uit om nettoladingen klein te houden. Als u apps en services hebt die afhankelijk zijn van een bepaalde claim in een v1.0-token dat niet meer standaard wordt geleverd in een Microsoft identity platform token, kunt u overwegen de optionele claimfunctie te gebruiken om die claim op te nemen.

Belangrijk

v1.0- en v2.0-tokens kunnen worden uitgegeven door zowel de v1.0- als v2.0-eindpunten! id_tokens komen altijd overeen met het eindpunt waarvoor ze worden aangevraagd en toegangstokens komen altijd overeen met de indeling die wordt verwacht door de Web-API die uw client aanroept met dat token. Dus als uw app gebruikmaakt van het v2.0-eindpunt om een token op te halen om Microsoft Graph aan te roepen, waarin toegangstokens in v1.0-indeling worden verwacht, ontvangt uw app een token in de v1.0-indeling.

Beperkingen

Er zijn enkele beperkingen om rekening mee te houden bij het gebruik van Microsoft identity platform.

Wanneer u toepassingen bouwt die zijn geïntegreerd met de Microsoft identity platform, moet u bepalen of het Microsoft identity platform-eindpunt- en verificatieprotocollen aan uw behoeften voldoen. Het v1.0-eindpunt en -platform worden nog steeds volledig ondersteund en bevatten in sommige opzichten meer functies dan Microsoft identity platform. Microsoft identity platform introduceert echter aanzienlijke voordelen voor ontwikkelaars.

Hier volgt nu een vereenvoudigde aanbeveling voor ontwikkelaars:

  • Als u persoonlijke Microsoft-accounts in uw toepassing wilt ondersteunen of als u een nieuwe toepassing wilt schrijven, gebruikt u Microsoft identity platform. Maar voordat u dit doet, moet u de beperkingen begrijpen die in dit artikel worden besproken.
  • Als u een toepassing migreert of bijwerkt die afhankelijk is van SAML, kunt u Microsoft identity platform niet gebruiken. Raadpleeg in plaats daarvan de handleiding Azure AD v1.0.

Het Microsoft identity platform-eindpunt zal zich ontwikkelen om de hier vermelde beperkingen te elimineren, zodat u het Microsoft identity platform-eindpunt alleen hoeft te gebruiken. Gebruik dit artikel ondertussen om te bepalen of het Microsoft identity platform eindpunt geschikt is voor u. We blijven dit artikel bijwerken om de huidige status van het Microsoft identity platform-eindpunt weer te geven. Kom terug om uw vereisten opnieuw te beoordelen op basis van Microsoft identity platform mogelijkheden.

Beperkingen voor app-registraties

Voor elke app die u wilt integreren met het Microsoft identity platform-eindpunt, kunt u een app-registratie maken in de nieuwe App-registraties ervaring in de Azure Portal. Bestaande Microsoft-account-apps zijn niet compatibel met de portal, maar alle Microsoft Entra apps zijn dat wel, ongeacht waar of wanneer ze zijn geregistreerd.

App-registraties die ondersteuning bieden voor werk- en schoolaccounts en persoonlijke accounts, hebben de volgende opmerkingen:

  • Er zijn slechts twee app-geheimen toegestaan per toepassings-id.
  • Een toepassing die niet is geregistreerd in een tenant, kan alleen worden beheerd door het account dat deze heeft geregistreerd. Het kan niet worden gedeeld met andere ontwikkelaars. Dit is het geval voor de meeste apps die zijn geregistreerd met een persoonlijk Microsoft-account in de portal voor app-registratie. Als u uw app-registratie met meerdere ontwikkelaars wilt delen, registreert u de toepassing in een tenant met behulp van de nieuwe sectie App-registraties van de Azure Portal.
  • Er zijn verschillende beperkingen voor de indeling van de omleidings-URL die is toegestaan. Zie de volgende sectie voor meer informatie over deze logboekregistratie.

Beperkingen voor omleidings-URL's

Zie Omleidings-URI-/antwoord-URL-beperkingen in de documentatie van Microsoft identity platform voor de meest recente informatie over beperkingen voor omleidings-URL's voor apps die zijn geregistreerd voor Microsoft identity platform.

Zie Een app registreren met behulp van de nieuwe App-registraties-ervaring voor meer informatie over het registreren van een app voor gebruik met Microsoft identity platform.

Beperkingen voor bibliotheken en SDK's

Momenteel is bibliotheekondersteuning voor het Microsoft identity platform-eindpunt beperkt. Als u het Microsoft identity platform-eindpunt in een productietoepassing wilt gebruiken, hebt u de volgende opties:

  • Als u een webtoepassing bouwt, kunt u de algemeen beschikbare middleware aan de serverzijde veilig gebruiken om aanmelding en tokenvalidatie uit te voeren. Deze omvatten de OWIN OpenID Connect-middleware voor ASP.NET en de Node.js Passport-invoegtoepassing. Zie de sectie Microsoft identity platform - aan de slag voor codevoorbeelden die gebruikmaken van Microsoft Middleware.
  • Als u een desktop- of mobiele toepassing bouwt, kunt u een van de Microsoft Authentication Libraries (MSAL) gebruiken. Deze bibliotheken zijn algemeen beschikbaar of in een door productie ondersteunde preview, dus het is veilig om ze te gebruiken in productietoepassingen. U kunt meer lezen over de voorwaarden van de preview en de beschikbare bibliotheken in de naslaginformatie over verificatiebibliotheken.
  • Voor platforms die niet worden gedekt door Microsoft-bibliotheken, kunt u integreren met het Microsoft identity platform-eindpunt door rechtstreeks protocolberichten in uw toepassingscode te verzenden en te ontvangen. De OpenID Connect- en OAuth-protocollen worden expliciet gedocumenteerd om u te helpen bij het uitvoeren van een dergelijke integratie.
  • Ten slotte kunt u opensource OpenID Connect- en OAuth-bibliotheken gebruiken om te integreren met het Microsoft identity platform-eindpunt. Het Microsoft identity platform-eindpunt moet zonder wijzigingen compatibel zijn met veel opensource-protocolbibliotheken. De beschikbaarheid van dit soort bibliotheken verschilt per taal en platform. De OpenID Connect - en OAuth 2.0-websites onderhouden een lijst met populaire implementaties. Zie Microsoft identity platform- en verificatiebibliotheken en de lijst met opensource-clientbibliotheken en voorbeelden die zijn getest met het Microsoft identity platform-eindpunt voor meer informatie.
  • Ter referentie is .well-known het https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration eindpunt voor het Microsoft identity platform gemeenschappelijk eindpunt. Vervang common door uw tenant-id om gegevens op te halen die specifiek zijn voor uw tenant.

Protocolwijzigingen

Het Microsoft identity platform-eindpunt biedt geen ondersteuning voor SAML of WS-Federation. Het biedt alleen ondersteuning voor OpenID Connect en OAuth 2.0. De belangrijke wijzigingen in de OAuth 2.0-protocollen van het v1.0-eindpunt zijn:

  • De email claim wordt geretourneerd als een optionele claim is geconfigureerd of scope=email is opgegeven in de aanvraag.
  • De scope parameter wordt nu ondersteund in plaats van de resource parameter.
  • Veel antwoorden zijn gewijzigd om ze compatibeler te maken met de OAuth 2.0-specificatie, bijvoorbeeld correct expires_in retourneren als een int in plaats van een tekenreeks.

Zie openID Connect en OAuth 2.0-protocolreferenties voor een beter begrip van het bereik van protocolfunctionaliteit die wordt ondersteund in het Microsoft identity platform-eindpunt.

SAML-gebruik

Als u Active Directory Authentication Library (ADAL) hebt gebruikt in Windows-toepassingen, hebt u mogelijk gebruikgemaakt van geïntegreerde Windows-verificatie, waarbij gebruik wordt gemaakt van de SAML-assertietoekenning (Security Assertion Markup Language). Met deze toekenning kunnen gebruikers van federatieve Microsoft Entra-tenants zich op de achtergrond verifiëren met hun on-premises Active Directory-exemplaar zonder referenties in te voeren. Hoewel SAML nog steeds een ondersteund protocol is voor gebruik met zakelijke gebruikers, is het v2.0-eindpunt alleen bedoeld voor gebruik met OAuth 2.0-toepassingen.

Volgende stappen

Meer informatie vindt u in de documentatie over het Microsoft Identity Platform.