Delen via

Wachtwoordreferenties van de Microsoft Identity Platform en OAuth 2.0-resource-eigenaar

  • Artikel

Het Microsoft Identity Platform ondersteunt de OAuth 2.0 Resource Owner Password Credentials (ROPC), waarmee een toepassing de gebruiker kan aanmelden door hun wachtwoord rechtstreeks te verwerken. In dit artikel wordt beschreven hoe u rechtstreeks programma's kunt uitvoeren 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 niet de ROPC-stroom te gebruiken; dit is niet compatibel met meervoudige verificatie (MFA). 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 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 tenantspecifiek eindpunt (https://login.microsoftonline.com/{TenantId_or_Name}) of het organizations-eindpunt moet gebruiken.
  • Persoonlijke accounts die zijn uitgenodigd voor een Microsoft Entra-tenant kunnen geen gebruik maken van de ROPC-stroom.
  • Accounts die geen wachtwoorden hebben, kunnen zich niet aanmelden met ROPC, wat betekent dat functies zoals sms-aanmelding, FIDO en de Authenticator-app niet werken met die stroom. Als uw app of gebruikers deze functies vereisen, gebruikt u een ander toekenningstype dan ROPC.
  • Als gebruikers MFA- (Multi-Factor Authentication) moeten gebruiken om zich aan te melden bij de toepassing, worden ze in plaats daarvan geblokkeerd.
  • ROPC wordt niet ondersteund in hybride identiteitsfederatie scenario's (bijvoorbeeld Microsoft Entra-id en AD FS die worden gebruikt voor het verifiëren van on-premises accounts). Als gebruikers worden omgeleid naar een on-premises id-provider, kan Microsoft Entra ID de gebruikersnaam en het wachtwoord van die id-provider niet testen. passthrough-verificatie wordt echter ondersteund met ROPC.
  • Een uitzondering op een scenario voor federatie van hybride identiteiten is het volgende: Home Realm Discovery-beleid met AllowCloudPasswordValidation 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 federatieve gebruikers inschakelen voor verouderde toepassingenvoor meer informatie.
  • Wachtwoorden met voorloop- of volgspaties worden niet ondersteund door de ROPC-stroom.

Hoe te migreren weg van ROPC

Naarmate MFA vaker voorkomt, accepteren sommige Microsoft-web-API's alleen toegangstokens als ze aan de MFA-vereisten voldoen. Toepassingen en testplatformen die afhankelijk zijn van ROPC, worden vergrendeld. Microsoft Entra geeft het token niet uit of de resource weigert de aanvraag.

Als u ROPC gebruikt om tokens te verkrijgen om beveiligde downstream-API's aan te roepen, migreert u naar een strategie voor het verkrijgen van tokens.

Wanneer gebruikerscontext beschikbaar is

Als een eindgebruiker toegang moet hebben tot een resource, moet de clienttoepassing die namens hen handelt, een vorm van interactieve verificatie gebruiken. De eindgebruiker kan alleen worden gevraagd om MFA wanneer hierom wordt gevraagd in de browser.

  • Voor webtoepassingen:
  • Web-API's kunnen geen browser weergeven. In plaats daarvan moeten ze een uitdaging terugsturen naar de clienttoepassing. Zie Web-API's en uitdagende gebruikers in web-API'svoor meer informatie.
  • Desktoptoepassingen moeten gebruikmaken van verificatie op basis van broker. Brokers gebruiken verificatie op basis van browsers om MFA af te dwingen en een zo veilig mogelijke situatie te creëren.
  • Mobiele toepassingen moeten ook worden geconfigureerd voor verificatie op basis van broker (Authenticator, bedrijfsportal).

Wanneer gebruikerscontext niet beschikbaar is

Voorbeelden van scenario's waarbij er geen gebruikerscontext betrokken is, maar niet beperkt is tot:

  • Een script dat wordt uitgevoerd als onderdeel van een CI-pijplijn.
  • Een service die een resource namens zichzelf moet aanroepen, zonder gebruikersgegevens.

Toepassingsontwikkelaars moeten gebruikmaken van service-principalverificatie, die wordt geïllustreerd in de daemon-voorbeelden. MFA is niet van toepassing op service-principals.

Er zijn meerdere manieren om te authenticeren als een service principal.

  • Als uw app wordt uitgevoerd in de Azure-infrastructuur, gebruikt u Managed Identity. Beheerde identiteit elimineert de overhead van het onderhouden en roteren van geheimen en certificaten.
  • Als uw app wordt uitgevoerd op een systeem dat wordt beheerd door een andere OAuth2-compatibele id-provider, zoals GitHub, gebruikt u federatieve identiteitsreferenties.
  • Als u geen beheerde identiteit of een federatieve identiteit kunt gebruiken, gebruikt u een certificaatreferentie.

Waarschuwing

Gebruik geen service-principalverificatie wanneer een gebruikerscontext beschikbaar is. Alleen-app-toegang heeft inherente hoge privileges en verleent vaak tenantbrede toegang, waardoor een kwaadwillende mogelijk toegang heeft tot klantgegevens van elke gebruiker.

Protocolschema

In het volgende diagram ziet u de ROPC-stroom.

Diagram dat de stroom van inloggegevens van de resource-eigenaar toont

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 inloggegevens van de gebruiker veilig uit het geheugen verwijderen. Het mag ze nooit redden.

// 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=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password
Parameter Conditie Beschrijving
tenant Vereist De maptenant waarin u de gebruiker wilt aanmelden. De tenant kan in GUID- of vriendelijke naamformaat zijn. 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 het Microsoft Entra-beheercentrum - App-registraties pagina die 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 scopesof machtigingen die de app nodig heeft. In een interactief proces moet de beheerder of de gebruiker vooraf toestemming geven voor deze toegangsrechten.
client_secret Soms vereist Als uw app een openbare client is, kan de client_secret of client_assertion niet worden opgenomen. Als de app een vertrouwelijke client is, moet deze worden opgenomen.
client_assertion Soms vereist Een andere vorm van client_secret, gegenereerd met behulp van een certificaat. Zie certificaatreferentiesvoor meer informatie.

Geslaagde verificatiereactie

Het volgende voorbeeld toont een succesvolle token response.

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Parameter Formaat Beschrijving
token_type Snaar Altijd ingesteld op Bearer.
scope Door spaties gescheiden tekenreeksen Als er een toegangstoken is geretourneerd, geeft deze parameter de bereiken weer waarvoor het toegangstoken geldig is.
expires_in Int Het aantal seconden waarvoor het opgenomen toegangstoken geldig is.
access_token Ondoorzichtige tekenreeks Verleend voor de scope die zijn aangevraagd.
id_token JWT Uitgegeven als de oorspronkelijke scope parameter het openid bereik bevat.
refresh_token Ondoorzichtige tekenreeks Uitgegeven als de oorspronkelijke scope parameter offline_accessbevat.

U kunt het vernieuwingstoken gebruiken om nieuwe toegangstokens en vernieuwingstokens te verkrijgen met behulp van dezelfde stroom die wordt beschreven in de documentatie van de OAuth-codestroom.

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 gebruikmaken van een speciale indeling die niet als JWT wordt gevalideerd en die ook kan worden versleuteld voor consumentengebruikers (Microsoft-account). Hoewel het lezen van tokens een nuttige tool voor debugging en leren is, neem hiervan geen afhankelijkheden in uw code of neem aan dat er specifieke informatie is over tokens die niet voor een API zijn die u beheert.

Foutreactie

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 inloggegevens zijn onjuist of de cliënt heeft geen toestemming voor de aangevraagde toegangsgebieden. Als de bereiken niet worden verleend, wordt er een consent_required foutmelding 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 toekenningstype wordt niet ondersteund voor de /common of /consumers verificatiecontexten. Gebruik in plaats daarvan /organizations of een tenant-id.

Meer informatie

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