Dela via

Auktorisera åtkomst till webbprogram med OpenID Connect och Azure Active Directory

Varning

Det här innehållet gäller för den äldre Azure AD v1.0-slutpunkten. Använd Microsofts identitetsplattform för nya projekt.

OpenID Connect är ett enkelt identitetslager som bygger på OAuth 2.0-protokollet. OAuth 2.0 definierar mekanismer för att hämta och använda åtkomsttoken för åtkomst till skyddade resurser, men de definierar inte standardmetoder för att tillhandahålla identitetsinformation. OpenID Connect implementerar autentisering som ett tillägg till OAuth 2.0-auktoriseringsprocessen. Den innehåller information om slutanvändaren i form av en id_token som verifierar användarens identitet och tillhandahåller grundläggande profilinformation om användaren.

OpenID Connect är vår rekommendation om du skapar ett webbprogram som finns på en server och nås via en webbläsare.

Registrera din applikation med din AD-klient

Registrera först ditt program hos din klientorganisation i Azure Active Directory (Azure AD). Detta ger dig ett program-ID för ditt program och gör det möjligt för det att ta emot token.

  1. Logga in på Azure-portalen.

  2. Välj din Azure AD-klient genom att välja ditt konto i det övre högra hörnet på sidan, följt av att välja Växla katalog och sedan välja lämplig klient.

    • Hoppa över det här steget om du bara har en Azure AD-klient under ditt konto eller om du redan har valt lämplig Azure AD-klientorganisation.

  3. I Azure-portalen söker du efter och väljer Azure Active Directory-.

  4. Välj Appregistreringari Azure Active Directory vänstra menyn och välj sedan Ny registrering.

  5. Följ anvisningarna och skapa ett nytt program. Det spelar ingen roll om det är ett webbprogram eller ett klientprogram för allmänheten (mobilt & skrivbord) för den här handledningen, men om du vill ha specifika exempel för webbprogram eller klientprogram för allmänheten kan du läsa våra snabbstartsguider.

    • Namn är programnamnet och beskriver ditt program för slutanvändarna.
    • Under Kontotyper som stöds väljer du Accounts in any organizational directory and personal Microsoft accounts (Konton i alla organisationskataloger och personliga Microsoft-konton).
    • Ange omdirigerings-URI:n. För webbprogram är det här bas-URL:en för din app där användarna kan logga in. Till exempel http://localhost:12345. För offentlig klient (mobil & desktop) använder Azure AD den för att returnera tokensvar. Ange ett värde som är specifikt för ditt program. Till exempel http://MyFirstAADApp.

  6. När du har slutfört registreringen tilldelar Azure AD ditt program en unik klientidentifierare (program-ID). Du behöver det här värdet i nästa avsnitt, så kopiera det från programsidan.

  7. Om du vill hitta ditt program i Azure-portalen väljer du Appregistreringaroch väljer sedan Visa alla program.

Autentiseringsflöde med OpenID Connect

Det mest grundläggande inloggningsflödet innehåller följande steg – var och en av dem beskrivs i detalj nedan.

OpenId Connect-autentiseringsflöde

OpenID Connect-metadatadokument

OpenID Connect beskriver ett metadatadokument som innehåller det mesta av den information som krävs för att en app ska kunna utföra inloggning. Detta inkluderar information som url:er som ska användas och platsen för tjänstens offentliga signeringsnycklar. Dokumentet OpenID Connect-metadata finns på:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

Metadata är ett enkelt JSON-dokument (JavaScript Object Notation). Ett exempel finns i följande kodfragment. Innehållet i kodfragmentet beskrivs fullständigt i OpenID Connect-specifikationen. Observera att om du anger ett klient-ID i stället för {tenant} ovan, kommer klientspecifika URI:er att returneras i JSON-objektet.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

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

Skicka inloggningsbegäran

När webbprogrammet behöver autentisera användaren måste det dirigera användaren till /authorize slutpunkten. Den här begäran liknar den första delen av OAuth 2.0 Authorization Code Flow, med några viktiga distinktioner:

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

Så en exempelbegäran skulle se ut så här:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
Parameter Typ Beskrivning
hyresgäst obligatorisk Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in på programmet. De tillåtna värdena är klientidentifierare, till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller contoso.onmicrosoft.com eller common för klientoberoende token
klient-id obligatorisk Program-ID:t som tilldelades din app när du registrerade det med Azure AD. Du hittar detta i Azure-portalen. Klicka på Azure Active Directory, klicka på Appregistreringar, välj programmet och leta upp program-ID:t på programsidan.
respons_typ obligatorisk Måste innehålla id_token för OpenID Connect-inloggning. Det kan också innehålla andra response_types, till exempel code eller token.
omfattning rekommenderas OpenID Connect-specifikationen kräver omfånget openid, vilket översätts till behörigheten "Logga in dig" i användargränssnittet för medgivande. Detta och andra OIDC-omfång ignoreras på v1.0-slutpunkten, men är fortfarande en bästa praxis för standardkompatibla klienter.
nonce obligatorisk Ett värde som ingår i begäran, som genereras av appen, som ingår i resultatet id_token som ett anspråk. Appen kan sedan verifiera det här värdet för att minimera tokenreprisattacker. Värdet är vanligtvis en slumpmässig, unik sträng eller GUID som kan användas för att identifiera begärans ursprung.
omdirigerings-URI rekommenderas Appens redirect_uri, där autentiseringssvar kan skickas och tas emot av din app. Den måste exakt matcha en av de redirect_uris du registrerade i portalen, förutom att den måste vara URL-kodad. Om det saknas skickas användaragenten tillbaka till någon av de omdirigerings-URI:er som registrerats för appen slumpmässigt. Den maximala längden är 255 byte
svarsläge valfri Anger vilken metod som ska användas för att skicka den resulterande authorization_code tillbaka till din app. Värden som stöds är form_post för HTTP-formulärinlägg och fragment för URL-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. Standardvärdet för alla flöde inklusive en id_token är fragment.
tillstånd rekommenderas Ett värde som ingår i begäran som returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll som du vill. 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 de var på.
omedelbar valfri Anger vilken typ av användarinteraktion som krävs. För närvarande är de enda giltiga värdena "login", "none" och "consent". prompt=login tvingar användaren att ange sina autentiseringsuppgifter för den begäran och negera enkel inloggning. prompt=none är motsatsen – det säkerställer att användaren inte får någon interaktiv uppmaning alls. Om begäran inte kan slutföras tyst via enkel inloggning returnerar slutpunkten ett fel. prompt=consent utlöser dialogrutan OAuth-medgivande när användaren har loggat in och ber användaren att bevilja behörigheter till appen.
inloggningsförslag valfri Kan användas för att i förväg fylla i fältet användarnamn/e-postadress på inloggningssidan för användaren, om du känner till användarnamnet i förväg. Oftast använder appar den här parametern under återautentisering, efter att ha extraherat användarnamnet från en tidigare inloggning med hjälp av preferred_username-klämmen.

Nu uppmanas användaren att ange sina autentiseringsuppgifter och slutföra autentiseringen.

Exempelsvar

Ett exempelsvar som skickas till angivet redirect_uri i inloggningsbegäran efter att användaren har autentiserats kan se ut så här:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parameter Beskrivning
identitets_token Det 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.
tillstånd Ett värde som ingår i begäran som också returneras i tokensvaret. Ett slumpmässigt genererat unikt värde används vanligtvis för att förhindra förfalskning av förfrågningar 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 de var på.

Felsvar

Felsvar kan också skickas till så att redirect_uri appen kan hantera dem på rätt sätt:

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

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

Felkoder för auktoriseringsslutpunktsfel

I följande tabell beskrivs de olika felkoder som kan returneras i parametern error för felsvaret.

Felkod Beskrivning Klientåtgärd
ogiltig_förfrågan Protokollfel, till exempel en parameter som saknas. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis under den första testningen.
obehörig_klient Klientprogrammet får 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 med instruktioner för att installera programmet och lägga till det i Azure AD.
åtkomst nekad Resursägaren nekades medgivande Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren samtycker.
otillåten_svarstyp Auktoriseringsservern stöder inte svarstypen i begäran. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis under den första testningen.
serverfel 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.
tillfälligt otillgänglig 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.
ogiltig resurs Målresursen är ogiltig eftersom den inte finns, Azure AD kan inte hitta den eller så är den inte korrekt konfigurerad. Detta indikerar 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 Azure AD.

Verifiera ID-token

Det räcker inte att bara ta emot en id_token för att autentisera användaren. Du måste verifiera signaturen och verifiera anspråken id_token enligt appens krav. Azure AD-slutpunkten använder JSON-webbtoken (JWT) och kryptering av offentliga nycklar för att signera token och verifiera att de är giltiga.

Du kan välja att verifiera id_token i klientkoden, men en vanlig metod är att skicka id_token till en serverdelsserver och utföra verifieringen där.

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

  • Se till att användaren/organisationen har registrerat sig för appen.
  • Se till att användaren har rätt auktorisering eller behörigheter med hjälp av wids- eller roles-anspråken.
  • 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 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, register, anpassning och liknande. Mer information om id_tokens och anspråk finns i AAD id_tokens.

Skicka en utloggningsbegäran

När du vill logga ut användaren från appen räcker det inte att rensa appens cookies eller på annat sätt avsluta sessionen med användaren. Du måste också omdirigera användaren till end_session_endpoint för utloggning. Om du inte gör det kan användaren autentisera till din app igen utan att ange sina autentiseringsuppgifter igen, eftersom de har en giltig session med enkel inloggning med Azure AD-slutpunkten.

Du kan helt enkelt omdirigera användaren till den end_session_endpoint som anges i OpenID Connect-metadatadokumentet:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter Typ Beskrivning
post_logout_redirect_uri rekommenderas Url:en som användaren ska omdirigeras till efter lyckad utloggning. Den här URL:en måste matcha en av de omdirigerings-URI:er som registrerats för ditt program i appregistreringsportalen. Om post_logout_redirect_uri inte ingår visas ett allmänt meddelande.

Enkel utloggning

När du omdirigerar användaren till end_session_endpointrensar Azure AD användarens session från webbläsaren. Användaren kan dock fortfarande vara inloggad i andra program som använder Azure AD för autentisering. För att göra det möjligt för dessa program att logga ut användaren samtidigt skickar Azure AD en HTTP GET-begäran till den registrerade 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 inloggning i ditt program måste du implementera en LogoutUrl sådan i programmets kod. Du kan ange LogoutUrl från Azure-portalen:

  1. Logga in på Azure-portalen.
  2. Välj din Active Directory genom att klicka på ditt konto i det övre högra hörnet på sidan.
  3. Välj Azure Active Directory i den vänstra navigeringspanelen och välj sedan Appregistreringar och välj ditt program.
  4. Klicka på Inställningar och sedan på Egenskaper och leta reda på textrutan Utloggnings-URL .

Tokenförvärv

Många webbappar behöver inte bara logga in användaren, utan även få åtkomst till en webbtjänst åt användaren som använder OAuth. Det här scenariot kombinerar OpenID Connect för användarautentisering samtidigt som du hämtar en authorization_code som kan användas för att få access_tokens genom OAuth Authorization Code Flow.

Hämta åtkomsttoken

Om du vill hämta åtkomsttoken måste du ändra inloggningsbegäran ovan:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

Genom att inkludera behörighetsomfång i begäran och använda response_type=code+id_token säkerställer authorize-slutpunkten att användaren har samtyckt till de behörigheter som anges i scope-frågeparametern och returnerar en auktoriseringskod till din app för att byta mot en åtkomsttoken.

Lyckat svar

Ett lyckat svar, som skickas till redirect_uri med hjälp av 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...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Parameter Beskrivning
identitets_token Det 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.
kod Den authorization_code som appen begärde. Appen kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. Authorization_codes är kortlivade och upphör vanligtvis att gälla efter cirka 10 minuter.
tillstånd 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.

Felsvar

Felsvar kan också skickas till så att redirect_uri 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
fel En felkodssträng som kan användas för att klassificera typer av fel som inträffar och som kan användas för att reagera på fel.
felbeskrivning Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel.

En beskrivning av möjliga felkoder och deras rekommenderade klientåtgärd finns i Felkoder för auktoriseringsslutpunktsfel.

När du har fått en auktorisering code och en id_tokenkan du logga in användaren och få åtkomsttoken för deras räkning. För att logga in användaren måste du verifiera id_token exakt enligt beskrivningen ovan. För att få åtkomsttoken kan du följa stegen som beskrivs i avsnittet "Använd auktoriseringskoden för att begära en åtkomsttoken" i vår dokumentation om OAuth-kodflödet.

Nästa steg