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. Gebruik indien mogelijk in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) om tokens te verkrijgen en beveiligde web-API's aan te roepen. Bekijk ook de voorbeeld-apps die MSAL gebruiken.

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

  • De Microsoft identity platform ondersteunt alleen de ROPC-toekenning binnen Azure AD 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 Azure AD-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 nodig hebben, gebruikt u een ander toekenningstype dan ROPC.
  • Als gebruikers meervoudige verificatie (MFA) moeten gebruiken om zich aan te melden bij de toepassing, worden ze in plaats daarvan geblokkeerd.
  • ROPC wordt niet ondersteund in hybride identiteitsfederatiescenario's (bijvoorbeeld Azure AD en ADFS die worden gebruikt om on-premises accounts te verifiëren). Als gebruikers op de volledige pagina worden omgeleid naar een on-premises id-provider, kan Azure AD 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 hybride identiteitsfederatiescenario 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.

Tip

Voer deze aanvraag uit in Postman
Voer deze aanvraag en meer uit in Postman, en vergeet niet om tokens en id's te vervangen.

Protocoldiagram

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

Diagram met de stroom voor wachtwoord van broneigenaar

Autorisatieaanvraag

De ROPC-stroom is één aanvraag; het verzendt de clientidentificatie en de referenties van de gebruiker naar de id-provider en ontvangt 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 client de referenties van de gebruiker veilig verwijderen uit het geheugen. 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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-ID) die door de pagina App-registraties van Azure Portal is 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.

Waarschuwing

Als onderdeel van het niet aanbevelen van deze stroom voor gebruik, ondersteunen de officiële SDK's deze stroom niet voor vertrouwelijke clients, degenen die een geheim of assertie gebruiken. Mogelijk kunt u met de SDK die u wilt gebruiken, geen geheim toevoegen tijdens het gebruik van ROPC.

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 Indeling Beschrijving
token_type Tekenreeks 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.

Foutreacties

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.

Lees meer

Zie het codevoorbeeld van de .NET Core-consoletoepassing op GitHub voor een voorbeeldimplementatie van de ROPC-stroom.