AD FS OpenID Connect/OAuth-stromen en toepassingsscenario's
Van toepassing op AD FS 2019 en hoger
| Scenariobeschrijving | Scenario-overzicht met behulp van voorbeelden | OAuth 2.0-proces/vergunning | Cliënttype |
|---|---|---|---|
| App met één pagina | voorbeeld met MSAL- | Impliciete | Publiek |
| Web-app waarmee gebruikers worden aangemeld | voorbeeld met OWIN- | autorisatiecode | Openbaar, vertrouwelijk |
| Systeemeigen app roept web-API aan | voorbeeld met MSAL- | autorisatiecode | Publiek |
| Web-app roept web-API aan | voorbeeld met MSAL- | autorisatiecode | Vertrouwelijk |
| PKCE-implementatie | autorisatiecode | Publiek | |
| Web-API roept een andere web-API aan namens de gebruiker (OBO) | voorbeeld met MSAL- | namens | Web-app fungeert als vertrouwelijk |
| Daemon-app roept web-API aan | Clientgegevens | Vertrouwelijk | |
| Web App roept web-API aan met behulp van gebruikersreferenties | Gebruikersnaam en wachtwoord van de resource-eigenaar | Openbaar, vertrouwelijk | |
| Browserloze app roept web-API aan | apparaatcode | Openbaar, vertrouwelijk |
Impliciete toekenningsstroom
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie Impliciete toekenningsstroom in microsoft-identiteitsplatformvoor meer informatie over impliciete toekenningsstroom in Microsoft Entra ID.
Voor toepassingen met één pagina (AngularJS, Ember.js, React.js, enzovoort), ondersteunt AD FS de OAuth 2.0 Impliciete toekenningsstroom. De impliciete stroom wordt beschreven in de OAuth 2.0-specificatie. Het belangrijkste voordeel is dat de app tokens van AD FS kan ophalen zonder een exchange van referenties voor de back-endserver uit te voeren. Met deze stroom kan de app zich aanmelden bij de gebruiker, sessie onderhouden en tokens ophalen naar andere web-API's binnen de JavaScript-code van de client. Er zijn enkele belangrijke beveiligingsoverwegingen waarmee u rekening moet houden bij het gebruik van de impliciete stroom specifiek rond client.
Als u de impliciete stroom en AD FS wilt gebruiken om verificatie toe te voegen aan uw JavaScript-app, volgt u de algemene stappen in de volgende sectie.
Protocolschema
In het volgende diagram ziet u hoe de volledige impliciete aanmeldingsstroom eruitziet en de secties die volgen, beschrijven elke stap in meer detail.
impliciete aanmelding 
Id-token en toegangstoken aanvragen
Als u de gebruiker in eerste instantie wilt aanmelden bij uw app, kunt u een OpenID Connect-verificatieaanvraag verzenden en id_token en toegangstoken ophalen vanuit het AD FS-eindpunt.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| response_type | vereist | Moet id_token bevatten voor aanmelding bij OpenID Connect. Het kan ook de response_type tokenbevatten. Door het token hier te gebruiken, kan uw app direct vanaf het autorisatie-eindpunt een toegangstoken ontvangen zonder dat u een tweede aanvraag hoeft te doen voor het tokeneindpunt. |
| redirect_uri | vereist | De redirect_uri van uw app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Het moet exact overeenkomen met een van de redirect_uris die u hebt geconfigureerd in AD FS. |
| nonce | vereist | Een waarde die is opgenomen in de aanvraag, gegenereerd door de app die moet worden 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 die kan worden gebruikt om de oorsprong van de aanvraag te identificeren. Alleen vereist wanneer een id_token wordt aangevraagd. |
| omvang | optioneel | Een door spaties gescheiden lijst van scopes. Voor OpenID Connect moet de scope openidzijn opgenomen. |
| hulpbron | optioneel | De URL van uw web-API. Opmerking: als u msal-clientbibliotheek gebruikt, wordt de resourceparameter niet verzonden. In plaats daarvan wordt de resource-URL verzonden als onderdeel van de bereikparameter: scope = [resource url]//[scope values e.g., openid]Als de resource hier of in het bereik niet wordt doorgegeven, gebruikt AD FS een standaardresource urn:microsoft:userinfo. Het resourcebeleid voor gebruikersinformatie, zoals MFA, uitgifte- of autorisatiebeleid, kan niet worden aangepast. |
| reactiemodus | optioneel | Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. Standaard ingesteld op fragment. |
| staat | optioneel | Een waarde die is opgenomen in de aanvraag die ook moet worden geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om vervalsingsaanvallen op meerdere sites te voorkomen. De status wordt ook gebruikt om informatie over de status van de gebruiker in de app te coderen voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden. |
| aanmoediging | optioneel | Geeft het type gebruikersinteractie aan dat vereist is. De enige geldige waarden op dit moment zijn inloggen en geen. - prompt=login dwingt de gebruiker om hun inloggegevens in te voeren bij dat verzoek, waardoor single-sign-on wordt genegeerd.
- prompt=none is het tegenovergestelde - het zorgt ervoor dat de gebruiker helemaal geen interactieve prompt krijgt. Als de aanvraag niet stilzwijgend kan worden voltooid via eenmalige aanmelding, retourneert AD FS een fout 'interactie vereist'. |
| 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 van tevoren kent. Apps gebruiken deze parameter vaak tijdens opnieuw verificatie, nadat de gebruikersnaam al is geëxtraheerd uit een vorige aanmelding met behulp van de upn claim van id_token. |
| domein_hint | optioneel | Indien opgenomen, wordt het detectieproces op basis van een domein overgeslagen dat de gebruiker doorloopt op de aanmeldingspagina, wat leidt tot een iets gestroomlijndere gebruikerservaring. |
Op dit moment wordt de gebruiker gevraagd om zijn referenties in te voeren en de verificatie te voltooien. Zodra de gebruiker is geverifieerd, retourneert het AD FS-autorisatie-eindpunt een antwoord op uw app op de aangegeven redirect_uri, met behulp van de methode die is opgegeven in de parameter response_mode.
Succesvolle respons
Een geslaagd antwoord met behulp van response_mode=fragment and response_type=id_token+token ziet er als volgt uit
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| Maatstaf | Beschrijving |
|---|---|
| toegangstoken | Inbegrepen als response_type tokenbevat. |
| token_type | Inbegrepen als response_type tokenbevat. Het is altijd "Bearer". |
| verloopt_in | Inbegrepen als response_type tokenbevat. Geeft het aantal seconden aan dat het token geldig is voor cachedoeleinden. |
| omvang | Geeft de scope(s) aan waarvoor de access_token geldig is. |
| id_token | Inbegrepen als response_type id_tokenbevat. Een ondertekend JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. |
| 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. |
Vernieuwen van tokens
De impliciete toekenning biedt geen vernieuwingssleutels. Zowel id_tokens als access_tokens verloopt na een korte periode, zodat uw app moet worden voorbereid om deze tokens periodiek te vernieuwen. Als u een van beide typen token wilt vernieuwen, kunt u dezelfde verborgen iframeaanvraag uitvoeren in de vorige sectie met behulp van de parameter prompt=none om het gedrag van het identiteitsplatform te beheren. Als u een new id_tokenwilt ontvangen, moet u response_type=id_tokengebruiken.
Stroom voor het verlenen van autorisatiecode
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie voor meer informatie over de autorisatiecode-stroom in Microsoft Entra ID autorisatiecode-stroom in het Microsoft Identity Platform.
De toekenning van OAuth 2.0-autorisatiecode kan worden gebruikt in web-apps om toegang te krijgen tot beveiligde resources, zoals web-API's. De OAuth 2.0-autorisatiecodestroom wordt beschreven in sectie 4.1 van de OAuth 2.0-specificatie. Het wordt gebruikt om verificatie en autorisatie uit te voeren in de meeste app-typen, waaronder web-apps en systeemeigen geïnstalleerde apps. Met de verwerkingsstroom kunnen apps veilig toegangstokens verkrijgen die kunnen worden gebruikt voor toegang tot resources die door AD FS worden vertrouwd.
Protocol-diagram
Op hoog niveau ziet de verificatiestroom voor een systeemeigen toepassing er ongeveer als volgt uit:
Een autorisatiecode aanvragen
De autorisatiecodestroom begint met de client die de gebruiker naar het eindpunt /authorize stuurt. In deze aanvraag geeft de client de machtigingen aan die nodig zijn om van de gebruiker te verkrijgen:
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| reactietype | vereist | Moet code bevatten voor de autorisatiecodestroom. |
| doorverwijs_uri | vereist | Het gedeelte van uw redirect_uri app waar authenticatiereacties kunnen worden verzonden en ontvangen door uw app. Het moet exact overeenkomen met een van de redirect_uris die u hebt geregistreerd in de AD FS voor de client. |
| hulpbron | optioneel | De URL van uw web-API. Opmerking: als u msal-clientbibliotheek gebruikt, wordt de resourceparameter niet verzonden. In plaats daarvan wordt de resource-URL verzonden als onderdeel van de bereikparameter: scope = [resource url]//[scope values e.g., openid]Als de resource hier of in het bereik niet wordt doorgegeven, gebruikt AD FS een standaardresource urn:microsoft:userinfo. Beleidsregels voor gebruikersinformatie, zoals MFA, uitgifte- of autorisatiebeleid, kunnen niet aangepast worden. |
| omvang | optioneel | Een door spaties gescheiden lijst van scopes. |
| reactiemodus | optioneel | Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. Dit kan een van de volgende methoden zijn: - query - fragment - form_post query de code als een queryreeksparameter op uw omleidings-URI levert. Als u de code aanvraagt, kunt u query, fragment of form_post gebruiken.
form_post voert een POST uit die de code bevat naar uw omleidings-URI. |
| staat | optioneel | Een waarde die is opgenomen in de aanvraag die ook moet worden geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om vervalsingsaanvallen op meerdere sites te voorkomen. De waarde kan ook informatie coderen over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop deze zich bevonden. |
| aanmoediging | optioneel | Geeft het type gebruikersinteractie aan dat vereist is. De enige geldige waarden op dit moment zijn inloggen en geen. - prompt=login dwingen gebruikers hun referenties bij dat verzoek in te voeren, waardoor single sign-on wordt genegeerd.
- prompt=none werkt daarentegen zodat de gebruiker helemaal geen interactieve prompt te zien krijgt. Als het verzoek niet stilletjes kan worden voltooid via single sign-on, retourneert AD FS een interaction_required fout. |
| login-aanwijzing | optioneel | Kan worden gebruikt om het veld gebruikersnaam/e-mailadres van de aanmeldingspagina voor de gebruiker vooraf in te vullen als u de gebruikersnaam van tevoren kent. Apps gebruiken deze parameter vaak tijdens opnieuw verificatie, nadat de gebruikersnaam al is geëxtraheerd uit een vorige aanmelding met behulp van de claim upnuit id_token. |
| domein_hint | optioneel | Indien opgenomen, wordt het detectieproces op basis van een domein overgeslagen dat de gebruiker doorloopt op de aanmeldingspagina, wat leidt tot een iets gestroomlijndere gebruikerservaring. |
| code_challenge_method | optioneel | De methode die wordt gebruikt voor het coderen van de code_verifier voor de parameter code_challenge. Kan een van de volgende waarden zijn: - gewone - S256- Indien uitgesloten, wordt ervan uitgegaan dat code_challenge tekst zonder opmaak is als code_challenge is opgenomen. AD FS ondersteunt zowel gewone als S256. Zie de PKCE RFC voor meer informatie. |
| code-uitdaging | optioneel | Wordt gebruikt om autorisatiecode te beveiligen via Proof Key for Code Exchange (PKCE) van een systeemeigen client. Vereist als code_challenge_method is opgenomen. Zie de PKCE RFC- voor meer informatie |
Op dit moment wordt de gebruiker gevraagd om zijn referenties in te voeren en de verificatie te voltooien. Zodra de gebruiker wordt geverifieerd, retourneert de AD FS een antwoord naar uw app op de aangegeven redirect_uri, met behulp van de methode die is opgegeven in de response_mode parameter.
Succesvolle respons
Een geslaagd antwoord met behulp van response_mode=query ziet er als volgt uit:
GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Maatstaf | Beschrijving |
|---|---|
| code | De authorization_code die de app heeft aangevraagd. De app kan de autorisatiecode gebruiken om een toegangstoken aan te vragen voor de doelresource. Authorization_codes korte levensduur hebben, verlopen ze doorgaans na ongeveer 10 minuten. |
| staat | Als een state-parameter is opgenomen in de aanvraag, zou dezelfde waarde moeten verschijnen in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn. |
Een toegangstoken aanvragen
Nu je een authorization_code hebt verkregen en toestemming hebt gekregen van de gebruiker, kun je de code voor een access_token gebruiken om toegang te krijgen tot de gewenste resource. Wissel de code in door een POST-aanvraag naar het /token-eindpunt te verzenden:
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| toekennings_type | vereist | Moet authorization_code zijn voor de autorisatiecodestroom. |
| code | vereist | De authorization_code die u in het eerste deel van het proces hebt verkregen. |
| omleidings-URI | vereist | Dezelfde redirect_uri waarde die is gebruikt voor het verkrijgen van de authorization_code. |
| klantgeheim | vereist voor web-apps | Het toepassingsgeheim dat u hebt gemaakt tijdens de app-registratie in AD FS. U moet het toepassingsgeheim niet gebruiken in een systeemeigen app, omdat client_secrets niet betrouwbaar kunnen worden opgeslagen op apparaten. Het is vereist voor web-apps en web-API's, die de mogelijkheid hebben om de client_secret veilig op te slaan aan de serverzijde. Het clientgeheim moet url-gecodeerd zijn voordat het wordt verzonden. Deze apps kunnen ook gebruikmaken van een verificatie op basis van sleutels door een JWT te ondertekenen en deze toe te voegen als client_assertion parameter. |
| code_verifier | optioneel | Hetzelfde code_verifier dat is gebruikt om de authorization_code te verkrijgen. Vereist als PKCE is gebruikt in de toekenningsaanvraag van de autorisatiecode. Zie de PKCE RFC voor meer informatie. Deze optie is van toepassing op AD FS 2019 en hoger |
Succesvolle respons
Een geslaagd tokenantwoord ziet er als volgt uit:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Maatstaf | Beschrijving |
|---|---|
| toegangstoken | Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde resource (web-API). |
| token_type | Geeft de waarde van het tokentype aan. Het enige type dat AD FS ondersteunt, is Bearer. |
| expires_in | Hoe lang het toegangstoken geldig is, in seconden. |
| refresh_token | Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om meer toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Refresh_tokens lange levensduur hebben en kunnen worden gebruikt om de toegang tot resources gedurende langere tijd te behouden. |
| refresh_token_expires_in | Hoe lang het vernieuwingstoken geldig is (in seconden). |
| id_token | Een JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. |
Het toegangstoken gebruiken
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Stroom voor het verlenen van tokens vernieuwen
Access_tokens korte levensduur hebben en u moet ze vernieuwen nadat ze verlopen om toegang te blijven krijgen tot resources. U kunt dit doen door een andere POST-aanvraag in te dienen bij het /token-eindpunt. Dit keer geeft u de refresh_token op in plaats van de code. Vernieuwingstokens zijn geldig voor alle machtigingen waarvoor uw client al toegangstokens heeft ontvangen.
Vernieuwingstokens hebben geen bepaalde levensduur. Normaal gesproken zijn de levensduur van vernieuwingstokens relatief lang. In sommige gevallen verlopen verversingstokens echter, worden ze ingetrokken of hebben ze niet voldoende bevoegdheden voor de gewenste actie. Uw toepassing moet correct verwachten en afhandelen van fouten die door het tokenuitgifte-eindpunt worden geretourneerd.
Hoewel vernieuwingstokens niet worden ingetrokken bij het verkrijgen van nieuwe toegangstokens, wordt verwacht dat u het oude vernieuwingstoken negeert. Volgens de OAuth 2.0-specificatie staat: 'De autorisatieserver kan een nieuw vernieuwingstoken uitgeven. In dat geval moet de client het oude vernieuwingstoken negeren en vervangen door het nieuwe vernieuwingstoken. De autorisatieserver kan het oude vernieuwingstoken intrekken nadat een nieuw vernieuwingstoken aan de client is uitgegeven. AD FS geeft een vernieuwingstoken uit wanneer de levensduur van het nieuwe vernieuwingstoken langer is dan de levensduur van het vorige vernieuwingstoken. Als u aanvullende informatie wilt bekijken over de levensduur van het AD FS-vernieuwingstoken, gaat u naar AD FS-instellingen voor eenmalige aanmelding.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| toewijzingstype | vereist | Moet refresh_token zijn voor dit deel van de autorisatiecodestroom. |
| hulpbron | optioneel | De URL van uw web-API. Opmerking: als u msal-clientbibliotheek gebruikt, wordt de resourceparameter niet verzonden. In plaats daarvan wordt de resource-URL verzonden als onderdeel van de bereikparameter: scope = [resource url]//[scope values e.g., openid]Als de resource hier of in het bereik niet wordt doorgegeven, gebruikt AD FS een standaardresource urn:microsoft:userinfo. Het gebruikersinformatiebronbeleid, zoals MFA, uitgifte- of autorisatiebeleid, kan niet worden aangepast. |
| omvang | optioneel | Een door spaties gescheiden lijst van scopes. |
| vernieuw_token | vereist | De refresh_token die u in de tweede fase van het proces verkreeg. |
| klantgeheim | vereist voor web-apps | Het toepassingsgeheim dat u hebt gemaakt in de app-registratieportal voor uw app. Deze mag niet worden gebruikt in een systeemeigen app, omdat client_secrets niet betrouwbaar kunnen worden opgeslagen op apparaten. Het is vereist voor web-apps en web-API's, die de mogelijkheid hebben om de client_secret veilig op te slaan aan de serverzijde. Deze apps kunnen ook gebruikmaken van een verificatie op basis van sleutels door een JWT te ondertekenen en deze toe te voegen als client_assertion parameter. |
Succesvolle respons
Een geslaagd antwoord op een token ziet er als volgt uit:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Maatstaf | Beschrijving |
|---|---|
| toegangstoken | Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde resource, zoals een web-API. |
| token_type | Geeft de waarde van het tokentype aan. Het enige type dat AD FS ondersteunt, is Bearer |
| verloopt_in | Hoe lang het toegangstoken geldig is, in seconden. |
| omvang | De scopen waarvoor de access_token geldig is. |
| vernieuw_token (refresh_token) | Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om meer toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Refresh_tokens lange levensduur hebben en kunnen worden gebruikt om de toegang tot resources gedurende langere tijd te behouden. |
| vernieuwings_token_verloopt_over | Hoe lang het ververstoken geldig is (in seconden). |
| id_token | Een JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. |
Ondersteuning voor Proof Key for Code Exchange (PKCE) voor OAuth
OAuth-openbare clients die gebruikmaken van de autorisatiecodetoekenning zijn kwetsbaar voor onderscheppingsaanvallen van autorisatiecode, zoals beschreven in RFC 7636-. Om deze aanvallen te beperken, ondersteunt AD FS vanaf Windows Server 2019 nu Proof Key for Code Exchange (PKCE) voor de stroom OAuth Authorization Code Grant.
De PKCE-ondersteuningsspecificatie voegt meer parameters toe aan de OAuth 2.0-autorisatie- en toegangstokenaanvragen. In het volgende diagram ziet u een visueel overzicht van het PKCE-proces wanneer een client AD FS in Windows Server 2019 gebruikt.
In de sectie met het label A maakt en registreert de client een geheim met de naam code_verifier en wordt een getransformeerde versie van het geheim met de naam t(code_verifier)afgeleid, ook wel bekend als code_challenge. De client verzendt vervolgens het geheim in de OAuth 2.0-autorisatieaanvraag samen met de t_m transformatiemethode.
In de sectie met het label B reageert het autorisatie-eindpunt zoals gebruikelijk, maar registreert het t(code_verifier) geheim en de transformatiemethode.
In de sectie met het label C verzendt de client vervolgens de autorisatiecode in de aanvraag voor het toegangstoken zoals gebruikelijk, maar bevat het code_verifier geheim dat is gegenereerd in sectie A.
In de sectie met het label D transformeert AD FS het code_verifiergeheim en vergelijkt het met het t(code_verifier) geheim uit sectie B. Als hun waarden niet gelijk zijn, weigert AD FS de toegang.
Meerdere authenticatieproviders kiezen voor dezelfde beleidsregel in Windows Server 2019
AD FS biedt al ondersteuning voor het activeren van extra verificatie op basis van een claimregelbeleid (RP). Met deze beleidsregels kunt u deze instellen voor een bepaalde RP of op globaal niveau. U kunt een extra verificatiebeleid voor een bepaalde RP instellen door PowerShell als beheerder te openen en de cmdlet Set-AdfsRelyingPartyTrust uit te voeren door de parameter AdditionalAuthenticationRules of AdditionalAuthenticationRulesFile door te geven. Als u deze globaal wilt instellen, kan een beheerder de cmdlet Set-AdfsAdditionalAuthenticationRule gebruiken. Als u extra beleidsregels instelt, kunt u meer dan één verificatieprovider gebruiken voor dezelfde toepassing.
Claimregels bieden de mogelijkheid om de verificatieprovider te selecteren voor aanvullende verificatie, wat nuttig is in situaties waarin klanten schakelen tussen providers of een afzonderlijke provider vereisen voor bepaalde toepassingen. Vanaf Windows Server 2019 kunt u nu claimregels gebruiken om te bepalen welke andere verificatieprovider moet worden aangeroepen voor extra verificatie. Deze functie is handig voor twee scenario's:
Gebruikers overstappen van een andere verificatieprovider naar een andere. Wanneer u gebruikers onboardt naar een nieuwere verificatieprovider, kunnen ze groepen gebruiken om te bepalen welke extra verificatieprovider de service gebruikt.
Gebruikers hebben een specifieke extra verificatieprovider nodig voor bepaalde toepassingen, maar moeten ook een andere methode gebruiken voor andere toepassingen.
U kunt deze instellingen configureren door de volgende opdracht uit te voeren vanuit ander verificatiebeleid:
Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );'
Als u deze regel wilt instellen, moet u de claim http://schemas.microsoft.com/claims/authnmethodsproviders van andere verificatiebeleidsregels uitgeven. De waarde van deze claim moet de Naam variabele van de verificatieprovider zijn.
U kunt deze regelconfiguratie ook wijzigen zodat gebruikers van de ene verificatieprovider naar de andere kunnen overstappen. Stel dat u één groep wilt wijzigen die u beheert voor het gebruik van Azure AD MFA en één groep voor het gebruik van certificaten als extra verificatieprovider.
Als u wilt bijhouden hoeveel personen zich registreren voor Azure AD MFA en certificaatverificatie, voert u een opdracht als volgt uit en vervangt u de waarden met de waarden die relevant zijn voor uw organisatie:
'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-608905689-872870963-3921916988-12345"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");
not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value=="S-1-5-21-608905689-872870963-3921916988-12345"]) => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");’
Vervolgens kunt u de eerste toepassing, AppAgenoemd, instellen om Azure AD Multi-Factor Authentication als extra verificatieprovider te gebruiken door deze opdracht uit te voeren:
Set-AdfsRelyingPartyTrust -TargetName AppA -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");'
Ten slotte kunt u de tweede app, genaamd AppB, instellen om Certificaat als extra verificatieprovider te gebruiken door deze opdracht uit te voeren:
Set-AdfsRelyingPartyTrust -TargetName AppB -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");'
Beheerders kunnen ook regels maken om meer dan één extra verificatieprovider toe te staan. In dit geval toont AD FS de uitgegeven verificatiemethoden providers, en een gebruiker kan een van hen kiezen. Als u meerdere extra verificatieproviders wilt toestaan, moeten ze meerdere claims uitgeven met behulp van de waarde http://schemas.microsoft.com/claims/authnmethodsproviders.
Als de claimevaluatie geen van de verificatieproviders retourneert, wordt AD FS teruggedraaid en wordt een lijst weergegeven met alle extra verificatieproviders die zijn geconfigureerd door de beheerder op AD FS. De gebruiker moet vervolgens handmatig de juiste verificatieprovider selecteren.
Als uw voorkeursverificatieprovider zich niet in de lijst bevindt, kunt u de volgende cmdlet uitvoeren om alle ondersteunde providers weer te geven:
(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
De waarde die u gebruikt voor de http://schemas.microsoft.com/claims/authnmethodsproviders claim moet een van de providernamen zijn die worden geretourneerd door de lijst met providers die door AD FS is geretourneerd.
AD FS biedt geen ondersteuning voor het activeren van een bepaalde extra verificatieprovider terwijl de RP gebruikmaakt van toegangsbeheerbeleid in AD FS Windows Server 2016. Wanneer u een toepassing uit een toegangsbeheerbeleid verplaatst, kopieert AD FS het bijbehorende beleid van Access Control Policy naar AdditionalAuthenticationRules en IssuanceAuthorizationRules. Als een beheerder een specifieke verificatieprovider wil gebruiken, moet deze het toegangsbeheerbeleid stoppen en in plaats daarvan AdditionalAuthenticationRuleswijzigen.
Stroom aanBehalf-Of
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie On-Behalf-Of flow in Microsoft Identity Platformvoor meer informatie over de on-Behalf-Of stroom in Microsoft Entra ID.
De OAuth 2.0 On-Behalf-Of flow (OBO) dient de use case waarbij een toepassing een service/web-API aanroept, die op zijn beurt een andere service/web-API moet aanroepen. Het idee is om de gedelegeerde gebruikersidentiteit en machtigingen door te geven via de aanvraagketen. Voor de middellaagservice om geauthentiseerde verzoeken naar de downstream-service te kunnen doen, moet het een toegangstoken verkrijgen van de AD FS namens de gebruiker.
Protocolschema
Stel dat de gebruiker is geverifieerd voor een toepassing met behulp van de OAuth 2.0-autorisatiecodestroom die in de vorige sectie is beschreven. Op dit moment heeft de toepassing een toegangstoken voor API A (token A) met de claims van de gebruiker en toestemming voor toegang tot de web-API (API A) in de middelste laag. Zorg ervoor dat de client de user_impersonation scope in het token aanvraagt. API A moet nu een geverifieerde aanvraag indienen bij de downstream web-API (API B).
De volgende stappen vormen de OBO-stroom en worden uitgelegd met behulp van het volgende diagram.
- De klanttoepassing doet een aanvraag naar API A met token A. Opmerking: tijdens het configureren van de OBO-stroom in AD FS moet u ervoor zorgen dat bereik
user_impersonationis geselecteerd en dat de klant bereikuser_impersonationvraagt in de aanvraag. - API A wordt geverifieerd bij het eindpunt voor de uitgifte van het AD FS-token en vraagt een token aan om toegang te krijgen tot API B. Opmerking: zorg er tijdens het configureren van deze stroom in AD FS voor dat API A ook is geregistreerd als een servertoepassing met clientID met dezelfde waarde als de resource-id in API A.
- Het eindpunt voor de uitgifte van het AD FS-token valideert de referenties van API A met token A en geeft het toegangstoken voor API B (token B) uit.
- Token B wordt ingesteld in de autorisatieheader van de aanvraag naar API B.
- Gegevens van de beveiligde resource worden geretourneerd door API B.
Service-to-service-toegangstokenaanvraag
Als u een toegangstoken wilt aanvragen, maakt u een HTTP POST naar het AD FS-tokeneindpunt met de volgende parameters.
Eerste geval: Toegangstokenaanvraag met een gedeeld geheim
Voor een gedeeld geheim bevat een service-to-service-toegangstokenaanvraag de volgende parameters:
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| grant_type | vereist | Het type van token aanvraag. Voor een aanvraag met behulp van een JWT moet de waarde urn:ietf:params:oauth:grant-type:jwt-bearer zijn. |
| client-id | vereist | De client-id die u configureert bij het registreren van uw eerste web-API als een server-app (app in de middelste laag). Dit moet hetzelfde zijn als de Resource-ID die in het eerste deel wordt gebruikt, dat wil zeggen de URL van de eerste Web-API. |
| klantgeheim | vereist | Het toepassingsgeheim dat u hebt gemaakt tijdens de registratie van de server-app in AD FS. |
| bewering | vereist | De waarde van het token dat in de aanvraag wordt gebruikt. |
| aangevraagd_token_gebruik | vereist | Hiermee geeft u op hoe de aanvraag moet worden verwerkt. In de OBO-stroom moet de waarde worden ingesteld op on_behalf_of |
| hulpbron | vereist | De resource-id die is opgegeven tijdens het registreren van de eerste web-API als de server-app (app in de middelste laag). De resource-id moet de URL zijn van de tweede web-API-app-aanroepen in de middelste laag namens de client. |
| omvang | optioneel | Een door spaties gescheiden lijst met bereiken voor de tokenaanvraag. |
Voorbeeld
De volgende HTTP POST vraagt een toegangstoken en verversingstoken aan
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
Tweede geval: Toegangstokenaanvraag met een certificaat
Een service-naar-service-toegangstokenaanvraag met een certificaat bevat de volgende parameters:
| Maatstaf | vereist/optioneel | Beschrijving |
|---|---|---|
| grant_type | vereist | Het type tokenaanvraag. Voor een aanvraag met behulp van een JWT moet de waarde urn:ietf:params:oauth:grant-type:jwt-bearer zijn. |
| client-id | vereist | De client-id die u configureert bij het registreren van uw eerste web-API als een server-app (app in de middelste laag). Dit moet hetzelfde zijn als de resource-id die in de eerste fase wordt gebruikt, de URL van de eerste web-API. |
| client_assertion_type | vereist | De waarde moet urn:ietf:params:oauth:client-assertion-type:jwt-bearer zijn. |
| client_assertion | vereist | Een assertie (een JSON-webtoken) die u moet maken en ondertekenen met het certificaat dat u hebt geregistreerd als referenties voor uw toepassing. |
| bewering | vereist | De waarde van het token dat in de aanvraag wordt gebruikt. |
| aangevraagd_token_gebruik | vereist | Hiermee geeft u op hoe de aanvraag moet worden verwerkt. In de OBO-stroom moet de waarde worden ingesteld op on_behalf_of |
| hulpbron | vereist | De resource-id die is opgegeven tijdens het registreren van de eerste web-API als de server-app (app in de middelste laag). De resource-id moet de URL zijn van de tweede web-API-app-aanroepen in de middelste laag namens de client. |
| omvang | optioneel | Een door spaties gescheiden lijst van toegangsgebieden voor de token-aanvraag. |
U ziet dat de parameters bijna hetzelfde zijn. Dit voorbeeld is vergelijkbaar met het verzoek met behulp van een gedeeld geheim, behalve dat de parameter client_secret wordt vervangen door twee parameters: client_assertion_type en client_assertion.
Voorbeeld
De volgende HTTP POST vraagt een toegangstoken voor de web-API aan met een certificaat.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
Antwoord van service-to-servicetoegangstoken
Een geslaagd antwoord is een JSON OAuth 2.0-antwoord met de volgende parameters.
| Maatstaf | Beschrijving |
|---|---|
| token_type | Geeft de waarde van het tokentype aan. Het enige type dat AD FS ondersteunt, is Bearer. |
| omvang | Het toegangsbereik dat in het token wordt verleend. |
| verloopt_in | De tijdsduur, in seconden, dat het toegangstoken geldig is. |
| toegangstoken | Het aangevraagde toegangstoken. De aanroepende service kan dit token gebruiken om te verifiëren bij de ontvangende service. |
| id_token | Een JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. |
| refresh_token | Het refresh-token voor het aangevraagde toegangstoken. De aanroepende service kan dit token gebruiken om een ander toegangstoken aan te vragen nadat het huidige toegangstoken is verlopen. |
| Refresh_token_expires_in | De duur, in seconden, dat de vernieuwingssleutel geldig is. |
Voorbeeld van geslaagd antwoord
In het volgende voorbeeld ziet u een geslaagd antwoord op een aanvraag voor een toegangstoken voor de web-API.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
Gebruik het toegangstoken om toegang te krijgen tot de beveiligde resource Nu kan de service in de middelste laag het token gebruiken dat is verkregen in het vorige antwoordvoorbeeld om geverifieerde aanvragen naar de downstream-web-API te maken door het token in de autorisatieheader in te stellen.
Voorbeeld
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
Stroom voor het verlenen van clientreferenties
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie voor meer informatie over de stroom voor het verlenen van clientreferenties in Microsoft Entra ID Stroom voor het verlenen van clientreferenties in het Microsoft Identity Platform.
U kunt de OAuth 2.0-clientreferenties verlenen die zijn opgegeven in RFC 6749-, voor toegang tot door het web gehoste resources met behulp van de identiteit van een toepassing. Dit type toekenning wordt vaak gebruikt voor server-naar-server-interacties die op de achtergrond moeten worden uitgevoerd, zonder directe interactie met een gebruiker. Deze typen toepassingen worden vaak daemons of serviceaccounts genoemd.
Met de OAuth 2.0-clientverificatiestroom kan een webservice (vertrouwelijke client) gebruik maken van zijn eigen referenties in plaats van een gebruiker te vertegenwoordigen, om zich te verifiëren wanneer een andere webservice wordt aangeroepen. In dit scenario is de client doorgaans een webservice in de middelste laag, een daemonservice of een website. Voor een hoger niveau van zekerheid staat de AD FS ook de aanroepende service toe om een certificaat te gebruiken (in plaats van een gedeeld geheim) als referentie.
Protocolschema
In het volgende diagram ziet u de clientcredentials-toekenningsstroom.
Een token aanvragen
Als u een token wilt ophalen met behulp van de clientreferenties verlenen, verzendt u een POST aanvraag naar het /token AD FS-eindpunt:
Eerste geval: Toegangstokenaanvraag met een gedeeld geheim
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| omvang | optioneel | Een door spaties gescheiden lijst met bereiken waarvoor de gebruiker toestemming moet geven. |
| klantgeheim | vereist | Het clientgeheim dat u hebt gegenereerd voor uw app in de portal voor app-registratie. Het clientgeheim moet url-gecodeerd zijn voordat het wordt verzonden. |
| toewijzingstype | vereist | Moet worden ingesteld op client_credentials. |
Tweede geval: Toegangstokenaanvraag met een certificaat
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client_assertion_type | vereist | De waarde moet worden ingesteld op urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| cliënt_assertie | verplicht | Een assertie (een JSON-webtoken) die u moet maken en ondertekenen met het certificaat dat u hebt geregistreerd als referenties voor uw toepassing. |
| grant_type | vereist | Moet worden ingesteld op client_credentials. |
| client-id | optioneel | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. Het maakt deel uit van client_assertion, dus het is niet vereist om hier door te geven. |
| omvang | optioneel | Een door spaties gescheiden lijst met toestemmingen waarvoor de gebruiker toestemming moet geven. |
Een token gebruiken
Nu u een token hebt verkregen, gebruikt u het token om aanvragen naar de resource te verzenden. Wanneer het token verloopt, herhaalt u de aanvraag naar het /token-eindpunt om een nieuw toegangstoken te verkrijgen.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Toekenningsproces van wachtwoordreferenties voor resource-eigenaar (niet aanbevolen)
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie Toekennen van wachtwoordreferenties aan de resource-eigenaar in Microsoft Entra ID voor meer informatie over de gebruikersaanmeldingsstroom in het Microsoft Identity Platform.
Met ROPC (Resource Owner Password Credential) kan een toepassing de gebruiker aanmelden door hun wachtwoord rechtstreeks te verwerken. De ROPC-stroom vereist een hoge mate van vertrouwen en gebruikersblootstelling en u moet deze stroom alleen gebruiken wanneer andere, veiligere stromen niet kunnen worden gebruikt.
Protocolschema
In het volgende diagram ziet u de ROPC-stroom.
Autorisatieaanvraag
De ROPC-stroom is één aanvraag. De clientidentificatie en gebruikersreferenties worden naar de IDP verzonden en ontvangen vervolgens tokens als resultaat. De client moet het e-mailadres (UPN) en wachtwoord van de gebruiker aanvragen voordat u dit doet. Onmiddellijk na een geslaagde aanvraag moet de cliënt de inloggegevens van de gebruiker veilig vrijgeven uit het geheugen. Het mag ze nooit redden.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| Maatstaf | Vereist/optioneel | Beschrijving |
|---|---|---|
| client-id | vereist | Klant-ID |
| soort_toestemming | vereist | Moet op wachtwoord worden ingesteld. |
| gebruikersnaam | vereist | Het e-mailadres van de gebruiker. |
| wachtwoord | vereist | Het wachtwoord van de gebruiker. |
| omvang | optioneel | Een door spaties gescheiden lijst van scopes. |
Geslaagde verificatiereactie
Het volgende voorbeeld toont een succesvolle token response.
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| Maatstaf | Beschrijving |
|---|---|
| token_type | Altijd ingesteld op Bearer. |
| omvang | Als er een toegangstoken is geretourneerd, geeft deze parameter de bereiken weer waarvoor het toegangstoken geldig is. |
| verloopt_in | Het aantal seconden waarvoor het opgenomen toegangstoken geldig is. |
| toegangstoken | Verleend voor de reikwijdten die zijn aangevraagd. |
| id_token | Een JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. |
| refresh_token_expires_in | Het aantal seconden waarvoor het inbegrepen ververstoken geldig is. |
| refresh_token | Uitgegeven als de oorspronkelijke bereikparameter offline_access bevat. |
U kunt het vernieuwingstoken gebruiken om nieuwe toegangstokens te verkrijgen en tokens te vernieuwen met behulp van dezelfde stroom die wordt beschreven in de sectie voor het verlenen van verificatiecode van dit artikel.
Apparaatcodeproces
Notitie
Microsoft raadt ten zeerste aan om te migreren naar Microsoft Entra ID in plaats van een upgrade uit te voeren naar een nieuwere AD FS-versie. Zie Apparaatcodestroom in microsoft-identiteitsplatformvoor meer informatie over apparaatcodestroom in Microsoft Entra ID.
Met apparaatcode-verlening kunnen gebruikers inloggen op invoer-beperkte apparaten, zoals een smart TV, IoT-apparaat of printer. Als u deze flow wilt inschakelen, laat het apparaat de gebruiker een webpagina bezoeken in de browser van een ander apparaat om in te loggen. Zodra de gebruiker zich heeft aangemeld, kan het apparaat toegangstokens ophalen en tokens vernieuwen als dat nodig is.
Protocolschema
De volledige apparaatcodestroom ziet er ongeveer uit als in het volgende diagram. We beschrijven elk van de stappen verderop in dit artikel.
Aanvraag voor apparaatautorisatie
De klant moet eerst bij de authenticatieserver informeren naar een apparaat en gebruikerscode die gebruikt worden om de authenticatie te initiëren. De client verzamelt deze aanvraag vanaf het /devicecode-eindpunt. In deze aanvraag moet de client ook de machtigingen vermelden die van de gebruiker moeten worden verkregen. Vanaf het moment dat deze aanvraag wordt verzonden, heeft de gebruiker slechts 15 minuten om zich aan te melden (de gebruikelijke waarde voor expires_in), dus dien deze aanvraag alleen in wanneer de gebruiker heeft aangegeven dat ze klaar zijn om zich aan te melden.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
scope=openid
| Maatstaf | Conditie | Beschrijving |
|---|---|---|
| client-id | vereist | De toepassings-id (client) die de AD FS heeft toegewezen aan uw app. |
| omvang | optioneel | Een door spaties gescheiden lijst van scopes. |
Antwoord voor apparaatautorisatie
Een geslaagd antwoord is een JSON-object met de vereiste informatie waarmee de gebruiker zich kan aanmelden.
| Maatstaf | Beschrijving |
|---|---|
| apparaatcode | Een lange tekenreeks die wordt gebruikt om de sessie tussen de client en de autorisatieserver te verifiëren. De client gebruikt deze parameter om het toegangstoken aan te vragen van de autorisatieserver. |
| user_code | Een korte tekenreeks die wordt weergegeven aan de gebruiker die wordt gebruikt om de sessie op een secundair apparaat te identificeren. |
| verification_uri | De URI waar de gebruiker naartoe moet gaan met de user_code om u aan te melden. |
| verificatie_uri_voltooid | De URI waar de gebruiker naartoe moet gaan met de user_code om u aan te melden. Het is vooraf gevuld met user_code, zodat de gebruiker geen user_code hoeft in te voeren |
| verloopt_in | Het aantal seconden voordat de device_code en user_code verlopen. |
| interval | Het aantal seconden dat de client moet wachten tussen polling-aanvragen. |
| bericht | Een door mensen leesbare tekenreeks met instructies voor de gebruiker. Het kan worden gelokaliseerd door een queryparameter op te geven in de aanvraag van het formulier ?mkt=xx-XX, waarbij de juiste taalcultuurcode wordt ingevuld. |
De gebruiker verifiëren
Nadat de client de user_code en verification_uri heeft ontvangen, worden deze gegevens aan de gebruiker weergegeven, zodat ze zich kunnen aanmelden met hun mobiele telefoon of pc-browser. Daarnaast kan de client een QR-code of een vergelijkbaar mechanisme gebruiken om de verfication_uri_complete weer te geven, die de stap neemt van het invoeren van de user_code voor de gebruiker.
Terwijl de gebruiker bij de verification_uri verificatie uitvoert, moet de client het /token-eindpunt voor het aangevraagde token peilen met behulp van de device_code.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 00001111-aaaa-2222-bbbb-3333cccc4444
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| Maatstaf | vereist | Beschrijving |
|---|---|---|
| grant_type | vereist | Moet urn:ietf:params:oauth:grant-type:device_code zijn |
| client-id | vereist | Moet overeenkomen met de client_id die in de aanvankelijke aanvraag wordt gebruikt. |
| code | vereist | De "device_code" die is geretourneerd bij het autorisatieverzoek van het apparaat. |
Geslaagde verificatiereactie
Een geslaagd tokenantwoord ziet er als volgt uit:
| Maatstaf | Beschrijving |
|---|---|
| token_type | Altijd "Bearer". |
| omvang | Als er een toegangstoken is geretourneerd, worden de scopes vermeld waarvoor het toegangstoken geldig is. |
| verloopt_in | Aantal seconden voordat een inbegrepen toegangstoken geldig is. |
| toegangstoken | Toegekend voor de omvangen die zijn aangevraagd. |
| id_token | Uitgegeven als de oorspronkelijke bereikparameter het openid-bereik bevat. |
| refresh_token | Uitgegeven als de oorspronkelijke bereikparameter offline_access bevat. |
| refresh_token_expires_in | Aantal seconden waarvoor het meegeleverde vernieuwingstoken geldig is. |
Verwante inhoud
Zie AD FS Development voor de volledige lijst met artikelen, die stapsgewijze instructies bieden voor het gebruik van de gerelateerde stromen.