Microsofts identitetsplattform Anslut OpenID

OpenID Anslut (OIDC) är ett autentiseringsprotokoll som bygger på OAuth 2.0 och som du kan använda för att på ett säkert sätt logga in en användare i ett program. När du använder Microsofts identitetsplattform implementeringen av OpenID-Anslut kan du lägga till inloggning och API-åtkomst till dina appar. Den här artikeln visar hur du gör detta oberoende av språk och beskriver hur du skickar och tar emot HTTP-meddelanden utan att använda microsofts bibliotek med öppen källkod.

OpenID Anslut utökar OAuth 2.0-auktoriseringsprotokollet för användning som ett autentiseringsprotokoll, så att du kan göra enkel inloggning med OAuth. OpenID Anslut introducerar begreppet ID-token, vilket är en säkerhetstoken som gör att klienten kan verifiera användarens identitet. ID-token hämtar också grundläggande profilinformation om användaren. Den introducerar även UserInfo-slutpunkten, ett API som returnerar information om användaren.

Tips

Try running this request in Postman
Prova att köra den här begäran och mycket mer i Postman – glöm inte att ersätta token och-ID:er!

Protokolldiagram: Inloggning

I det mest grundläggande inloggningsflödet visas stegen i nästa diagram. Varje steg beskrivs i detalj i den här artikeln.

OpenID Connect protocol: Sign-in

Hämta dokumentet openID Anslut metadata

OpenID Anslut beskriver ett metadatadokument (RFC) som innehåller merparten av den information som krävs för att en app ska kunna logga in. Detta inkluderar information som url:er som ska användas och platsen för tjänstens offentliga signeringsnycklar. Du hittar det här dokumentet genom att lägga till sökvägen till identifieringsdokumentet till auktoritets-URL:en:

Sökväg till identifieringsdokument: /.well-known/openid-configuration

Myndigheten: https://login.microsoftonline.com/{tenant}/v2.0

{tenant}kan ta något av fyra värden:

Värde Beskrivning
common Användare med både ett personligt Microsoft-konto ett arbets- eller skolkonto från Azure AD kan logga in i programmet.
organizations Endast användare med arbets- eller skolkonton från Azure AD kan logga in i programmet.
consumers Endast användare med en Microsoft-konto kan logga in i programmet.
8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller contoso.onmicrosoft.com Endast användare från en viss Azure AD-klientorganisation (oavsett om de är medlemmar i katalogen med ett arbets- eller skolkonto, eller om de är gäster i katalogen med en personlig Microsoft-konto) kan logga in i programmet. Antingen det egna domännamnet för Azure AD-klienten eller klientens GUID-id kan användas. Du kan också använda 9188040d-6c67-4c5b-b112-36a304b66dad konsumentklientorganisationen, , i stället för consumers klientorganisationen.

Behörigheten skiljer sig åt mellan nationella moln, t.ex. https://login.microsoftonline.de för Azure AD-instansen i Tyskland. Om du inte använder det offentliga molnet kan du granska de nationella molnslutpunkterna för att hitta rätt moln. Kontrollera att klienten och /v2.0/ finns i din begäran så att du kan använda v2.0-versionen av slutpunkten.

Tips

Prova! Klicka https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration för att se common konfigurationen.

Exempelbegäran

Om du vill anropa userinfo-slutpunkten för den gemensamma auktoriteten i det offentliga molnet använder du följande:

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

Exempelsvar

Metadata är ett enkelt JavaScript Object Notation (JSON). Se följande kodfragment för ett exempel. Innehållet beskrivs fullständigt i OpenID-Anslut specifikation.

{
  "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"
  ],
  ...

}

Om din app har anpassade signeringsnycklar som ett resultat av att använda funktionen för anspråksmappning måste du lägga till en frågeparameter som innehåller app-ID:t för att få en pekare på appens signeringsnyckelinformation. jwks_uri Till exempel: https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e innehåller en jwks_uri av https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e .

Vanligtvis använder du det här metadatadokumentet för att konfigurera ett OpenID Anslut-bibliotek eller SDK. Biblioteket använder metadata för att göra sitt arbete. Men om du inte använder ett förbyggt OpenID Anslut-bibliotek kan du följa stegen i resten av den här artikeln för att logga in i en webbapp med hjälp av Microsofts identitetsplattform.

Skicka inloggningsbegäran

När webbappen behöver autentisera användaren kan den dirigera användaren till /authorize slutpunkten. Den här begäran liknar det första steget i OAuth 2.0-auktoriseringskodflödet,med följande viktiga skillnader:

  • Begäran måste innehålla openid omfånget i scope parametern .
  • Parametern response_type måste innehålla id_token .
  • Begäran måste innehålla nonce parametern .

Viktigt

För att kunna begära en ID-token från /authorization-slutpunkten måste appregistreringen i registreringsportalen ha implicit beviljande av id_tokens aktiverat på fliken Autentisering (som anger flaggan i programmanifestet till ). Om den inte är aktiverad returneras ett fel: "Det angivna värdet för indataparametern unsupported_response "response_type" tillåts inte för den här klienten. Det förväntade värdet är "code" (kod)

Ett exempel:

// Line breaks are for legibility only.

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 för begäran för att styra vem som kan logga in i programmet. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder. För gästscenarier där du loggar in en användare från en klientorganisation till en annan klientorganisation måste du ange klient-ID:t för att logga in dem på rätt sätt i resursklientorganisationen.
client_id Obligatorisk Det program-ID (klient) som Azure Portal – Appregistreringar till din app.
response_type Obligatorisk Måste id_token inkluderas för Anslut OpenID-inloggning. Den kan också innehålla andra response_type värden, till exempel code .
redirect_uri Rekommenderas Appens omdirigerings-URI, 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 registrerad redirect_uri slumpmässigt att skicka användaren tillbaka till.
scope Obligatorisk En blankstegsavgränsad lista över omfång. För OpenID Anslut måste det innehålla omfånget , som översätts till openidopenid 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 ingår i begäran, som genereras av appen, som inkluderas i det id_token värdet som anspråk. Appen kan verifiera det här värdet för att minimera tokenuppspelningsattacker. Värdet är vanligtvis en slumpmässig, unik sträng som kan användas för att identifiera begärans ursprung.
response_mode Rekommenderas Anger den metod som ska användas för att skicka den resulterande auktoriseringskoden tillbaka till din app. Det kan vara form_post eller fragment. För webbprogram rekommenderar vi att du response_mode=form_post använder 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 val annat 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 gjordes, till exempel den sida eller vy 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 , och consentselect_account . Anspråket prompt=login tvingar användaren att ange sina autentiseringsuppgifter för begäran, vilket negerar enkel inloggning. Parametern prompt=none är motsatsen och ska kopplas till en för att ange vilken användare som måste vara login_hint inloggad. De här parametrarna säkerställer att användaren inte visas någon interaktiv prompt alls. Om begäran inte kan slutföras tyst via enkel inloggning (eftersom ingen användare har loggat in, den hintade användaren inte är inloggad eller det finns flera användare inloggade och ingen ledtråd har angetts) returnerar Microsofts identitetsplattform ett fel. Anspråket prompt=consent utlöser dialogrutan för OAuth-medgivande när användaren loggar in. I dialogrutan uppmanas användaren att bevilja behörigheter till appen. Slutligen visar användaren en kontoväljare, negerar tyst enkel inloggning men låter användaren välja vilket konto de vill logga in med, utan att kräva select_account inmatning av autentiseringsuppgifter. Du kan inte använda login_hint och select_account tillsammans.
login_hint Valfritt Du kan använda den här parametern för att fylla i fältet användarnamn och e-postadress i förväg på inloggningssidan för användaren, om du känner till användarnamnet i förväg. Appar använder ofta den här parametern vid omauthenticering, efter att redan ha extraherat det valfria login_hintlogin_hint anspråket från en tidigare inloggning.
domain_hint Valfritt Området 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 är federerade 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. Den 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 uppmanas 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 innehavare.

När användaren autentiseras och ger sitt medgivande Microsofts identitetsplattform ett svar till din app vid den angivna omdirigerings-URI:en med hjälp av den metod som anges i response_mode parametern .

Lyckat svar

Ett lyckat svar när du använder response_mode=form_post ser ut så här:

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 id_token parametern 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.
state Om state en 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:en så att appen kan hantera dem. Ett felsvar ser ut så här:

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 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 error parametern för felsvaret:

Felkod Beskrivning Klientåtgärd
invalid_request Protokollfel, till exempel en obligatorisk parameter som saknas. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel som vanligtvis uppstår under den första testningen.
unauthorized_client Klientprogrammet kan inte begära en auktoriseringskod. Detta inträffar vanligtvis 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 godkänner det.
unsupported_response_type Auktoriseringsservern stöder inte svarstypen i begäran. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel som vanligtvis uppstår under den första testningen.
server_error Servern påträffade ett oväntat fel. Försök att skicka begäran igen. De här felen kan uppstå på grund av tillfälliga förhållanden. 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 att skicka begäran igen. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt tillstånd.
invalid_resource Målresursen är ogiltig eftersom den antingen inte finns, att Azure AD inte kan hitta den eller att den inte är korrekt konfigurerad. Detta anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren att ange instruktioner för att installera programmet och lägga till det i Azure AD.

Verifiera ID-token

Att bara få id_token är inte alltid tillräckligt för att autentisera användaren. Du kan också behöva verifiera id_token signatur och verifiera anspråken i token enligt appens krav. Precis som alla OIDC-plattformar använder Microsofts identitetsplattform JSON-webbtoken (JWT) och kryptering med offentlig nyckel för att signera ID-token och verifiera att de är giltiga.

Det är inte alla appar som har nytta av att verifiera ID-token – interna appar och ensidesappar kan till exempel sällan dra nytta av att verifiera ID-token. Någon med fysisk åtkomst till enheten (eller webbläsaren) kan kringgå valideringen på många sätt – från att redigera webbtrafiken till enheten för att tillhandahålla falska token och nycklar till att helt enkelt felsöka programmet för att hoppa över valideringslogiken. Å andra sidan måste webbappar och API:er som använder en ID-token för auktorisering verifiera ID-token noggrant eftersom de ger åtkomst till data.

När du har verifierat signaturen för id_token finns det några anspråk som du måste verifiera. Se referensen för mer information, inklusive validera token och viktig information om signering av nyckel för rollover. Vi rekommenderar att du använder ett bibliotek för parsning och validering av token – det finns minst ett tillgängligt för de flesta språk och plattformar.

Du kanske också vill verifiera ytterligare anspråk beroende på ditt scenario. Några vanliga verifieringar är:

  • Se till att användaren/organisationen har registrerat sig för appen.
  • Se till att användaren har rätt auktorisering/behörigheter
  • Att säkerställa en viss styrka för autentisering har inträffat, till exempel multifaktorautentisering.

När du har verifierat id_token kan du starta en session med användaren och använda anspråken i id_token för att hämta information om användaren i din app. Den här informationen kan användas för visning, poster, anpassning osv.

Protokolldiagram: Anskaffning av åtkomsttoken

Många webbappar behöver inte bara logga in användaren, utan även för att få åtkomst till en webbtjänst för användarens räkning med hjälp av OAuth. Det här scenariot kombinerar OpenID Anslut för användarautentisering samtidigt som du får en auktoriseringskod som du kan använda för att hämta åtkomsttoken om du använder OAuth-auktoriseringskodflödet.

Det fullständiga OpenID Anslut flödet för inloggning och tokenförvärv liknar nästa diagram. Vi beskriver varje steg i detalj i nästa avsnitt i artikeln.

OpenID Connect protocol: Token acquisition

Hämta en åtkomsttoken för att anropa UserInfo

Om du vill hämta en token för OIDC UserInfo-slutpunkten ändrar du inloggningsbegäran:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token%20token                       // this will return both an id_token and an access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your registered redirect URI, URL encoded
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // `openid` is required.  `profile` and `email` provide additional information in the UserInfo endpoint the same way they do in an ID token. 
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

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

Tips

Klicka på följande länk för att köra den här begäran. När du har loggat in omdirigeras webbläsaren till https://localhost/myapp/ , med en ID-token och en token i adressfältet. Observera att den här begäran response_mode=fragment endast används i demonstrationssyfte – för en webbapp rekommenderar vi att du använder form_post för ytterligare säkerhet där det är möjligt. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Lyckat tokensvar

Ett lyckat svar från att använda response_mode=form_post ser ut så här:

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 innebär 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 "Bearer"
expires_in Hur lång tid tar det innan åtkomsttoken upphör att gälla, i sekunder.
scope De behörigheter som beviljas för åtkomsttoken. Observera att eftersom UserInfo-slutpunkten finns på MS Graph kan det finnas ytterligare Graph-omfång som anges här (t.ex. user.read) om de tidigare har beviljats för appen. Det beror på att en token för en viss resurs alltid innehåller alla behörigheter som för närvarande beviljas till klienten.
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 referensen.
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 att verifiera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i din kod. Token för Microsoft-tjänster kan använda ett särskilt format som inte valideras som en JWT och kan också krypteras för konsumentanvändare (Microsoft-konto). Även om läsningstoken är ett användbart felsöknings- och inlärningsverktyg ska du inte ta beroenden av detta i koden eller förutsätta specifika token som inte är för ett API som du kontrollerar.

Felsvar

Felsvar kan också skickas till omdirigerings-URI:en så att appen kan hantera dem på rätt sätt. Ett felsvar ser ut så här:

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 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 slutpunktsfel för auktorisering.

När du har en auktoriseringskod och en ID-token kan du logga in användaren och hämta å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 OAuth-kodflödesdokumentationen.

Anropa UserInfo-slutpunkten

Granska UserInfo-dokumentationen för att titta på hur anropet av UserInfo-slutpunkten med denna token.

Skicka en ut logga ut-begäran

När du vill logga ut användaren från din app räcker det inte att rensa appens cookies eller på annat sätt avsluta användarens session. Du måste också omdirigera användaren till Microsofts identitetsplattform logga ut. Om du inte gör detta återautentiseringar användaren till din app utan att ange sina autentiseringsuppgifter igen, eftersom de kommer att ha en giltig session med enkel inloggning med Microsofts identitetsplattform.

Du kan omdirigera användaren till som anges end_session_endpoint i dokumentet OpenID Anslut metadata:

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 Rekommenderas Den URL som användaren omdirigeras till efter att ha loggat ut. Om parametern inte ingår visas ett allmänt meddelande som genereras av användarens Microsofts identitetsplattform. Den här URL:en måste matcha en av de omdirigerings-URI:er som registrerats för ditt program i appregistreringsportalen.

Enkel utloggning

När du omdirigerar användaren end_session_endpoint till Microsofts identitetsplattform rensar 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. För att dessa program ska kunna logga ut användaren samtidigt skickar Microsofts identitetsplattform en HTTP GET-begäran till den registrerade för alla program som användaren för närvarande är LogoutUrl inloggad på. Program måste svara på denna begäran genom att rensa alla sessioner som identifierar användaren och returnera ett 200 svar. Om du vill stödja enkel ut inloggning i ditt program måste du implementera en LogoutUrl sådan i programmets kod. Du kan ange från LogoutUrl appregistreringsportalen.

Nästa steg