Varför uppdatera till Microsoft-identitetsplattformen (v2.0)?

  • Artikel

När du utvecklar ett nytt program är det viktigt att känna till skillnaderna mellan slutpunkterna Microsofts identitetsplattform (v2.0) och Azure Active Directory (v1.0). Den här artikeln beskriver de största skillnaderna mellan slutpunkterna och vissa befintliga begränsningar för Microsofts identitetsplattform.

Vem kan logga in

Vem kan logga in med v1.0- och v2.0-slutpunkter

  • V1.0-slutpunkten tillåter endast arbets- och skolkonton att logga in på ditt program (Azure AD)
  • Med Microsofts identitetsplattform slutpunkt kan arbets- och skolkonton från Microsoft Entra-ID och personliga Microsoft-konton (MSA), till exempel hotmail.com, outlook.com och msn.com, logga in.
  • Båda slutpunkterna accepterar också inloggningar för gästanvändare av en Microsoft Entra katalog för program som konfigurerats som en enda klientorganisation eller för program med flera klientorganisationer som konfigurerats för att peka på den klientspecifika slutpunkten (https://login.microsoftonline.com/{TenantId_or_Name}).

Med Microsofts identitetsplattform slutpunkt kan du skriva appar som accepterar inloggningar från personliga Microsoft-konton samt arbets- och skolkonton. Detta ger dig möjlighet att skriva din app helt kontoagnostisk. Om din app till exempel anropar Microsoft Graph blir vissa ytterligare funktioner och data tillgängliga för arbetskonton, till exempel deras SharePoint-webbplatser eller katalogdata. Men för många åtgärder, till exempel Läsa en användares e-post, kan samma kod komma åt e-postmeddelandet för både personliga konton och arbets- och skolkonton.

För Microsofts identitetsplattform slutpunkt kan du använda Microsoft Authentication Library (MSAL) för att få åtkomst till konsument-, utbildnings- och företagsvärldarna. Slutpunkten Azure AD v1.0 accepterar endast inloggningar från arbets- och skolkonton.

Appar som använder Azure AD v1.0-slutpunkten måste ange nödvändiga OAuth 2.0-behörigheter i förväg, till exempel:

Exempel som visar användargränssnittet för behörighetsregistrering

Behörigheterna som anges direkt för programregistreringen är statiska. Även om statiska behörigheter för appen som definierats i Azure Portal hålla koden enkel och enkel, ger den några möjliga problem för utvecklare:

  • Appen måste begära alla behörigheter som den skulle behöva vid användarens första inloggning. Detta kan leda till en lång lista med behörigheter som avråder slutanvändarna från att godkänna appens åtkomst vid den första inloggningen.

  • Appen måste känna till alla resurser som den någonsin skulle komma åt i förväg. Det var svårt att skapa appar som kunde komma åt ett godtyckligt antal resurser.

Med Microsofts identitetsplattform slutpunkten kan du ignorera de statiska behörigheter som definierats i appregistreringsinformationen i Azure Portal och begära behörigheter stegvis i stället, vilket innebär att du behöver en minimal uppsättning behörigheter i förväg och växer mer över tid när kunden använder ytterligare appfunktioner. För att göra det kan du ange de omfång som din app behöver när som helst genom att inkludera de nya omfången i parametern scope när du begär en åtkomsttoken – utan att behöva fördefiniera dem i programregistreringsinformationen. Om användaren ännu inte har samtyckt till nya omfång som lagts till i begäran uppmanas de endast att godkänna de nya behörigheterna. Mer information finns i behörigheter, medgivande och omfång.

Om du tillåter att en app begär behörigheter dynamiskt via parametern scope får utvecklarna fullständig kontroll över användarens upplevelse. Du kan också läsa in ditt medgivande i förväg och be om alla behörigheter i en första auktoriseringsbegäran. Om din app kräver ett stort antal behörigheter kan du samla in dessa behörigheter från användaren stegvis när de försöker använda vissa funktioner i appen över tid.

Admin medgivande som görs för en organisations räkning kräver fortfarande de statiska behörigheter som registrerats för appen, så du bör ange dessa behörigheter för appar i appregistreringsportalen om du behöver en administratör för att ge medgivande åt hela organisationen. Detta minskar de cykler som krävs av organisationsadministratören för att konfigurera programmet.

Omfång, inte resurser

För appar som använder v1.0-slutpunkten kan en app fungera som en resurs eller som mottagare av token. En resurs kan definiera ett antal omfång eller oAuth2Permissions som den förstår, så att klientappar kan begära token från den resursen för en viss uppsättning omfång. Tänk på Microsoft Graph API som ett exempel på en resurs:

  • Resursidentifierare eller AppID URI: https://graph.microsoft.com/
  • Omfång, eller oAuth2Permissions: Directory.Read, Directory.Writeoch så vidare.

Detta gäller för Microsofts identitetsplattform slutpunkten. En app kan fortfarande fungera som en resurs, definiera omfång och identifieras av en URI. Klientappar kan fortfarande begära åtkomst till dessa omfång. Hur en klient begär dessa behörigheter har dock ändrats.

För v1.0-slutpunkten kan en OAuth 2.0-auktorisera begäran till Azure AD ha sett ut så här:

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

Här anger resursparametern vilken resurs klientappen begär auktorisering för. Azure AD beräknade de behörigheter som krävs av appen baserat på statisk konfiguration i Azure Portal och utfärdade token därefter.

För program som använder Microsofts identitetsplattform slutpunkt ser samma OAuth 2.0-auktoriseringsbegäran ut så här:

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
...

Här anger omfångsparametern vilken resurs och vilka behörigheter appen begär auktorisering för. Den önskade resursen finns fortfarande i begäran – den ingår i vart och ett av värdena för omfångsparametern. Om du använder omfångsparametern på det här sättet kan Microsofts identitetsplattform slutpunkten vara mer kompatibel med OAuth 2.0-specifikationen och anpassas närmare till vanliga branschpraxis. Det gör det också möjligt för appar att göra inkrementellt medgivande – endast begära behörigheter när programmet kräver dem i stället för i förväg.

Välkända omfång

Offlineåtkomst

Appar som använder Microsofts identitetsplattform slutpunkt kan kräva användning av en ny välkänd behörighet för appar – omfångetoffline_access. Alla appar måste begära den här behörigheten om de behöver åtkomst till resurser för en användares räkning under en längre tid, även om användaren kanske inte aktivt använder appen. Omfånget offline_access visas för användaren i dialogrutor för medgivande som Åtkomst till dina data när som helst, vilket användaren måste godkänna. Om du begär behörigheten offline_access kan webbappen ta emot OAuth 2.0-refresh_tokens från Microsofts identitetsplattform slutpunkten. Uppdateringstoken är långlivade och kan bytas ut mot nya OAuth 2.0-åtkomsttoken för längre åtkomstperioder.

Om din app inte begär omfånget får den offline_access inte uppdateringstoken. Det innebär att när du löser in en auktoriseringskod i OAuth 2.0-auktoriseringskodflödet får du bara tillbaka en åtkomsttoken från /token slutpunkten. Åtkomsttoken förblir giltig under en kort tidsperiod (vanligtvis en timme), men upphör så småningom att gälla. Då måste appen omdirigera användaren tillbaka till /authorize slutpunkten för att hämta en ny auktoriseringskod. Under den här omdirigeringen kanske användaren behöver eller kanske inte behöver ange sina autentiseringsuppgifter igen eller återställa till behörigheter, beroende på apptyp.

Mer information om OAuth 2.0, refresh_tokensoch access_tokens, finns i Microsofts identitetsplattform-protokollreferensen.

OpenID, profil och e-post

Historiskt sett skulle det mest grundläggande OpenID Connect-inloggningsflödet med Microsofts identitetsplattform ge mycket information om användaren i den resulterande id_token. Anspråken i en id_token kan innehålla användarens namn, önskat användarnamn, e-postadress, objekt-ID med mera.

Den information som omfånget openid ger din app åtkomst till är nu begränsad. Omfånget openid tillåter endast att din app loggar in användaren och får en appspecifik identifierare för användaren. Om du vill hämta personuppgifter om användaren i din app måste appen begära ytterligare behörigheter från användaren. Med två nya omfång, email och profile, kan du begära ytterligare behörigheter.

  • Omfånget email ger din app åtkomst till användarens primära e-postadress via anspråket email i id_token, förutsatt att användaren har en adresserbar e-postadress.
  • Omfånget profile ger din app åtkomst till all annan grundläggande information om användaren, till exempel deras namn, önskat användarnamn, objekt-ID och så vidare i id_token.

Med de här omfången kan du koda din app på ett minimalt sätt så att du bara kan be användaren om den uppsättning information som appen behöver för att utföra sitt jobb. Mer information om dessa omfång finns i Microsofts identitetsplattform omfångsreferens.

Tokenanspråk

den Microsofts identitetsplattform slutpunkten utfärdar en mindre uppsättning anspråk i sina token som standard för att hålla nyttolaster små. Om du har appar och tjänster som är beroende av ett visst anspråk i en v1.0-token som inte längre tillhandahålls som standard i en Microsofts identitetsplattform token kan du överväga att använda den valfria anspråksfunktionen för att inkludera det anspråket.

Viktigt

v1.0- och v2.0-token kan utfärdas av både v1.0- och v2.0-slutpunkterna! id_tokens alltid matcha den slutpunkt som de begärs från, och åtkomsttoken matchar alltid det format som förväntas av webb-API:et som klienten anropar med den token. Så om din app använder v2.0-slutpunkten för att hämta en token för att anropa Microsoft Graph, som förväntar sig v1.0-formatåtkomsttoken, får appen en token i v1.0-format.

Begränsningar

Det finns några begränsningar att känna till när du använder Microsofts identitetsplattform.

När du skapar program som integreras med Microsofts identitetsplattform måste du bestämma om Microsofts identitetsplattform slutpunkts- och autentiseringsprotokoll uppfyller dina behov. V1.0-slutpunkten och plattformen stöds fortfarande fullt ut och är i vissa avseenden mer funktionsrik än Microsofts identitetsplattform. Men Microsofts identitetsplattform medför betydande fördelar för utvecklare.

Här är en förenklad rekommendation för utvecklare nu:

  • Om du vill ha eller behöver stöd för personliga Microsoft-konton i ditt program eller om du skriver ett nytt program använder du Microsofts identitetsplattform. Men innan du gör det bör du se till att du förstår de begränsningar som beskrivs i den här artikeln.
  • Om du migrerar eller uppdaterar ett program som förlitar sig på SAML kan du inte använda Microsofts identitetsplattform. Läs i stället Azure AD v1.0-guiden.

Den Microsofts identitetsplattform slutpunkten utvecklas för att eliminera begränsningarna som anges här, så att du bara behöver använda Microsofts identitetsplattform slutpunkten. Under tiden använder du den här artikeln för att avgöra om Microsofts identitetsplattform slutpunkten är rätt för dig. Vi fortsätter att uppdatera den här artikeln så att den återspeglar det aktuella tillståndet för Microsofts identitetsplattform slutpunkt. Kom tillbaka för att utvärdera dina krav mot Microsofts identitetsplattform funktioner.

Begränsningar för appregistreringar

För varje app som du vill integrera med Microsofts identitetsplattform-slutpunkten kan du skapa en appregistrering i den nya Appregistreringar upplevelsen i Azure Portal. Befintliga Microsoft-kontoappar är inte kompatibla med portalen, men alla Microsoft Entra appar är det, oavsett var eller när de registrerades.

Appregistreringar som stöder arbets- och skolkonton och personliga konton har följande förbehåll:

  • Endast två apphemligheter tillåts per program-ID.
  • Ett program som inte har registrerats i en klientorganisation kan bara hanteras av det konto som registrerade det. Det kan inte delas med andra utvecklare. Detta är fallet för de flesta appar som har registrerats med ett personligt Microsoft-konto i appregistreringsportalen. Om du vill dela din appregistrering med flera utvecklare registrerar du programmet i en klientorganisation med hjälp av det nya Appregistreringar avsnittet i Azure Portal.
  • Det finns flera begränsningar för formatet på omdirigerings-URL:en som tillåts. Mer information om omdirigerings-URL finns i nästa avsnitt.

Begränsningar för omdirigerings-URL:er

Den senaste informationen om begränsningar för omdirigerings-URL:er för appar som är registrerade för Microsofts identitetsplattform finns i Begränsningar och begränsningar för omdirigerings-URI/svars-URL i Microsofts identitetsplattform dokumentationen.

Information om hur du registrerar en app för användning med Microsofts identitetsplattform finns i Registrera en app med den nya Appregistreringar upplevelsen.

Begränsningar för bibliotek och SDK:er

Biblioteksstödet för Microsofts identitetsplattform slutpunkten är för närvarande begränsat. Om du vill använda Microsofts identitetsplattform slutpunkten i ett produktionsprogram har du följande alternativ:

  • Om du skapar ett webbprogram kan du på ett säkert sätt använda det allmänt tillgängliga mellanprogrammet på serversidan för att utföra inloggning och tokenverifiering. Dessa inkluderar OWIN OpenID Connect-mellanprogrammet för ASP.NET och Node.js Passport-plugin-programmet. Kodexempel som använder Microsoft-mellanprogram finns i avsnittet Microsofts identitetsplattform komma igång.
  • Om du skapar ett skrivbords- eller mobilprogram kan du använda något av Microsofts autentiseringsbibliotek (MSAL). Dessa bibliotek är allmänt tillgängliga eller i en förhandsversion som stöds av produktion, så det är säkert att använda dem i produktionsprogram. Du kan läsa mer om villkoren för förhandsversionen och de tillgängliga biblioteken i referensen för autentiseringsbibliotek.
  • För plattformar som inte omfattas av Microsoft-bibliotek kan du integrera med Microsofts identitetsplattform slutpunkt genom att skicka och ta emot protokollmeddelanden direkt i programkoden. OpenID Connect- och OAuth-protokollen dokumenteras uttryckligen för att hjälpa dig att göra en sådan integrering.
  • Slutligen kan du använda OpenID Connect- och OAuth-bibliotek med öppen källkod för att integrera med Microsofts identitetsplattform slutpunkten. Den Microsofts identitetsplattform slutpunkten ska vara kompatibel med många protokollbibliotek med öppen källkod utan ändringar. Tillgängligheten för den här typen av bibliotek varierar beroende på språk och plattform. OpenID Connect- och OAuth 2.0-webbplatserna har en lista över populära implementeringar. Mer information finns i Microsofts identitetsplattform- och autentiseringsbibliotek samt listan över klientbibliotek och exempel med öppen källkod som har testats med Microsofts identitetsplattform slutpunkten.
  • Som referens .well-known är https://login.microsoftonline.com/common/v2.0/.well-known/openid-configurationslutpunkten för den Microsofts identitetsplattform gemensamma slutpunkten . Ersätt common med ditt klientorganisations-ID för att hämta data som är specifika för din klientorganisation.

Protokolländringar

Den Microsofts identitetsplattform slutpunkten stöder inte SAML eller WS-Federation. Den stöder endast OpenID Connect och OAuth 2.0. De viktigaste ändringarna i OAuth 2.0-protokollen från v1.0-slutpunkten är:

  • Anspråket email returneras om ett valfritt anspråk har konfigurerats eller omfång=e-post har angetts i begäran.
  • Parametern scope stöds nu i stället för parametern resource .
  • Många svar har ändrats för att göra dem mer kompatibla med OAuth 2.0-specifikationen, till exempel korrekt returnering expires_in som en int i stället för en sträng.

Mer information om omfånget för protokollfunktioner som stöds i Microsofts identitetsplattform-slutpunkten finns i OpenID Connect- och OAuth 2.0-protokollreferens.

SAML-användning

Om du har använt Active Directory Authentication Library (ADAL) i Windows-program kan du ha utnyttjat Windows-integrerad autentisering, som använder SAML-försäkran (Security Assertion Markup Language). Med det här beviljandet kan användare av federerade Microsoft Entra klienter tyst autentisera med sin lokal Active Directory instans utan att ange autentiseringsuppgifter. Även om SAML fortfarande är ett protokoll som stöds för användning med företagsanvändare är v2.0-slutpunkten endast för användning med OAuth 2.0-program.

Nästa steg

Läs mer i Microsofts identitetsplattform dokumentationen.