OAuth 2.0-autorisatiecodestroom in Azure Active Directory B2C

Artikel
11/06/2023

U kunt de OAuth 2.0-autorisatiecodetoestemming gebruiken in apps die op een apparaat zijn geïnstalleerd om toegang te krijgen tot beveiligde resources, zoals web-API's. Met behulp van de Azure Active Directory B2C-implementatie (Azure AD B2C) van OAuth 2.0 kunt u registratie-, aanmeldings- en andere identiteitsbeheertaken toevoegen aan uw mobiele apps en bureaublad-apps met één pagina. Dit artikel is taalonafhankelijk. In het artikel wordt beschreven hoe u HTTP-berichten verzendt en ontvangt zonder opensource-bibliotheken te gebruiken. Indien mogelijk raden we u aan de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken. Bekijk de voorbeeld-apps die gebruikmaken van MSAL.

De OAuth 2.0-autorisatiecodestroom wordt beschreven in sectie 4.1 van de OAuth 2.0-specificatie. U kunt het gebruiken voor verificatie en autorisatie in de meeste toepassingstypen, waaronder webtoepassingen, toepassingen met één pagina en systeemeigen geïnstalleerde toepassingen. U kunt de OAuth 2.0-autorisatiecodestroom gebruiken om veilig toegangstokens te verkrijgen en tokens te vernieuwen voor uw toepassingen. Deze kunnen worden gebruikt voor toegang tot resources die worden beveiligd door een autorisatieserver. Met het vernieuwingstoken kan de client nieuwe toegangstokens verkrijgen (en vernieuwen) zodra het toegangstoken verloopt, meestal na één uur.

Dit artikel is gericht op de OAuth 2.0-autorisatiecodestroom voor openbare clients . Een openbare client is een clienttoepassing die niet kan worden vertrouwd om de integriteit van een geheim wachtwoord veilig te onderhouden. Dit omvat toepassingen met één pagina, mobiele apps, bureaubladtoepassingen en in wezen elke toepassing die niet op een server wordt uitgevoerd.

Notitie

Als u identiteitsbeheer wilt toevoegen aan een web-app met behulp van Azure AD B2C, gebruikt u OpenID Connect in plaats van OAuth 2.0.

Azure AD B2C breidt de standaard OAuth 2.0-stromen uit om meer te doen dan eenvoudige verificatie en autorisatie. Hiermee wordt de gebruikersstroom geïntroduceerd. Met gebruikersstromen kunt u OAuth 2.0 gebruiken om gebruikerservaringen toe te voegen aan uw toepassing, zoals registratie, aanmelding en profielbeheer. Id-providers die gebruikmaken van het OAuth 2.0-protocol zijn Amazon, Microsoft Entra ID, Facebook, GitHub, Google en LinkedIn.

Ga als volgt te werk om de HTTP-aanvragen in dit artikel uit te proberen:

Vervang {tenant} door de naam van uw Azure AD B2C-tenant.
Vervang door 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 de app-id van een toepassing die u eerder hebt geregistreerd in uw Azure AD B2C-tenant.
Vervang door {policy} de naam van een beleid dat u in uw tenant hebt gemaakt, bijvoorbeeld b2c_1_sign_in.

Omleidings-URI vereist voor apps met één pagina

De autorisatiecodestroom voor toepassingen met één pagina vereist aanvullende instellingen. Volg de instructies voor het maken van uw toepassing met één pagina om uw omleidings-URI correct te markeren als ingeschakeld voor CORS. Als u een bestaande omleidings-URI wilt bijwerken om CORS in te schakelen, klikt u op de migratieprompt in de sectie Web van het tabblad Verificatie van de app-registratie. U kunt ook de App-registraties manifesteditor openen en het type veld voor uw omleidings-URI instellen op spa in de replyUrlsWithType sectie.

Het spa omleidingstype is achterwaarts compatibel met de impliciete stroom. Apps die momenteel gebruikmaken van de impliciete stroom om tokens op te halen, kunnen zonder problemen naar het spa omleidings-URI-type worden verplaatst en de impliciete stroom blijven gebruiken.

1. Een autorisatiecode ophalen

De autorisatiecodestroom begint met de client die de gebruiker naar het /authorize eindpunt leidt. Dit is het interactieve deel van de stroom, waar de gebruiker actie onderneemt. In deze aanvraag geeft de client in de scope parameter de machtigingen aan die nodig zijn om van de gebruiker te verkrijgen. In de volgende voorbeelden (met regeleinden voor leesbaarheid) ziet u hoe u een autorisatiecode kunt verkrijgen. Als u deze GET HTTP-aanvraag test, gebruikt u uw browser.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parameter	Vereist?	Beschrijving
{tenant}	Vereist	Naam van uw Azure AD B2C-tenant
{policy}	Vereist	De gebruikersstroom die moet worden uitgevoerd. Geef de naam op van een gebruikersstroom die u hebt gemaakt in uw Azure AD B2C-tenant. Bijvoorbeeld: `b2c_1_sign_in`, `b2c_1_sign_up`of `b2c_1_edit_profile`.
client_id	Vereist	De toepassings-id die in de Azure Portal aan uw app is toegewezen.
response_type	Vereist	Het antwoordtype, dat moet bevatten `code` voor de autorisatiecodestroom. U kunt een id-token ontvangen als u dit opneemt in het antwoordtype, zoals `code+id_token`, en in dit geval moet het bereik bevatten `openid`.
redirect_uri	Vereist	De omleidings-URI van uw app, waar verificatiereacties worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u in de portal hebt geregistreerd, behalve dat deze URL-codering moet hebben.
scope	Vereist	Een door spaties gescheiden lijst van bereiken. Het `openid` bereik geeft een machtiging aan om de gebruiker aan te melden en gegevens over de gebruiker op te halen in de vorm van id-tokens. Het `offline_access` bereik is optioneel voor webtoepassingen. Dit geeft aan dat uw toepassing een vernieuwingstoken nodig heeft voor uitgebreide toegang tot resources. De client-id geeft aan dat het uitgegeven token is bedoeld voor gebruik door Azure AD B2C-geregistreerde client. De `https://{tenant-name}/{app-id-uri}/{scope}` geeft een machtiging aan voor beveiligde resources, zoals een web-API. Zie Een toegangstoken aanvragen voor meer informatie.
response_mode	Aanbevolen	De methode die u gebruikt om de resulterende autorisatiecode terug te sturen naar uw app. Dit kan , `form_post`of `fragment`zijn`query`.
staat	Aanbevolen	Een waarde die is opgenomen in de aanvraag die een tekenreeks kan zijn van alle inhoud die u wilt gebruiken. Meestal wordt een willekeurig gegenereerde unieke waarde gebruikt om aanvallen met vervalsing van aanvragen 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 plaatsvond. Bijvoorbeeld de pagina waarop de gebruiker zich bevond of de gebruikersstroom die werd uitgevoerd.
vraag	Optioneel	Het type gebruikersinteractie dat is vereist. Op dit moment is `login`de enige geldige waarde , waardoor de gebruiker wordt gedwongen om zijn referenties in te voeren voor die aanvraag. Eenmalige aanmelding wordt niet van kracht.
code_challenge	aanbevolen/vereist	Wordt gebruikt om toekenningen van autorisatiecode te beveiligen via Proof Key for Code Exchange (PKCE). Vereist indien `code_challenge_method` is inbegrepen. U moet logica toevoegen in uw toepassing om de `code_verifier` en `code_challenge`te genereren. De `code_challenge` is een BASE64 URL-gecodeerde SHA256-hash van de `code_verifier`. U slaat de `code_verifier` op in uw toepassing voor later gebruik en verzendt de `code_challenge` samen met de autorisatieaanvraag. Zie de PKCE RFC voor meer informatie. Dit wordt nu aanbevolen voor alle toepassingstypen: systeemeigen apps, SPA's en vertrouwelijke clients zoals web-apps.
`code_challenge_method`	aanbevolen/vereist	De methode die wordt gebruikt om de `code_verifier` voor de `code_challenge`-parameter te coderen. Dit ZOU MOETEN zijn `S256`, maar de specificatie staat het gebruik van `plain` toe als om de een of andere reden de client SHA256 niet kan ondersteunen. Als u de `code_challenge_method`uitsluit, maar wel de `code_challenge`opneemt, wordt ervan uitgegaan dat het `code_challenge` tekst zonder opmaak is. Microsoft identity platform ondersteunt zowel als `plainS256`. Zie de PKCE RFC voor meer informatie. Dit is vereist voor apps met één pagina die gebruikmaken van de autorisatiecodestroom.
login_hint	No	Kan worden gebruikt om het veld met de aanmeldingsnaam van de aanmeldingspagina vooraf in te vullen. Zie De aanmeldingsnaam vooraf invullen voor meer informatie.
domain_hint	No	Biedt een hint voor Azure AD B2C over de sociale id-provider die moet worden gebruikt voor aanmelding. Als er een geldige waarde is opgenomen, gaat de gebruiker rechtstreeks naar de aanmeldingspagina van de id-provider. Zie Aanmelden omleiden naar een sociale provider voor meer informatie.
Aangepaste parameters	No	Aangepaste parameters die kunnen worden gebruikt met aangepaste beleidsregels. Bijvoorbeeld dynamische aangepaste pagina-inhouds-URI of sleutel-waarde claim resolvers.

Op dit moment wordt de gebruiker gevraagd om de werkstroom van de gebruikersstroom te voltooien. Dit kan betekenen dat de gebruiker zijn gebruikersnaam en wachtwoord invoert, zich aanmeldt met een sociale identiteit, zich registreert voor de directory of een ander aantal stappen. Gebruikersacties zijn afhankelijk van hoe de gebruikersstroom is gedefinieerd.

Nadat de gebruiker de gebruikersstroom heeft voltooid, retourneert Microsoft Entra id een antwoord naar uw app met de waarde die u hebt gebruikt voor redirect_uri. Hierbij wordt de methode gebruikt die is opgegeven in de response_mode parameter . Het antwoord is precies hetzelfde voor elk van de gebruikersactiescenario's, onafhankelijk van de gebruikersstroom die is uitgevoerd.

Een geslaagd antwoord dat gebruikmaakt van response_mode=query ziet er als volgt uit:

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

Parameter	Beschrijving
code	De autorisatiecode die de app heeft aangevraagd. De app kan de autorisatiecode gebruiken om een toegangstoken voor een doelresource aan te vragen. Autorisatiecodes hebben een zeer korte levensduur. Normaal gesproken verlopen ze na ongeveer 10 minuten.
staat	Zie de volledige beschrijving in de tabel in de vorige sectie. Als een `state`-parameter is opgenomen in de aanvraag, zou dezelfde waarde moeten verschijnen in de reactie. De app moet controleren of de `state` waarden in de aanvraag en het antwoord identiek zijn.

Foutreacties kunnen ook worden verzonden naar de omleidings-URI, zodat de app ze op de juiste manier kan verwerken:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Parameter	Beschrijving
fout	Een foutcodetekenreeks die u kunt gebruiken om de typen fouten te classificeren die optreden. U kunt de tekenreeks ook gebruiken om te reageren op fouten.
error_description	Een specifiek foutbericht waarmee u de hoofdoorzaak van een verificatiefout kunt identificeren.
staat	Zie de volledige beschrijving in de voorgaande tabel. Als een `state`-parameter is opgenomen in de aanvraag, zou dezelfde waarde moeten verschijnen in de reactie. De app moet controleren of de `state` waarden in de aanvraag en het antwoord identiek zijn.

2. Een toegangstoken ophalen

Nu u een autorisatiecode hebt verkregen, kunt u de code voor een token inwisselen bij de beoogde resource door een POST-aanvraag naar het /token eindpunt te verzenden. In Azure AD B2C kunt u op de gebruikelijke wijze toegangstokens aanvragen voor andere API's door hun bereik(en) op te geven in de aanvraag.

U kunt ook een toegangstoken aanvragen voor de eigen back-endweb-API van uw app op basis van de conventie van het gebruik van de client-id van de app als het aangevraagde bereik (wat resulteert in een toegangstoken met die client-id als de 'doelgroep'):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Parameter	Vereist?	Beschrijving
{tenant}	Vereist	Naam van uw Azure AD B2C-tenant
{policy}	Vereist	De gebruikersstroom die is gebruikt om de autorisatiecode te verkrijgen. U kunt in deze aanvraag geen andere gebruikersstroom gebruiken.
client_id	Vereist	De toepassings-id die in de Azure Portal aan uw app is toegewezen.
client_secret	Ja, in Web Apps	Het toepassingsgeheim dat is gegenereerd in de Azure Portal. Clientgeheimen worden in deze stroom gebruikt voor web-app-scenario's, waarbij de client een clientgeheim veilig kan opslaan. Voor scenario's met systeemeigen apps (openbare client) kunnen clientgeheimen niet veilig worden opgeslagen en worden ze daarom niet gebruikt in deze aanroep. Als u een clientgeheim gebruikt, moet u dit periodiek wijzigen.
grant_type	Vereist	Het type subsidie. Voor de autorisatiecodestroom moet het toekenningstype zijn `authorization_code`.
scope	Aanbevolen	Een door spaties gescheiden lijst van bereiken. Eén bereikwaarde geeft aan Microsoft Entra id van beide machtigingen die worden aangevraagd. Het gebruik van de client-id als het bereik geeft aan dat uw app een toegangstoken nodig heeft dat kan worden gebruikt voor uw eigen service of web-API, vertegenwoordigd door dezelfde client-id. Het `offline_access` bereik geeft aan dat uw app een vernieuwingstoken nodig heeft voor langdurige toegang tot resources. U kunt het `openid` bereik ook gebruiken om een id-token aan te vragen bij Azure AD B2C.
code	Vereist	De autorisatiecode die u hebt verkregen van het `/authorize` eindpunt.
redirect_uri	Vereist	De omleidings-URI van de toepassing waar u de autorisatiecode hebt ontvangen.
code_verifier	aanbevolen	Hetzelfde dat `code_verifier` wordt gebruikt om de autorisatiecode op te halen. Vereist als PKCE is gebruikt in de toekenningsaanvraag van de autorisatiecode. Zie de PKCE RFC voor meer informatie.

Als u deze POST HTTP-aanvraag test, kunt u elke HTTP-client gebruiken, zoals Microsoft PowerShell of Postman.

Een geslaagd tokenantwoord ziet er als volgt uit:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parameter	Beschrijving
not_before	Het tijdstip waarop het token als geldig wordt beschouwd, in epoch-tijd.
token_type	De waarde van het tokentype. Het enige type dat Microsoft Entra id ondersteunt, is Bearer.
access_token	Het ondertekende JSON-webtoken (JWT) dat u hebt aangevraagd.
scope	De bereiken waarvoor het token geldig is. U kunt ook bereiken gebruiken om tokens in de cache te plaatsen voor later gebruik.
expires_in	De tijdsduur dat het token geldig is (in seconden).
refresh_token	Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om extra tokens te verkrijgen nadat het huidige token is verlopen. Vernieuwingstokens hebben een lange levensduur. U kunt ze gebruiken om de toegang tot resources voor langere tijd te behouden. Zie de Azure AD B2C-tokenreferentie voor meer informatie.

Foutreacties zien er als volgt uit:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parameter	Beschrijving
fout	Een foutcodetekenreeks die u kunt gebruiken om de typen fouten te classificeren die optreden. U kunt de tekenreeks ook gebruiken om te reageren op fouten.
error_description	Een specifiek foutbericht waarmee u de hoofdoorzaak van een verificatiefout kunt identificeren.

3. Het token gebruiken

Nu u een toegangstoken hebt verkregen, kunt u het token gebruiken in aanvragen voor uw back-endweb-API's door het op te slaan in de Authorization header:

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Het token vernieuwen

Toegangstokens en id-tokens zijn van korte duur. Nadat ze zijn verlopen, moet u ze vernieuwen om toegang te blijven krijgen tot resources. Wanneer u het toegangstoken vernieuwt, retourneert Azure AD B2C een nieuw token. Het vernieuwde toegangstoken heeft de claimwaarden bijgewerkt nbf (niet eerder), iat (uitgegeven op) en exp (vervaldatum). Alle andere claimwaarden zijn hetzelfde als het oorspronkelijk uitgegeven toegangstoken.

Als u het token wilt vernieuwen, dient u nog een POST-aanvraag in bij het /token eindpunt. Geef deze keer de refresh_token op in plaats van de code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Parameter	Vereist?	Beschrijving
{tenant}	Vereist	Naam van uw Azure AD B2C-tenant
{policy}	Vereist	De gebruikersstroom die is gebruikt om het oorspronkelijke vernieuwingstoken te verkrijgen. U kunt in deze aanvraag geen andere gebruikersstroom gebruiken.
client_id	Vereist	De toepassings-id die is toegewezen aan uw app in de Azure Portal.
client_secret	Ja, in Web Apps	Het toepassingsgeheim dat is gegenereerd in de Azure Portal. Clientgeheimen worden in deze stroom gebruikt voor web-app-scenario's, waarbij de client een clientgeheim veilig kan opslaan. Voor scenario's met systeemeigen apps (openbare client) kunnen clientgeheimen niet veilig worden opgeslagen en worden ze daarom niet gebruikt in deze aanroep. Als u een clientgeheim gebruikt, wijzigt u dit regelmatig.
grant_type	Vereist	Het type subsidie. Voor dit deel van de autorisatiecodestroom moet het toekenningstype zijn `refresh_token`.
scope	Aanbevolen	Een door spaties gescheiden lijst van bereiken. Eén bereikwaarde geeft aan Microsoft Entra id van beide machtigingen die worden aangevraagd. Als u de client-id als bereik gebruikt, geeft u aan dat uw app een toegangstoken nodig heeft dat kan worden gebruikt voor uw eigen service of web-API, vertegenwoordigd door dezelfde client-id. Het `offline_access` bereik geeft aan dat uw app een vernieuwingstoken nodig heeft voor langdurige toegang tot resources. U kunt het `openid` bereik ook gebruiken om een id-token aan te vragen bij Azure AD B2C.
redirect_uri	Optioneel	De omleidings-URI van de toepassing waar u de autorisatiecode hebt ontvangen.
refresh_token	Vereist	Het oorspronkelijke vernieuwingstoken dat u hebt verkregen in het tweede deel van de stroom.