Microsofts identitetsplattform och flöde för OAuth 2.0-klientautentiseringsuppgifter

  • Artikel

Med OAuth 2.0-klientens autentiseringsuppgifter kan en webbtjänst (konfidentiell klient) använda sina egna autentiseringsuppgifter, i stället för att personifiera en användare, för att autentisera när en annan webbtjänst anropas. Det beviljande som anges i RFC 6749, som ibland kallas tvåbent OAuth, kan användas för att komma åt webbaserade resurser med hjälp av identiteten för ett program. Den här typen används ofta för server-till-server-interaktioner som måste köras i bakgrunden, utan omedelbar interaktion med en användare, och kallas ofta daemoner eller tjänstkonton.

I flödet för klientautentiseringsuppgifter beviljas behörigheter direkt till själva programmet av en administratör. När appen visar en token för en resurs framtvingar resursen att själva appen har behörighet att utföra en åtgärd eftersom det inte finns någon användare som är involverad i autentiseringen. Den här artikeln beskriver båda de steg som krävs för att:

I den här artikeln beskrivs hur du kan programmera direkt mot protokollet i ditt program. När det är möjligt rekommenderar vi att du använder de Microsoft Authentication Libraries (MSAL) som stöds i stället för att hämta token och anropa skyddade webb-API:er. Du kan också referera till exempelappar som använder MSAL. Som en sidoanteckning kommer uppdateringstoken aldrig att beviljas med det här flödet eftersom client_idclient_secret (vilket skulle krävas för att hämta en uppdateringstoken) kan användas för att hämta en åtkomsttoken i stället.

För en högre säkerhetsnivå tillåter Microsofts identitetsplattform även anropstjänsten att autentisera med hjälp av ett certifikat eller federerade autentiseringsuppgifter i stället för en delad hemlighet. Eftersom programmets egna autentiseringsuppgifter används måste dessa autentiseringsuppgifter hållas säkra. Publicera aldrig autentiseringsuppgifterna i källkoden, bädda in den på webbsidor eller använd den i ett allmänt distribuerat internt program.

Protokolldiagram

Hela flödet för klientautentiseringsuppgifter ser ut ungefär som i följande diagram. Vi beskriver vart och ett av stegen senare i den här artikeln.

Diagram showing the client credentials flow

Hämta direkt auktorisering

En app får vanligtvis direkt auktorisering för åtkomst till en resurs på något av två sätt:

Dessa två metoder är de vanligaste i Microsoft Entra-ID:t och vi rekommenderar dem för klienter och resurser som utför flödet för klientautentiseringsuppgifter. En resurs kan också välja att auktorisera sina klienter på andra sätt. Varje resursserver kan välja den metod som passar bäst för programmet.

Listor för åtkomstkontroll

En resursprovider kan framtvinga en auktoriseringskontroll baserat på en lista över program-ID:t (klient)-ID:t som den känner till och ger en specifik åtkomstnivå till. När resursen tar emot en token från Microsofts identitetsplattform kan den avkoda token och extrahera klientens program-ID från anspråken appid och iss . Sedan jämförs programmet med en åtkomstkontrollista (ACL) som det underhåller. ACL:s kornighet och metod kan variera avsevärt mellan resurser.

Ett vanligt användningsfall är att använda en ACL för att köra tester för ett webbprogram eller för ett webb-API. Webb-API:et kan endast bevilja en delmängd fullständiga behörigheter till en specifik klient. Om du vill köra slutpunkt-till-slutpunkt-tester på API:et kan du skapa en testklient som hämtar token från Microsofts identitetsplattform och sedan skickar dem till API:et. API:et kontrollerar sedan ACL för testklientens program-ID för fullständig åtkomst till API:ets hela funktionalitet. Om du använder den här typen av ACL kontrollerar du inte bara anroparens appid värde utan även att iss värdet för token är betrott.

Den här typen av auktorisering är vanlig för daemoner och tjänstkonton som behöver åtkomst till data som ägs av konsumentanvändare som har personliga Microsoft-konton. För data som ägs av organisationer rekommenderar vi att du får nödvändig auktorisering via programbehörigheter.

Kontrollera token utan anspråket roles

För att aktivera det här ACL-baserade auktoriseringsmönstret kräver Inte Microsoft Entra-ID att program har behörighet att hämta token för ett annat program. Därför kan endast apptoken utfärdas utan anspråk roles . Program som exponerar API:er måste implementera behörighetskontroller för att kunna acceptera token.

Om du vill förhindra att program får åtkomsttoken för endast rolllösa appar för ditt program kontrollerar du att tilldelningskraven är aktiverade för din app. Detta blockerar användare och program utan tilldelade roller från att kunna hämta en token för det här programmet.

Programbehörigheter

I stället för att använda ACL:er kan du använda API:er för att exponera en uppsättning programbehörigheter. Dessa beviljas till ett program av en organisations administratör och kan endast användas för att komma åt data som ägs av organisationen och dess anställda. Till exempel exponerar Microsoft Graph flera programbehörigheter för att göra följande:

  • Läsa e-post i alla postlådor
  • Läsa och skriva e-post i alla postlådor
  • Skicka e-post som alla användare
  • Läsa katalogdata

Om du vill använda approller (programbehörigheter) med ditt eget API (till skillnad från Microsoft Graph) måste du först exponera approllerna i API:ets appregistrering i administrationscentret för Microsoft Entra. Konfigurera sedan de nödvändiga approllerna genom att välja dessa behörigheter i klientprogrammets appregistrering. Om du inte har exponerat några approller i api:ets appregistrering kan du inte ange programbehörigheter för det API:et i klientprogrammets appregistrering i administrationscentret för Microsoft Entra.

När du autentiserar som ett program (till skillnad från med en användare) kan du inte använda delegerade behörigheter eftersom det inte finns någon användare för din app att agera för. Du måste använda programbehörigheter, även kallade approller, som beviljas av en administratör eller av API:ets ägare.

Mer information om programbehörigheter finns i Behörigheter och medgivande.

När du skapar ett program som använder programbehörigheter kräver appen vanligtvis en sida eller vy där administratören godkänner appens behörigheter. Den här sidan kan vara en del av appens inloggningsflöde, en del av appens inställningar eller ett dedikerat anslutningsflöde . Det är ofta klokt att appen endast visar den här anslutningsvyn när en användare har loggat in med ett Microsoft-konto för arbete eller skola.

Om du loggar in användaren i din app kan du identifiera den organisation som användaren tillhör innan du ber användaren att godkänna programbehörigheterna. Även om det inte är absolut nödvändigt kan det hjälpa dig att skapa en mer intuitiv upplevelse för dina användare. Om du vill logga in användaren följer du självstudierna för Microsofts identitetsplattform protokoll.

Begära behörigheter från en katalogadministratör

När du är redo att begära behörigheter från organisationens administratör kan du omdirigera användaren till slutpunkten för Microsofts identitetsplattform administratörsmedgivande.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Tips: Prova att klistra in följande begäran i en webbläsare.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
Parameter Villkor beskrivning
tenant Obligatoriskt Den katalogklient som du vill begära behörighet från. Detta kan vara i GUID- eller eget namnformat. Om du inte vet vilken klientorganisation användaren tillhör och du vill låta dem logga in med valfri klientorganisation använder du common.
client_id Obligatoriskt Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app.
redirect_uri Obligatoriskt Omdirigerings-URI:n där du vill att svaret ska skickas för din app att hantera. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i portalen, förutom att den måste vara URL-kodad och att den kan ha ytterligare sökvägssegment.
state Rekommenderat Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll som du vill. Tillståndet används för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.

I det här läget framtvingar Microsoft Entra-ID att endast en klientadministratör kan logga in för att slutföra begäran. Administratören uppmanas att godkänna alla direktprogrambehörigheter som du har begärt för din app i appregistreringsportalen.

Lyckat svar

Om administratören godkänner behörigheterna för ditt program ser det lyckade svaret ut så här:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parameter Description
tenant Den katalogklient som gav ditt program de behörigheter som begärdes i GUID-format.
state Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll som du vill. Tillståndet används för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på.
admin_consent Ställ in på Sant.
Felsvar

Om administratören inte godkänner behörigheterna för ditt program ser det misslyckade svaret ut så här:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parameter Description
error En felkodssträng som du kan använda för att klassificera typer av fel och som du kan använda för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa dig att identifiera rotorsaken till ett fel.

När du har fått ett lyckat svar från appetableringsslutpunkten har appen fått de direkta programbehörigheter som den begärde. Nu kan du begära en token för den resurs som du vill ha.

Hämta en token

När du har skaffat nödvändig auktorisering för ditt program fortsätter du med att hämta åtkomsttoken för API:er. Skicka en POST-begäran till Microsofts identitetsplattform om du vill hämta en token med hjälp av autentiseringsuppgifterna /token för klienten. Det finns några olika fall:

Första fallet: Åtkomsttokenbegäran med en delad hemlighet

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=sampleCredentials
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'
Parameter Villkor beskrivning
tenant Obligatoriskt Katalogklientorganisationen som programmet planerar att arbeta mot, i GUID- eller domännamnsformat.
client_id Obligatoriskt Det program-ID som har tilldelats till din app. Du hittar den här informationen i portalen där du registrerade din app.
scope Obligatoriskt Värdet som skickas för parametern scope i den här begäran ska vara resursidentifieraren (program-ID URI) för den resurs som du vill använda, fäst med suffixet .default . Alla omfång som ingår måste vara för en enskild resurs. Om du inkluderar omfång för flera resurser resulterar det i ett fel.
För Microsoft Graph-exemplet är https://graph.microsoft.com/.defaultvärdet . Det här värdet anger för Microsofts identitetsplattform att för alla direktprogrambehörigheter som du har konfigurerat för din app bör slutpunkten utfärda en token för de som är associerade med den resurs som du vill använda. Mer information om omfånget /.default finns i dokumentationen om medgivande.
client_secret Obligatoriskt Klienthemligheten som du genererade för din app i appregistreringsportalen. Klienthemligheten måste vara URL-kodad innan den skickas. Mönstret Grundläggande autentisering i stället för att ange autentiseringsuppgifter i auktoriseringshuvudet, per RFC 6749 stöds också.
grant_type Obligatoriskt Måste anges till client_credentials.

Andra fallet: Begäran om åtkomsttoken med ett certifikat

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&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
Parameter Villkor beskrivning
tenant Obligatoriskt Katalogklientorganisationen som programmet planerar att arbeta mot, i GUID- eller domännamnsformat.
client_id Obligatoriskt Det program-ID (klient)-ID som har tilldelats till din app.
scope Obligatoriskt Värdet som skickas för parametern scope i den här begäran ska vara resursidentifieraren (program-ID URI) för den resurs som du vill använda, fäst med suffixet .default . Alla omfång som ingår måste vara för en enskild resurs. Om du inkluderar omfång för flera resurser resulterar det i ett fel.
För Microsoft Graph-exemplet är https://graph.microsoft.com/.defaultvärdet . Det här värdet anger för Microsofts identitetsplattform att för alla direktprogrambehörigheter som du har konfigurerat för din app bör slutpunkten utfärda en token för de som är associerade med den resurs som du vill använda. Mer information om omfånget /.default finns i dokumentationen om medgivande.
client_assertion_type Obligatoriskt Värdet måste anges till urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Obligatoriskt En försäkran (en JSON-webbtoken) som du behöver för att skapa och signera med certifikatet som du registrerade som autentiseringsuppgifter för ditt program. Läs mer om certifikatautentiseringsuppgifter för att lära dig hur du registrerar ditt certifikat och formatet på försäkran.
grant_type Obligatoriskt Måste anges till client_credentials.

Parametrarna för den certifikatbaserade begäran skiljer sig bara på ett sätt från den delade hemlighetsbaserade begäran: parametern client_secret ersätts av parametrarna client_assertion_type och client_assertion .

Tredje fallet: Åtkomsttokenbegäran med federerade autentiseringsuppgifter

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com:443
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&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
Parameter Villkor beskrivning
client_assertion Obligatoriskt En försäkran (en JWT- eller JSON-webbtoken) som ditt program får från en annan identitetsprovider utanför Microsofts identitetsplattform, till exempel Kubernetes. Detaljerna i denna JWT måste vara registrerade i ditt program som en federerad identitetsautentiseringsuppgift. Läs mer om arbetsbelastningsidentitetsfederation för att lära dig hur du konfigurerar och använder intyg som genererats från andra identitetsprovidrar.

Allt i begäran är detsamma som det certifikatbaserade flödet, med det avgörande undantaget för källan till client_assertion. I det här flödet skapar programmet inte själva JWT-försäkran. I stället använder appen en JWT som skapats av en annan identitetsprovider. Detta kallas identitetsfederation för arbetsbelastning, där appidentiteten i en annan identitetsplattform används för att hämta token i Microsofts identitetsplattform. Detta passar bäst för scenarier mellan moln, till exempel värd för din beräkning utanför Azure men åtkomst till API:er som skyddas av Microsofts identitetsplattform. Information om det nödvändiga formatet för JWT:er som skapats av andra identitetsprovidrar finns i kontrollformatet.

Lyckat svar

Ett lyckat svar från vilken metod som helst ser ut så här:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parameter Description
access_token Den begärda åtkomsttoken. Appen kan använda den här token för att autentisera till den skyddade resursen, till exempel till ett webb-API.
token_type Anger värdet för tokentyp. Den enda typ som Microsofts identitetsplattform stöder är bearer.
expires_in Hur lång tid en åtkomsttoken är giltig (i sekunder).

Varning

Försök inte verifiera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i koden. Token för Microsoft-tjänster kan använda ett särskilt format som inte verifieras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Läs token är ett användbart felsöknings- och inlärningsverktyg, men använd inte beroenden för detta i koden eller anta detaljer om token som inte är för ett API som du kontrollerar.

Felsvar

Ett felsvar (400 Felaktig begäran) ser ut så här:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Parameter Description
error En felkodssträng som du kan använda för att klassificera typer av fel som inträffar och för att reagera på fel.
error_description Ett specifikt felmeddelande som kan hjälpa dig att identifiera rotorsaken till ett autentiseringsfel.
error_codes En lista över STS-specifika felkoder som kan hjälpa dig med diagnostik.
timestamp Den tid då felet inträffade.
trace_id En unik identifierare för begäran om hjälp med diagnostik.
correlation_id En unik identifierare för begäran för att hjälpa till med diagnostik mellan komponenter.

Använda en token

Nu när du har skaffat en token använder du token för att göra begäranden till resursen. När token upphör att gälla upprepar du begäran till /token slutpunkten för att hämta en ny åtkomsttoken.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Prova följande kommando i terminalen och se till att ersätta token med din egen.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...." 'https://graph.microsoft.com/v1.0/users'

Kodexempel och annan dokumentation

Läs översiktsdokumentationen för klientautentiseringsuppgifter från Microsofts autentiseringsbibliotek

Exempel Plattform beskrivning
active-directory-dotnetcore-daemon-v2 .NET 6.0+ Ett ASP.NET Core-program som visar användare av en klientorganisation som frågar Microsoft Graph med hjälp av programmets identitet i stället för för en användare. Exemplet illustrerar också variationen med hjälp av certifikat för autentisering.
active-directory-dotnet-daemon-v2 ASP.NET MVC Ett webbprogram som synkroniserar data från Microsoft Graph med hjälp av programmets identitet i stället för för en användares räkning.
ms-identity-javascript-nodejs-console Node.js-konsolen Ett Node.js program som visar användare av en klient genom att fråga Microsoft Graph med hjälp av programmets identitet