OpenID Connect på Microsofts identitetsplattform

OpenID Connect (OIDC) utökar OAuth 2.0-auktoriseringsprotokollet för användning även som ett autentiseringsprotokoll. Du kan använda OIDC för att aktivera enkel inloggning (SSO) mellan 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 i OpenID Connect Core 1.0-specifikationen.

Protokollflöde: Inloggning

Det här diagrammet visar det grundläggande OpenID Connect-inloggningsflödet. Stegen i flödet beskrivs mer detaljerat i senare avsnitt i artikeln.

Simfältsdiagram som visar OpenID Connect-protokollets inloggningsflöde.

Tips

Prova att köra den här begäran i Postman
Prova att köra den här begäran och mer i Postman – glöm inte att ersätta token och ID:t!

Aktivera ID-token

ID-token som introducerades av OpenID Connect 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 få annan information (anspråk) om dem.

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

Om du vill aktivera ID-token för din app navigerar du till Azure Portal och sedan:

  1. Välj Azure Active Directory>Appregistreringar><din programautentisering>>.
  2. Under Implicit beviljande och hybridflöden markerar du kryssrutan ID-token (används för implicita och hybridflöden).

Eller:

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

Om du glömmer att aktivera ID-token för din app och du begär en, 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 bland annat använda metadata för att identifiera de 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 du använder ett autentiseringsbibliotek i din app (rekommenderas) 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 Azure AD 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 Azure AD kan logga in på programmet.
organizations Endast användare med arbets- eller skolkonton från Azure AD 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 Azure AD 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 Azure AD klientorganisation eller klientorganisations-ID i GUID-format. Du kan också använda konsumentklientorganisationens GUID, 9188040d-6c67-4c5b-b112-36a304b66dad, i stället för consumers.

Du hittar även appens OpenID-konfigurationsdokument-URI i appregistreringen i Azure Portal.

Du hittar OIDC-konfigurationsdokumentet för din app genom att gå till Azure Portal och sedan:

  1. Välj Azure Active Directory>Appregistreringar><då programslutpunkter>>.
  2. Leta upp URI:n under OpenID Connect-metadatadokumentet.

Exempelbegäran

Den här 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

Tips

Prova! Om du vill se OpenID-konfigurationsdokumentet common för ett programs auktoritet 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 (trunkerat för korthet). Metadata som returneras i JSON-svaret beskrivs i detalj i OpenID Connect 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 slutpunkt. Begäran liknar den första delen av OAuth 2.0-auktoriseringskodflödet , men med dessa skillnader:

  • Inkludera omfånget openid i parametern scope .
  • Ange id_token eller code+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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 Krävs 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 loggar in 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 Obligatorisk Det program-ID (klient)-ID som Azure Portal – Appregistreringar upplevelse som tilldelats din app.
response_type Obligatorisk Måste inkluderas id_token för OpenID Connect-inloggning. Det kan också innehålla andra response_type värden, till exempel code.
redirect_uri Rekommenderas 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 Obligatorisk En blankstegsavgränsad lista över omfång. För OpenID Connect 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 Obligatorisk Ett värde som genereras och skickas av din app i begäran om en ID-token. Samma nonce värde ingår i 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 Rekommenderas Anger den 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 Rekommenderas 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 för tillfället är login, none, consentoch select_account. Anspråket prompt=login tvingar användaren att ange sina autentiseringsuppgifter för den begäran, vilket förhindrar enkel inloggning. Parametern prompt=none är den motsatta 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 i förväg 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åketlogin_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 effektiv 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 godkänna 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 autentiserats och gett medgivande returnerar Microsofts identitetsplattform ett svar till din app på angiven omdirigerings-URI 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 Beskrivning
id_token Den 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 ID-tokenreferensen.
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 Beskrivning
error En felkodsträ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 Description Klientåtgärd
invalid_request Protokollfel som en obligatorisk 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 Azure AD eller inte läggs till i användarens Azure AD klientorganisation. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD.
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, Azure AD inte kan hitta den eller har konfigurerats felaktigt. Det här felet anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD.

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 kryptografi med offentliga nycklar.

Webbappar och webb-API:er som använder ID-token för auktorisering måste verifiera dem eftersom sådana program ger åtkomst till data. Andra typer av program kanske dock inte drar nytta av ID-tokenvalidering. Interna 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å verifieringen.

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 Verifiera en ID-token i ID-tokenreferensen. 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
  • Säkerställande av en viss autentiseringsstyrka har inträffat, 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: Anskaffning av åtkomsttoken

Många program behöver inte bara logga in en användare, utan även komma åt en skyddad resurs som ett webb-API för användarens räkning. I det här scenariot kombineras OpenID Connect 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 Connect-flödet för inloggning och tokenhämtning ser ut ungefär så här:

OpenID Connect-protokoll: Tokenförvärv

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=6731de76-14a6-49ae-97bc-6eba6914391e        // 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 i stället response_type=token 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 Beskrivning
access_token Den token som ska användas för att anropa UserInfo-slutpunkten.
token_type Alltid "bärare"
expires_in Hur lång tid tills åtkomsttoken upphör att gälla, i sekunder.
scope De behörigheter som beviljas för åtkomsttoken. Eftersom UserInfo-slutpunkten finns på Microsoft Graph är det möjligt för scope att innehålla andra som tidigare beviljats till programmet (till exempel User.Read).
id_token Den 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 valideras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Även om läsning av token är ett användbart felsöknings- och inlärningsverktyg bör du inte använda beroenden för detta i din kod 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 Beskrivning
error En felkodsträ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 exakt enligt beskrivningen. Om du vill hämta åtkomsttoken följer du stegen som beskrivs i dokumentationen för OAuth-kodflöde.

Anropa UserInfo-slutpunkten

Läs userinfo-dokumentationen för att se hur du anropar UserInfo-slutpunkten med denna 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 din apps cookies eller avsluta användarens session i ditt program på annat sätt.

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 enligt end_session_endpoint beskrivningen i konfigurationsdokumentet för OpenID Connect. end_session_endpoint stöder 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 Description
post_logout_redirect_uri Rekommenderas 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åketlogin_hint i klientprogrammet och använder värdet för det login_hint valfria anspråket logout_hint som parameter. Använd inte UPN:er eller telefonnummer som värde för parametern logout_hint .

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 på andra program som använder Microsoft-konton för autentisering. Om du vill göra det möjligt för dessa program att logga ut användaren samtidigt skickar Microsofts identitetsplattform en HTTP GET-begäran till registreringen LogoutUrl av 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 utloggning i ditt program måste du implementera en LogoutUrl sådan i programmets kod. Du kan ange från appregistreringsportalen LogoutUrl .

Nästa steg