Delen via

Toegang verlenen aan webtoepassingen die gebruikmaken van OpenID Connect en Azure Active Directory

  • Artikel

Waarschuwing

Deze inhoud is voor het oudere Azure AD v1.0-eindpunt. Gebruik het Microsoft Identity Platform voor nieuwe projecten.

OpenID Connect is een eenvoudige identiteitslaag die is gebouwd op het OAuth 2.0-protocol. OAuth 2.0 definieert mechanismen voor het verkrijgen en gebruiken van toegangstokens voor toegang tot beveiligde resources, maar ze definiëren geen standaardmethoden om identiteitsgegevens te verstrekken. OpenID Connect implementeert verificatie als een extensie voor het OAuth 2.0-autorisatieproces. Het biedt informatie over de eindgebruiker in de vorm van een id_token die de identiteit van de gebruiker verifieert en basisprofielgegevens over de gebruiker verstrekt.

OpenID Connect is onze aanbeveling als u een webtoepassing bouwt die wordt gehost op een server en toegankelijk is via een browser.

Uw toepassing registreren bij uw AD-tenant

U moet eerst uw toepassing registreren bij uw Azure Active Directory-tenant (Azure AD-tenant). Na registratie beschikt u over een toepassings-id voor uw toepassing en kan uw toepassing tokens ontvangen.

  1. Meld u aan bij de Azure-portal.

  2. Kies uw Azure Active Directory-tenant door in de rechterbovenhoek van deze pagina uw account te selecteren, gevolgd door de navigatie Directory schakelen te selecteren en vervolgens de juiste tenant te selecteren.

    • Sla deze stap over als u maar één Azure AD-tenant in uw account hebt of als u al de juiste Azure AD-tenant hebt geselecteerd.

  3. Zoek en selecteer in de Azure-portal de optie Azure Active Directory.

  4. Selecteer in het linkermenu van de Azure Active Directory achtereenvolgens App-registraties en Nieuwe registratie.

  5. Volg de aanwijzingen en maak een nieuwe toepassing. Voor deze zelfstudie maakt het niet uit of het een webtoepassing of een openbare clienttoepassing (mobiel & desktop) is, maar als u specifieke voorbeelden wilt voor webtoepassingen of openbare clienttoepassingen, raadpleegt u onze quickstarts.

    • Naam is de naam van de toepassing en beschrijft de toepassing voor eindgebruikers.
    • Selecteer onder Ondersteunde accounttypen de optie Accounts in een organisatieadreslijst en persoonlijke Microsoft-account.
    • Geef de omleidings-URI op. Voor webtoepassingen is dit de basis-URL van uw toepassing, waar gebruikers zich kunnen aanmelden. Bijvoorbeeld http://localhost:12345. Voor een openbare client (mobiele & desktop) gebruikt Azure AD deze om tokenantwoorden te retourneren. Voer een specifieke waarde in voor uw toepassing. Bijvoorbeeld http://MyFirstAADApp.

  6. Nadat u de registratie hebt voltooid, wijst Azure AD aan uw toepassing een unieke client-id toe. Dit is de toepassings-id. U hebt deze waarde nodig in de volgende secties. Kopieer deze daarom vanaf de toepassingspagina.

  7. Als u uw toepassing in de Azure Portal wilt vinden, selecteert u App-registraties en selecteert u vervolgens Alle toepassingen weergeven.

Verificatiestroom waarbij OpenID Connect wordt gebruikt

De meest eenvoudige aanmeldingsstroom bevat de volgende stappen. Elk van deze stappen wordt hieronder uitgebreid beschreven.

OpenId Connect-verificatiestroom

OpenID Connect-document met metagegevens

OpenID Connect beschrijft een metagegevensdocument dat de meeste informatie bevat die een app nodig heeft om aan te melden. Dit omvat informatie zoals de URL's die moeten worden gebruikt en de locatie van de openbare ondertekeningssleutels van de service. Het OpenID Connect-metagegevensdocument vindt u op:

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

De metagegevens zijn een eenvoudig JSON-document (JavaScript Object Notation). Zie het volgende fragment voor een voorbeeld. De inhoud van het fragment wordt volledig beschreven in de OpenID Connect-specificatie. Houd er rekening mee dat het opgeven van een tenant-id in plaats van common voor {tenant} hierboven resulteert in tenantspecifieke URI's in het JSON-object dat wordt geretourneerd.

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

Als uw app aangepaste ondertekeningssleutels heeft als gevolg van het gebruik van de functie voor claimtoewijzing, moet u een appid-queryparameter met de app-id toevoegen om een jwks_uri te krijgen die wijst naar de informatie over de ondertekeningssleutel van uw app. Bijvoorbeeld: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e bevat een jwks_uri van https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

De aanmeldingsaanvraag verzenden

Wanneer uw webtoepassing de gebruiker moet verifiëren, moet deze de gebruiker doorsturen naar het /authorize-eindpunt. Deze aanvraag is vergelijkbaar met het eerste deel van de OAuth 2.0-autorisatiecodestroom, met enkele belangrijke verschillen:

  • De aanvraag moet het bereik openid in de scope-parameter bevatten.
  • De response_type-parameter moet id_token bevatten.
  • De aanvraag moet de nonce-parameter bevatten.

Een voorbeeldaanvraag ziet er dan als volgt uit:

// 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 Type Description
tenant vereist De {tenant} waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. De toegestane waarden zijn tenant-id's, bijvoorbeeld 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 of contoso.onmicrosoft.comcommon voor tenant-onafhankelijke tokens
client_id vereist De toepassings-id die aan uw toepassing is toegewezen toen u deze bij Azure AD hebt geregistreerd. U vindt dit in de Azure Portal. Klik op Azure Active Directory, klik op App-registraties, kies de toepassing en zoek de toepassings-id op de toepassingspagina.
response_type vereist Moet id_token bevatten voor aanmelding bij OpenID Connect. Het kan ook andere response_types bevatten, zoals code of token.
scope aanbevolen De OpenID Connect-specificatie vereist het bereik openid, dat wordt omgezet in de machtiging 'Aanmelden' in de gebruikersinterface voor toestemming. Deze en andere OIDC-bereiken worden genegeerd op het v1.0-eindpunt, maar is wel een best practice voor clients die compatibel zijn met standaarden.
nonce vereist Een waarde die is opgenomen in de aanvraag, gegenereerd door de app, die wordt opgenomen in de resulterende id_token als een claim. De app kan deze waarde vervolgens verifiëren om aanvallen waarbij tokens worden herhaald te beperken. De waarde is doorgaans een gerandomiseerde, unieke tekenreeks of GUID die kan worden gebruikt om de oorsprong van de aanvraag te identificeren.
redirect_uri aanbevolen De omleidings-URI van uw app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in de portal, behalve dat deze URL-codering moet hebben. Als deze ontbreekt, wordt de gebruikersagent willekeurig teruggestuurd naar een van de omleidings-URI's die zijn geregistreerd voor de app. Maximale lengte is 255 bytes
response_mode optioneel Hiermee geeft u de methode op die moet worden gebruikt om de resulterende authorization_code terug te sturen naar uw app. Ondersteunde waarden zijn form_post voor HTTP-formulierpost en fragment voor URL-fragment. Voor webtoepassingen raden we u aan response_mode=form_post te gebruiken om te zorgen voor de veiligste overdracht van tokens naar uw toepassing. De standaardinstelling voor elke stroom, inclusief een id_token is fragment.
staat aanbevolen Een waarde die is opgenomen in de aanvraag die wordt geretourneerd in de tokenreactie. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt voor om aanvallen van aanvraagvervalsing op meerdere sites te voorkomen. De status wordt ook gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
vraag optioneel Geeft het type gebruikersinteractie aan dat vereist is. Momenteel zijn de enige geldige waarden 'aanmelden', 'geen' en 'toestemming'. prompt=login dwingt de gebruiker om zijn referenties op die aanvraag in te voeren, waardoor eenmalige aanmelding wordt genegeerd. prompt=none is het tegenovergestelde - het zorgt ervoor dat de gebruiker geen interactieve prompt te zien krijgt. Als de aanvraag niet stil op de achtergrond kan worden voltooid via eenmalige aanmelding, retourneert het eindpunt een fout. prompt=consent activeert het dialoogvenster OAuth-toestemming nadat de gebruiker zich heeft aangemeld en vraagt de gebruiker machtigingen te verlenen aan de app.
login_hint optioneel Kan worden gebruikt om het veld gebruikersnaam/e-mailadres van de aanmeldingspagina voor de gebruiker vooraf in te vullen, als u de gebruikersnaam vooraf weet. Apps gebruiken deze parameter vaak tijdens het opnieuw verifiëren, waarbij de gebruikersnaam al is geëxtraheerd uit een eerdere aanmelding met behulp van de preferred_username-claim.

Op dit moment wordt de gebruiker gevraagd om zijn referenties in te voeren en de verificatie te voltooien.

Voorbeeldantwoord

Een voorbeeldantwoord dat is verzonden naar de redirect_uri opgegeven aanmeldingsaanvraag nadat de gebruiker is geverifieerd, kan er als volgt uitzien:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
Parameter Beschrijving
id_token De id_token-app die door de app is aangevraagd. U kunt de id_token gebruiken om de identiteit van de gebruiker te controleren en een sessie met de gebruiker te starten.
staat Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in de tokenreactie. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt voor om aanvallen van aanvraagvervalsing op meerdere sites te voorkomen. De status wordt ook gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.

Foutreactie

Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de app ze op de juiste wijze kan verwerken:

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 Beschrijving
fout Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren.

Foutcodes voor autorisatie-eindpuntfouten

In de volgende tabel worden de verschillende foutcodes beschreven die kunnen worden geretourneerd in de error-parameter van het foutbericht.

Foutcode Description Clientactie
invalid_request Protocolfout, zoals een ontbrekende, vereiste parameter. Herstel de aanvraag en dien ze opnieuw in. Dit is een ontwikkelingsfout en wordt meestal opgevangen tijdens de eerste test.
unauthorized_client De clienttoepassing mag geen autorisatiecode aanvragen. Dit gebeurt meestal wanneer de clienttoepassing niet is geregistreerd in Azure AD of niet wordt toegevoegd aan de Azure AD-tenant van de gebruiker. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Azure AD.
access_denied Toestemming door resource-eigenaar geweigerd De clienttoepassing kan de gebruiker waarschuwen dat het niet kan worden voortgezet, tenzij de gebruiker toestemming geeft.
unsupported_response_type De autorisatieserver biedt geen ondersteuning voor het reactietype in de aanvraag. Herstel de aanvraag en dien ze opnieuw in. Dit is een ontwikkelingsfout en wordt meestal opgevangen tijdens de eerste test.
server_error Er is een onverwachte fout opgetreden op de server. Probeer de aanvraag opnieuw. Deze fouten kunnen worden veroorzaakt door tijdelijke voorwaarden. De clienttoepassing kan de gebruiker uitleggen dat de reactie is vertraagd vanwege een tijdelijke fout.
temporarily_unavailable De server is tijdelijk te druk om de aanvraag te verwerken. Probeer de aanvraag opnieuw. De clienttoepassing kan de gebruiker uitleggen dat de reactie is vertraagd vanwege een tijdelijke voorwaarde.
invalid_resource De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of deze niet juist is geconfigureerd. Dit geeft aan dat de resource, als deze bestaat, niet is geconfigureerd in de tenant. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Azure AD.

De id_token valideren

Het ontvangen van een id_token is niet voldoende om de gebruiker te verifiëren. U moet de handtekening valideren en de claims controleren in de id_token volgens de vereisten van uw app. Het Azure AD-eindpunt maakt gebruik van JSON Web Tokens (JWT's) en openbare-sleutelcryptografie om tokens te ondertekenen en te controleren of deze geldig zijn.

U kunt ervoor kiezen om de id_token-clientcode te valideren, maar het is gebruikelijk om de id_token naar een back-endserver te verzenden en daar de validatie uit te voeren.

Mogelijk wilt u ook aanvullende claims valideren, afhankelijk van uw scenario. Enkele vaak voorkomende validaties omvatten:

  • Ervoor zorgen dat de gebruiker/organisatie zich heeft geregistreerd voor de app.
  • Ervoor zorgen dat de gebruiker over de juiste autorisatie/bevoegdheden beschikt met behulp van de wids- of roles-claims.
  • Ervoor zorgen dat er een bepaalde verificatiesterkte is opgetreden, zoals meervoudige verificatie.

Zodra u de id_token hebt gevalideerd, kunt u een sessie met de gebruiker starten en de claims in de id_token gebruiken om informatie over de gebruiker in uw app te verkrijgen. Deze informatie kan worden gebruikt voor weergave, records, persoonlijke instellingen, enzovoort. Voor meer informatie over id_tokens en claims leest u AAD id_tokens.

Een afmeldingsaanvraag verzenden

Wanneer u de gebruiker wilt afmelden bij de app, is het niet voldoende om de cookies van uw app te wissen of anders de sessie met de gebruiker te beëindigen. U moet de gebruiker ook omleiden naar de end_session_endpoint voor afmelden. Als u dit niet doet, kan de gebruiker opnieuw verifiëren bij uw app zonder de referenties opnieuw in te voeren, omdat de gebruiker een geldige sessie voor eenmalige aanmelding heeft met het Azure AD-eindpunt.

U kunt de gebruiker gewoon omleiden naar de end_session_endpoint die staat vermeld in het OpenID Connect-metagegevensdocument:

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
Parameter Type Description
post_logout_redirect_uri aanbevolen De URL waarnaar de gebruiker moet worden omgeleid na het afmelden. Deze URL moet overeenkomen met een van de omleidings-URI's die zijn geregistreerd voor uw toepassing in de portal voor app-registratie. Als post_logout_redirect_uri niet is opgenomen, krijgt de gebruiker een algemeen bericht te zien.

Eenmalige afmelding

Wanneer u de gebruiker omleidt naar de end_session_endpoint, wist Azure AD de sessie van de gebruiker uit de browser. De gebruiker kan echter nog steeds zijn aangemeld bij andere toepassingen die Azure AD gebruiken voor verificatie. Als u wilt dat deze toepassingen de gebruiker tegelijkertijd afmelden, stuurt Azure AD een HTTP GET-aanvraag naar de geregistreerde LogoutUrl van alle toepassingen waarmee de gebruiker momenteel is aangemeld. Toepassingen moeten reageren op deze aanvraag door een sessie te wissen die de gebruiker identificeert en een 200-reactie retourneert. Als u eenmalige afmelding in uw toepassing wilt ondersteunen, moet u een dergelijke LogoutUrl implementeren in de code van uw toepassing. U kunt de LogoutUrl instellen vanuit de Azure Portal:

  1. Meld u aan bij de Azure-portal.
  2. Selecteer uw Active Directory door rechtsboven op de pagina op uw account te klikken.
  3. Kies Azure Active Directory in het linkernavigatievenster en kies vervolgens App-registraties en selecteer uw toepassing.
  4. Klik op Instellingen en vervolgens op Eigenschappen en zoek het tekstvak Afmeldings-URL.

Token ophalen

Veel web-apps moeten niet alleen de gebruiker aanmelden, maar ook toegang krijgen tot een webservice namens die gebruiker met behulp van OAuth. In dit scenario wordt OpenID Connect voor gebruikersverificatie gecombineerd terwijl tegelijkertijd een authorization_code wordt verkregen die kan worden gebruikt om de access_tokensop te halen met behulp van de OAuth-autorisatiecodestroom.

Toegangstokens ophalen

Als u toegangstokens wilt verkrijgen, moet u de aanmeldingsaanvraag van hierboven wijzigen:

// 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

Door het opnemen van machtigingsbereiken in de aanvraag en response_type=code+id_token te gebruiken, zorgt het authorize-eindpunt ervoor dat de gebruiker toestemming heeft gegeven voor de machtigingen die zijn aangegeven in de scope-queryparameter en retourneert uw app een autorisatiecode om een toegangstoken in te wisselen.

Geslaagde reactie

Een geslaagde reactie, verzonden naar de redirect_uri met behulp van response_mode=form_post, ziet er als volgt uit:

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

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
Parameter Beschrijving
id_token De id_token-app die door de app is aangevraagd. U kunt de id_token gebruiken om de identiteit van de gebruiker te controleren en een sessie met de gebruiker te starten.
code De autorisatiecode die door de app is aangevraagd. De app kan de autorisatiecode gebruiken om een toegangstoken aan te vragen voor de doelresource. Autorisatiecodes zijn kortstondige codes en verlopen normaal gesproken na ongeveer 10 minuten.
staat Als een statusparameter is opgenomen in de aanvraag, wordt dezelfde waarde weergegeven in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn.

Foutreactie

Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de app ze op de juiste wijze kan verwerken:

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 Beschrijving
fout Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren.

Zie Foutcodes voor autorisatie-eindpuntfouten voor een beschrijving van de mogelijke foutcodes en de aanbevolen clientactie.

Zodra u een autorisatie code en een id_token hebt gekregen, kunt u de gebruiker aanmelden en namens de gebruiker toegangstokens ophalen. Als u de gebruiker wilt aanmelden, moet u de id_token exact zoals hierboven beschreven valideren. Als u toegangstokens wilt ophalen, volgt u de stappen die worden beschreven in de sectie 'De autorisatiecode gebruiken om een toegangstoken aan te vragen' van onze OAuth-codestroomdocumentatie.

Volgende stappen