Dela via

Ge åtkomst till webbprogram med hjälp av OpenID Connect och Azure Active Directory

  • Artikel

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 som nås via en webbläsare.

Registrera ditt program med din AD-klient

Registrera först ditt program med din Azure Active Directory-klientorganisation (Azure AD). Det ger dig en program-ID för ditt program och låter det ta emot tokens.

  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 navigeringen Växla katalog och sedan välja lämplig klientorganisation.

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

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

  4. I den vänstra menyn i Azure Active Directory väljer du Appregistreringar och sedan Ny registrering.

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

    • Namn är appens namn och beskriver appen för anvä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 detta bas-URL:en för din app där användarna kan logga in. Till exempel http://localhost:12345. För offentliga klienter (mobila & desktop) använder Azure AD den för att returnera tokensvar. Ange ett specifikt värde för ditt program. Till exempel http://MyFirstAADApp.

  6. När du har slutfört registreringen tilldelar Azure AD programmet 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 Portal väljer du Appregistreringar och 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 merparten 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). Se följande kodfragment för ett exempel. Innehållet i kodfragmentet beskrivs fullständigt i OpenID Connect-specifikationen. Observera att om du anger ett klientorganisations-ID i stället common för {tenant} ovan resulterar det i klientspecifika URI:er i JSON-objektet som returneras.

{
    "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 app-ID:t för att få en jwks_uri 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-auktoriseringskodflödet, med några viktiga skillnader:

  • 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 Description
tenant krävs 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 till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 klientidentifierare eller contoso.onmicrosoft.comcommon för klientoberoende token
client_id krävs Det program-ID som tilldelats din app när du registrerade det med Azure AD. Du hittar detta i Azure Portal. Klicka på Azure Active Directory, klicka på Appregistreringar, välj programmet och leta upp program-ID:t på programsidan.
response_type krävs Måste inkluderas id_token för OpenID Connect-inloggning. Det kan också innehålla andra response_types, till exempel code eller token.
omfång Rekommenderas OpenID Connect-specifikationen kräver omfånget openid, som översätts till behörigheten "Logga in dig" i användargränssnittet för medgivande. Den här och andra OIDC-omfång ignoreras på v1.0-slutpunkten, men är fortfarande bästa praxis för standardkompatibla klienter.
Nonce krävs Ett värde som ingår i begäran, genererat 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.
redirect_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 som du registrerade i portalen, förutom att den måste vara URL-kodad. Om det saknas skickas användaragenten tillbaka till en av de omdirigerings-URI:er som registrerats för appen slumpmässigt. Den maximala längden är 255 byte
response_mode 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öden inklusive en id_token är fragment.
state 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å.
Snabb 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 fråga 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.
login_hint 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. Appar använder ofta den här parametern under omautentiseringen, eftersom de redan har extraherat användarnamnet från en tidigare inloggning med anspråket preferred_username .

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

Exempelsvar

Ett exempelsvar som skickas till angivet redirect_uri i inloggningsbegäran när 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
id_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.
state 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ö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å.

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 felkodsträ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.
error_description 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 Description Klientåtgärd
invalid_request Protokollfel, till exempel en parameter som saknas. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis upp under den första testningen.
unauthorized_client 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 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 är ett utvecklingsfel och fångas vanligtvis upp under den första testningen.
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 så är den inte korrekt konfigurerad. Detta 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

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. Den Azure AD slutpunkten använder JSON-webbtoken (JWT) och kryptografi med offentlig nyckel för att signera token och kontrollera 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/behörigheter med hjälp av anspråken wids eller roles .
  • En viss autentiseringsstyrka har säkerställts, till exempel multifaktorautentisering.

När du har verifierat id_tokenkan du starta en session med användaren och använda anspråken id_token i 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. 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 avsluta sessionen med användaren på annat sätt. Du måste också omdirigera användaren till end_session_endpoint för utloggning. Om du inte gör det kommer användaren att kunna autentisera till din app igen utan att ange sina autentiseringsuppgifter igen, eftersom de har en giltig session för enkel inloggning med Azure AD-slutpunkten.

Du kan helt enkelt omdirigera användaren till listan end_session_endpoint i dokumentet OpenID Connect-metadata:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter Typ Description
post_logout_redirect_uri Rekommenderas Den URL som användaren ska omdirigeras till efter att utloggningen har slutförts. 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 på 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 returnerar ett 200 svar. Om du vill stödja enkel inloggning i ditt program måste du implementera en LogoutUrl sådan i programmets kod. Du kan ange LogoutUrl från Azure Portal:

  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 för användarens räkning med hjälp av 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 använda access_tokensOAuth 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 med hjälp av response_type=code+id_tokenser authorize slutpunkten till att användaren har samtyckt till de behörigheter som anges i scope frågeparametern och returnerar appen en auktoriseringskod för att byta ut mot en åtkomsttoken.

Lyckat svar

Ett lyckat svar som skickas till med hjälp av redirect_uriresponse_mode=form_postser 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
id_token Den id_token app som begärdes. 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 kortvariga och upphör vanligtvis att gälla efter cirka 10 minuter.
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.

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 felkodsträ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.
error_description 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. Om du vill logga in användaren måste du verifiera exakt enligt beskrivningen id_token ovan. Om du vill hämta åtkomsttoken kan du följa stegen som beskrivs i avsnittet "Använd auktoriseringskoden för att begära en åtkomsttoken" i vår OAuth-kodflödesdokumentation.

Nästa steg