Wachtwoordreferenties voor het Microsoft-identiteitsplatform en de OAuth 2.0-broneigenaar

Het Microsoft-identiteitsplatform ondersteunt het verlenen van de wachtwoordreferenties van de OAuth 2.0-broneigenaar (ROPC), waardoor een toepassing zich kan aanmelden bij de gebruiker door diens wachtwoord rechtstreeks te verwerken. In dit artikel wordt beschreven hoe u rechtstreeks kunt programmeren op basis van het protocol in uw toepassing. Indien mogelijk raden we u aan om in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken om tokens te verkrijgen en beveiligde web-API's aan te roepen. Bekijk ook de voorbeeld-apps die gebruikmaken van MSAL.

Waarschuwing

Microsoft raadt u aan de ROPC-stroom niet te gebruiken. In de meeste scenario's zijn veiligere alternatieven beschikbaar en aanbevolen. Deze stroom vereist een zeer hoge mate van vertrouwen in de toepassing en draagt risico's die niet aanwezig zijn in andere stromen. U moet deze stroom alleen gebruiken wanneer andere veiligere stromen niet haalbaar zijn.

Belangrijk

• Het Microsoft Identity Platform ondersteunt alleen de ROPC-toekenning binnen Microsoft Entra-tenants, niet persoonlijke accounts. Dit betekent dat u een tenant-specifiek eindpunt moet gebruiken (https://login.microsoftonline.com/{TenantId_or_Name}) of het eindpunt van organizations.
• Persoonlijke accounts die zijn uitgenodigd voor een Microsoft Entra-tenant kunnen de ROPC-stroom niet gebruiken.
• Accounts die geen wachtwoorden hebben, kunnen zich niet aanmelden met ROPC. Dit betekent dat functies zoals sms-aanmelding, FIDO en de Authenticator-app niet met die stroom werken. Als uw app of gebruikers deze functies vereisen, gebruikt u een ander toekenningstype dan ROPC.
• Als gebruikers meervoudige verificatie (MFA) moeten gebruiken om zich aan te melden bij de toepassing, worden ze geblokkeerd.
• ROPC wordt niet ondersteund in hybride identiteitsfederatiescenario's (bijvoorbeeld Microsoft Entra ID en AD FS die worden gebruikt voor het verifiëren van on-premises accounts). Als gebruikers op de volledige pagina worden omgeleid naar een on-premises id-provider, kan Microsoft Entra ID de gebruikersnaam en het wachtwoord niet testen op basis van die id-provider. Passthrough-verificatie wordt echter wel ondersteund met ROPC.
• Een uitzondering op een scenario voor hybride identiteitsfederatie is het volgende: Home Realm Discovery-beleid waarbij AllowCloudPasswordValidation is ingesteld op TRUE, zorgt ervoor dat ROPC-stroom werkt voor federatieve gebruikers wanneer een on-premises wachtwoord wordt gesynchroniseerd met de cloud. Zie Directe ROPC-verificatie van gefedereerde gebruikers inschakelen voor oude toepassingen voor meer informatie.
• Wachtwoorden met voorloop- of volgspaties worden niet ondersteund door de ROPC-stroom.

Protocoldiagram

In het volgende diagram is de ROPC-stroom te zien.

Autorisatieaanvraag

De ROPC-stroom is één aanvraag; het verzendt de clientidentificatie en de referenties van de gebruiker naar de id-provider en ontvangt tokens in ruil. De client moet het e-mailadres (UPN) en wachtwoord van de gebruiker aanvragen voordat u dit doet. Onmiddellijk na een geslaagde aanvraag moet de client de referenties van de gebruiker veilig uit het geheugen verwijderen. Het mag deze nooit opslaan.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

Parameter	Voorwaarde	Beschrijving
tenant	Vereist	De map-tenant waarin u de gebruiker wilt aanmelden. De tenant kan een GUID- of beschrijvende naamindeling hebben. De parameter kan echter niet worden ingesteld op common of consumers, maar kan worden ingesteld op organizations.
client_id	Vereist	De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties pagina toegewezen aan uw app.
grant_type	Vereist	Moet worden ingesteld op password.
username	Vereist	Het e-mailadres van de gebruiker.
password	Vereist	Het wachtwoord van de gebruiker.
scope	Aanbevolen	Een door spaties gescheiden lijst met bereiken of machtigingen die de app nodig heeft. In een interactieve stroom moet de beheerder of de gebruiker voor deze bereiken vooraf toestemming geven.
client_secret	Soms vereist	Als uw app een openbare client is, kunt u de client_secret app wel of client_assertion niet opnemen. Als de app een vertrouwelijke client is, moet deze worden opgenomen.
client_assertion	Soms vereist	Een andere vorm van client_secret, gegenereerd met een certificaat. Zie certificaatreferenties voor meer informatie.

Geslaagd verificatie-antwoord

In het volgende voorbeeld ziet u een geslaagd tokenantwoord:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parameter	Notatie	Beschrijving
token_type	String	Altijd instellen op Bearer.
scope	Door spaties gescheiden tekenreeksen	Als er een toegangstoken wordt geretourneerd, geeft deze parameter de bereiken weer waarvoor het toegangstoken geldig is.
expires_in	int	Het aantal seconden waarvoor het inbegrepen toegangstoken geldig is.
access_token	Ondoorzichtige tekenreeks	Uitgegeven voor de bereiken die zijn aangevraagd.
id_token	JWT	Uitgegeven als de oorspronkelijke scope-parameter het openid-bereik bevatte.
refresh_token	Ondoorzichtige tekenreeks	Uitgegeven als de oorspronkelijke scope-parameter offline_access bevatte.

U kunt het vernieuwingstoken gebruiken om nieuwe toegangstokens te verkrijgen en tokens te vernieuwen met dezelfde stroom die wordt beschreven in de OAuth Code-stroomdocumentatie.

Waarschuwing

Probeer geen tokens te valideren of te lezen voor een API waarvan u geen eigenaar bent, inclusief de tokens in dit voorbeeld, in uw code. Tokens voor Microsoft-services kunnen een speciale indeling gebruiken die niet wordt gevalideerd als een JWT, en kunnen ook worden versleuteld voor consumentengebruikers (Microsoft-account). Hoewel het lezen van tokens een handig hulpprogramma voor foutopsporing is en een leerfunctie heeft, hoeft u hier geen afhankelijkheden van te maken in uw code of uit te gaan van specifieke informatie over tokens die niet voor een API zijn die u beheert.

Foutrespons

Als de gebruiker niet de juiste gebruikersnaam of het juiste wachtwoord heeft opgegeven of als de client de aangevraagde toestemming niet heeft ontvangen, mislukt de verificatie.

Fout	Beschrijving	Clientactie
invalid_grant	De verificatie is mislukt	De referenties zijn onjuist of de client heeft geen toestemming voor de aangevraagde bereiken. Als de bereiken niet worden verleend, wordt er een consent_required fout geretourneerd. Om deze fout op te lossen, moet de client de gebruiker naar een interactieve prompt verzenden met behulp van een webweergave of browser.
invalid_request	De aanvraag is onjuist samengesteld	Het type toekenning wordt niet ondersteund voor de /common of /consumers verificatiecontexten. Gebruik in plaats daarvan /organizations of een tenant-id.

Meer informatie

Zie het codevoorbeeld van de .NET-consoletoepassing op GitHub voor een voorbeeld van een implementatie van de ROPC-stroom.