OpenID-Anslut på Microsofts identitetsplattform

  • Artikel

OpenID Anslut (OIDC) utökar OAuth 2.0-auktoriseringsprotokollet för användning som ytterligare ett autentiseringsprotokoll. Du kan använda OIDC för att aktivera enkel inloggning (SSO) mellan dina OAuth-aktiverade program med hjälp av en säkerhetstoken som kallas för en ID-token.

Den fullständiga specifikationen för OIDC finns på OpenID Foundations webbplats på OpenID Anslut Core 1.0-specifikationen.

Protokollflöde: Logga in

Följande diagram visar det grundläggande OpenID-Anslut inloggningsflödet. Stegen i flödet beskrivs mer detaljerat i senare avsnitt i artikeln.

Swim-lane diagram showing the OpenID Connect protocol's sign-in flow.

Aktivera ID-token

ID-token som introducerades av OpenID Anslut utfärdas av auktoriseringsservern, Microsofts identitetsplattform, när klientprogrammet begär en under användarautentiseringen. Med ID-token kan ett klientprogram verifiera användarens identitet och hämta annan information (anspråk) om dem.

ID-token utfärdas inte som standard för ett program som registrerats med Microsofts identitetsplattform. ID-token för ett program aktiveras med någon av följande metoder:

  1. Logga in på administrationscentret för Microsoft Entra.
  2. Bläddra till Identitetsprogram>> Appregistreringar>< vår programautentisering.>>
  3. Under Plattformskonfigurationer väljer du Lägg till en plattform.
  4. I fönstret som öppnas väljer du lämplig plattform för ditt program. Välj till exempel Webb för ett webbprogram.
  5. Under Omdirigerings-URI:er lägger du till omdirigerings-URI:n för ditt program. Exempel: https://localhost:8080/
  6. Under Implicit beviljande och hybridflöden markerar du kryssrutan ID-token (används för implicita flöden och hybridflöden).

Eller:

  1. Välj Identitetsprogram>> Appregistreringar>< din programmanifest.>>
  2. Ange oauth2AllowIdTokenImplicitFlow till true i appregistreringens programmanifest.

Om ID-token inte är aktiverade för din app och en begärs returnerar Microsofts identitetsplattform ett unsupported_response fel som liknar:

Det angivna värdet för indataparametern "response_type" tillåts inte för den här klienten. Förväntat värde är "kod".

Att begära en ID-token genom att ange en response_type av id_token förklaras i Skicka inloggningsbegäran senare i artikeln.

Hämta OpenID-konfigurationsdokumentet

OpenID-leverantörer som Microsofts identitetsplattform tillhandahålla ett OpenID-providerkonfigurationsdokument vid en offentligt tillgänglig slutpunkt som innehåller providerns OIDC-slutpunkter, anspråk som stöds och andra metadata. Klientprogram kan använda metadata för att identifiera url:er som ska användas för autentisering och autentiseringstjänstens offentliga signeringsnycklar.

Autentiseringsbibliotek är de vanligaste konsumenterna av OpenID-konfigurationsdokumentet, som de använder för identifiering av autentiserings-URL:er, leverantörens offentliga signeringsnycklar och andra tjänstmetadata. Om ett autentiseringsbibliotek används i din app behöver du förmodligen inte handkoda begäranden till och svar från openID-konfigurationsdokumentets slutpunkt.

Hitta appens OpenID-konfigurationsdokument-URI

Varje appregistrering i Microsoft Entra-ID tillhandahålls en offentligt tillgänglig slutpunkt som hanterar dess OpenID-konfigurationsdokument. För att fastställa URI:n för konfigurationsdokumentets slutpunkt för din app lägger du till den välkända OpenID-konfigurationssökvägen till appregistreringens utfärdar-URL.

  • Välkänd dokumentsökväg för konfiguration: /.well-known/openid-configuration
  • Utfärdar-URL: https://login.microsoftonline.com/{tenant}/v2.0

Värdet för {tenant} varierar beroende på programmets inloggningspublik enligt följande tabell. Utfärdarens URL varierar också beroende på molninstans.

Värde beskrivning
common Användare med både ett personligt Microsoft-konto och ett arbets- eller skolkonto från Microsoft Entra-ID kan logga in på programmet.
organizations Endast användare med arbets- eller skolkonton från Microsoft Entra-ID kan logga in på programmet.
consumers Endast användare med ett personligt Microsoft-konto kan logga in på programmet.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller contoso.onmicrosoft.com Endast användare från en specifik Microsoft Entra-klientorganisation (katalogmedlemmar med ett arbets- eller skolkonto eller kataloggäster med ett personligt Microsoft-konto) kan logga in på programmet.

Värdet kan vara domännamnet för Microsoft Entra-klientorganisationen eller klientorganisations-ID:t i GUID-format. Du kan också använda konsumentklientens GUID, 9188040d-6c67-4c5b-b112-36a304b66dad, i stället för consumers.

Dricks

Observera att när du använder common eller consumers utfärdare för personliga Microsoft-konton måste det förbrukande resursprogrammet konfigureras för att stödja en sådan typ av konton i enlighet med signInAudience.

Om du vill hitta OIDC-konfigurationsdokumentet i administrationscentret för Microsoft Entra loggar du in på administrationscentret för Microsoft Entra och sedan:

  1. Bläddra till Identitetsprogram>> Appregistreringar>< dår programslutpunkter.>>
  2. Leta upp URI:n under OpenID Anslut metadatadokument.

Exempelbegäran

Följande begäran hämtar OpenID-konfigurationsmetadata från utfärdarens common OpenID-konfigurationsdokumentslutpunkt i det offentliga Azure-molnet:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Dricks

Prova! Om du vill se OpenID-konfigurationsdokumentet common för ett programs utfärdare går du till https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.

Exempelsvar

Konfigurationsmetadata returneras i JSON-format enligt följande exempel (trunkerade för korthet). Metadata som returneras i JSON-svaret beskrivs i detalj i OpenID Anslut 1.0-identifieringsspecifikationen.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Skicka inloggningsbegäran

Om du vill autentisera en användare och begära en ID-token för användning i ditt program dirigerar du användarens agent till Microsofts identitetsplattform/auktorisera slutpunkten. Begäran liknar den första delen av OAuth 2.0-auktoriseringskodflödet , men med dessa distinktioner:

  • Inkludera omfånget openid i parametern scope .
  • Ange id_token i parametern response_type .
  • Inkludera parametern nonce .

Exempel på inloggningsbegäran (radbrytningar ingår endast för läsbarhet):

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910
Parameter Villkor beskrivning
tenant Obligatoriskt Du kan använda {tenant} värdet i sökvägen till begäran för att styra vem som kan logga in på programmet. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i grunderna för protokoll. För gästscenarier där du signerar en användare från en klientorganisation till en annan klientorganisation måste du ange klientidentifieraren för att logga in dem korrekt i resursklientorganisationen.
client_id Obligatoriskt Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app.
response_type Obligatoriskt Måste inkluderas id_token för OpenID Anslut inloggning.
redirect_uri Rekommenderat Omdirigerings-URI:n för din app, där autentiseringssvar kan skickas och tas emot av din app. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i portalen, förutom att den måste vara URL-kodad. Om den inte finns väljer slutpunkten en som registrerats redirect_uri slumpmässigt för att skicka tillbaka användaren till.
scope Obligatoriskt En blankstegsavgränsad lista med omfång. För OpenID-Anslut måste den innehålla omfånget openid, som översätts till behörigheten Logga in dig i användargränssnittet för medgivande. Du kan också inkludera andra omfång i den här begäran om att begära medgivande.
nonce Obligatoriskt Ett värde som genereras och skickas av din app i dess begäran om en ID-token. Samma nonce värde ingår i den ID-token som returneras till din app av Microsofts identitetsplattform. För att minimera tokenreprisattacker bör appen kontrollera att nonce värdet i ID-token är samma värde som det som skickades när token begärdes. Värdet är vanligtvis en unik, slumpmässig sträng.
response_mode Rekommenderat Anger vilken metod som ska användas för att skicka tillbaka den resulterande auktoriseringskoden till din app. Det kan vara form_post eller fragment. För webbprogram rekommenderar vi att du använder response_mode=form_post, för att säkerställa den säkraste överföringen av token till ditt program.
state Rekommenderat Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll. Ett slumpmässigt genererat unikt värde används vanligtvis för att förhindra förfalskningsattacker mellan webbplatser. Tillståndet används också för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn som användaren var på.
prompt Valfritt Anger vilken typ av användarinteraktion som krävs. De enda giltiga värdena just nu är login, none, consentoch select_account. Anspråket prompt=login tvingar användaren att ange sina autentiseringsuppgifter för den begäran, vilket negerar enkel inloggning. Parametern prompt=none är motsatsen och bör paras ihop med en login_hint för att ange vilken användare som måste vara inloggad. Dessa parametrar säkerställer att användaren inte visas med någon interaktiv fråga alls. Om begäran inte kan slutföras tyst via enkel inloggning returnerar Microsofts identitetsplattform ett fel. Orsaker inkluderar ingen inloggad användare, den tipsade användaren är inte inloggad eller flera användare är inloggade men inget tips angavs. Anspråket prompt=consent utlöser dialogrutan OAuth-medgivande när användaren har loggat in. I dialogrutan uppmanas användaren att bevilja behörigheter till appen. select_account Slutligen visar användaren en kontoväljare som negerar tyst enkel inloggning men låter användaren välja vilket konto de tänker logga in med, utan att kräva autentiseringsuppgifter. Du kan inte använda både login_hint och select_account.
login_hint Valfritt Du kan använda den här parametern för att fylla i fältet användarnamn och e-postadress på inloggningssidan för användaren, om du känner till användarnamnet i förväg. Ofta använder appar den här parametern under omautentiseringen, efter att redan ha extraherat det valfria anspråket login_hint från en tidigare inloggning.
domain_hint Valfritt Sfären för användaren i en federerad katalog. Detta hoppar över den e-postbaserade identifieringsprocessen som användaren går igenom på inloggningssidan för en något mer effektiviserad användarupplevelse. För klienter som federeras via en lokal katalog som AD FS resulterar detta ofta i en sömlös inloggning på grund av den befintliga inloggningssessionen.

Nu uppmanas användaren att ange sina autentiseringsuppgifter och slutföra autentiseringen. Microsofts identitetsplattform verifierar att användaren har samtyckt till de behörigheter som anges i scope frågeparametern. Om användaren inte har samtyckt till någon av dessa behörigheter uppmanar Microsofts identitetsplattform användaren att samtycka till de behörigheter som krävs. Du kan läsa mer om behörigheter, medgivande och appar för flera klientorganisationer.

När användaren har autentiserat och gett sitt medgivande returnerar Microsofts identitetsplattform ett svar till din app vid den angivna omdirigerings-URI:n med hjälp av den metod som anges i parameternresponse_mode.

Lyckat svar

Ett lyckat svar när du använder response_mode=form_post liknar:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parameter Description
id_token ID-token som appen begärde. Du kan använda parametern id_token för att verifiera användarens identitet och starta en session med användaren. Mer information om ID-token och deras innehåll finns i referensen för ID-token.
state Om en state parameter ingår i begäran bör samma värde visas i svaret. Appen bör kontrollera att tillståndsvärdena i begäran och svaret är identiska.

Felsvar

Felsvar kan också skickas till omdirigerings-URI:n så att appen kan hantera dem, till exempel:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parameter Description
error En felkodssträng som du kan använda för att klassificera typer av fel som inträffar och för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa dig att identifiera rotorsaken till ett autentiseringsfel.

Felkoder för auktoriseringsslutpunktsfel

I följande tabell beskrivs felkoder som kan returneras i parametern error för felsvaret:

Felkod beskrivning Klientåtgärd
invalid_request Protokollfel som en nödvändig parameter saknas. Åtgärda och skicka begäran igen. Det här utvecklingsfelet bör fångas under programtestningen.
unauthorized_client Klientprogrammet kan inte begära en auktoriseringskod. Det här felet kan inträffa när klientprogrammet inte är registrerat i Microsoft Entra-ID eller inte läggs till i användarens Microsoft Entra-klientorganisation. Programmet kan uppmana användaren att installera programmet och lägga till det i Microsoft Entra-ID.
access_denied Resursägaren nekade medgivande. Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren samtycker.
unsupported_response_type Auktoriseringsservern stöder inte svarstypen i begäran. Åtgärda och skicka begäran igen. Det här utvecklingsfelet bör fångas under programtestningen.
server_error Servern påträffade ett oväntat fel. Försök igen med begäran. Dessa fel kan bero på tillfälliga villkor. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt fel.
temporarily_unavailable Servern är tillfälligt för upptagen för att hantera begäran. Försök igen med begäran. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt villkor.
invalid_resource Målresursen är ogiltig eftersom den inte finns, Microsoft Entra-ID:t kan inte hitta den eller så har den konfigurerats felaktigt. Det här felet anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren med instruktioner för att installera programmet och lägga till det i Microsoft Entra-ID.

Verifiera ID-token

Att ta emot en ID-token i din app kanske inte alltid räcker för att fullständigt autentisera användaren. Du kan också behöva verifiera ID-tokens signatur och verifiera dess anspråk enligt appens krav. Precis som alla OpenID-providers är Microsofts identitetsplattform ID-token JSON-webbtoken (JWT) signerade med hjälp av kryptering med offentliga nycklar.

Webbappar och webb-API:er som använder ID-token för auktorisering måste verifiera dem eftersom sådana program får åtkomst till data. Andra typer av program kanske inte drar nytta av validering av ID-token. Inbyggda appar och ensidesappar (SPA) drar till exempel sällan nytta av validering av ID-token eftersom en entitet med fysisk åtkomst till enheten eller webbläsaren potentiellt kan kringgå valideringen.

Två exempel på förbikoppling av tokenverifiering är:

  • Tillhandahålla falska token eller nycklar genom att ändra nätverkstrafik till enheten
  • Felsöka programmet och stega över valideringslogik under programkörningen.

Om du validerar ID-token i ditt program rekommenderar vi att du inte gör det manuellt. Använd i stället ett tokenverifieringsbibliotek för att parsa och verifiera token. Tokenvalideringsbibliotek är tillgängliga för de flesta utvecklingsspråk, ramverk och plattformar.

Vad du ska verifiera i en ID-token

Förutom att verifiera ID-tokens signatur bör du verifiera flera av dess anspråk enligt beskrivningen i Validera en ID-token. Se även Viktig information om signering av nyckel-rollover.

Flera andra valideringar är vanliga och varierar beroende på programscenario, inklusive:

  • Se till att användaren/organisationen har registrerat sig för appen.
  • Se till att användaren har rätt auktorisering/behörigheter
  • En viss autentiseringsstyrka har säkerställts, till exempel multifaktorautentisering.

När du har verifierat ID-token kan du starta en session med användaren och använda informationen i tokens anspråk för appanpassning, visning eller lagring av deras data.

Protokolldiagram: Förvärv av åtkomsttoken

Många program behöver inte bara logga in på en användare, utan även komma åt en skyddad resurs som ett webb-API för användarens räkning. Det här scenariot kombinerar OpenID-Anslut för att hämta en ID-token för autentisering av användaren och OAuth 2.0 för att hämta en åtkomsttoken för en skyddad resurs.

Det fullständiga OpenID-Anslut inloggnings- och tokeninsamlingsflödet ser ut ungefär så här:

OpenID Connect protocol: Token acquisition

Hämta en åtkomsttoken för UserInfo-slutpunkten

Förutom ID-token görs även den autentiserade användarens information tillgänglig på OIDC UserInfo-slutpunkten.

Om du vill hämta en åtkomsttoken för OIDC UserInfo-slutpunkten ändrar du inloggningsbegäran enligt beskrivningen här:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Du kan använda auktoriseringskodflödet, enhetskodflödet eller en uppdateringstoken response_type=token i stället för för att hämta en åtkomsttoken för din app.

Lyckat tokensvar

Ett lyckat svar från att använda response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Svarsparametrar betyder samma sak oavsett vilket flöde som används för att hämta dem.

Parameter Description
access_token Den token som ska användas för att anropa UserInfo-slutpunkten.
token_type Alltid "Bearer"
expires_in Hur lång tid tills åtkomsttoken upphör att gälla, i sekunder.
scope Behörigheterna som beviljats för åtkomsttoken. Eftersom UserInfo-slutpunkten finns på Microsoft Graph är det möjligt scope att innehålla andra som tidigare beviljats programmet (till exempel User.Read).
id_token ID-token som appen begärde. Du kan använda ID-token för att verifiera användarens identitet och starta en session med användaren. Du hittar mer information om ID-token och deras innehåll i ID-tokenreferensen.
state Om en tillståndsparameter ingår i begäran bör samma värde visas i svaret. Appen bör kontrollera att tillståndsvärdena i begäran och svaret är identiska.

Varning

Försök inte verifiera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i koden. Token för Microsoft-tjänster kan använda ett särskilt format som inte verifieras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Läs token är ett användbart felsöknings- och inlärningsverktyg, men använd inte beroenden för detta i koden eller anta detaljer om token som inte är för ett API som du kontrollerar.

Felsvar

Felsvar kan också skickas till omdirigerings-URI:n så att appen kan hantera dem på rätt sätt:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication
Parameter Description
error En felkodssträng som du kan använda för att klassificera typer av fel som inträffar och för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa dig att identifiera rotorsaken till ett autentiseringsfel.

En beskrivning av möjliga felkoder och rekommenderade klientsvar finns i Felkoder för auktoriseringsslutpunktsfel.

När du har en auktoriseringskod och en ID-token kan du logga in användaren och få åtkomsttoken för deras räkning. Om du vill logga in användaren måste du verifiera ID-token enligt beskrivningen i verifieringstoken. Om du vill hämta åtkomsttoken följer du stegen som beskrivs i dokumentationen för OAuth-kodflöde.

Anropa UserInfo-slutpunkten

Granska UserInfo-dokumentationen för att se hur du anropar UserInfo-slutpunkten med den här token.

Skicka en utloggningsbegäran

Om du vill logga ut en användare utför du båda dessa åtgärder:

  • Omdirigera användarens användaragent till Microsofts identitetsplattform utloggnings-URI
  • Rensa appens cookies eller avsluta användarens session i ditt program.

Om du inte utför någon av åtgärderna kan användaren förbli autentiserad och uppmanas inte att logga in nästa gång de använder din app.

Omdirigera användaragenten till det end_session_endpoint som visas i konfigurationsdokumentet för OpenID Anslut. Stöder end_session_endpoint både HTTP GET- och POST-begäranden.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter Villkor beskrivning
post_logout_redirect_uri Rekommenderat Url:en som användaren omdirigeras till efter att ha loggat ut. Om parametern inte ingår visas ett allmänt meddelande som genereras av Microsofts identitetsplattform. Den här URL:en måste matcha en av de omdirigerings-URI:er som registrerats för ditt program i appregistreringsportalen.
logout_hint Valfritt Aktiverar utloggning utan att användaren uppmanas att välja ett konto. Om du vill använda logout_hintaktiverar du det valfria anspråket login_hinti klientprogrammet och använder värdet för det login_hint valfria anspråket logout_hint som parameter. Använd inte UPN eller telefonnummer som värde för parametern logout_hint .

Kommentar

Efter lyckad utloggning anges de aktiva sessionerna till inaktiva. Om det finns en giltig primär uppdateringstoken (PRT) för den utloggade användaren och en ny inloggning körs avbryts enkel inloggning och användaren ser en uppmaning med en kontoväljare. Om det valda alternativet är det anslutna kontot som refererar till PRT fortsätter inloggningen automatiskt utan att behöva infoga nya autentiseringsuppgifter.

Enkel utloggning

När du omdirigerar användaren till end_session_endpointrensar Microsofts identitetsplattform användarens session från webbläsaren. Användaren kan dock fortfarande vara inloggad i andra program som använder Microsoft-konton för autentisering. För att göra det möjligt för dessa program att logga ut användaren samtidigt skickar Microsofts identitetsplattform en HTTP GET-begäran till registrerad LogoutUrl för alla program som användaren för närvarande är inloggad på. Program måste svara på den här begäran genom att rensa alla sessioner som identifierar användaren och returnera ett 200 svar. Om du vill ha stöd för enkel inloggning i ditt program måste du implementera en LogoutUrl sådan i programmets kod. Du kan ange LogoutUrl från appregistreringsportalen.

Nästa steg