Microsofts identitetsplattform och OAuth 2.0 Å-Behalf-Of-flödet

OBO-flödet (on-behalf-of) beskriver scenariot med ett webb-API som använder en annan identitet än sin egen för att anropa ett annat webb-API. Avsikten kallas delegering i OAuth och är att skicka en användares identitet och behörigheter via begärandekedjan.

För att mellannivåtjänsten ska kunna göra autentiserade begäranden till den underordnade tjänsten måste den skydda en åtkomsttoken från Microsofts identitetsplattform. Den använder endast delegerade omfång och inte programroller. Roller förblir kopplade till huvudnamnet (användaren) och aldrig till programmet som körs för användarens räkning. Detta inträffar för att förhindra att användaren får behörighet till resurser som de inte ska ha åtkomst till.

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. Se även exempelappar som använder MSAL för exempel.

Klientbegränsningar

Om ett huvudnamn för tjänsten begärde en apptoken och skickade den till ett API, skulle det API:et sedan byta ut en token som inte representerar det ursprungliga tjänstens huvudnamn. Det beror på att OBO-flödet endast fungerar för användarens huvudnamn. I stället måste den använda flödet för klientautentiseringsuppgifter för att hämta en apptoken. När det gäller ensidesappar (SPA) bör de skicka en åtkomsttoken till en konfidentiell klient på mellannivå för att utföra OBO-flöden i stället.

Om en klient använder implicit flöde för att hämta en id_token och även har jokertecken i en svars-URL kan id_token inte användas för ett OBO-flöde. Ett jokertecken är en URL som slutar med ett * tecken. Om till exempel https://myapp.com/* var svars-URL:en kan id_token inte användas eftersom den inte är tillräckligt specifik för att identifiera klienten. Detta förhindrar att token utfärdas. Åtkomsttoken som hämtas via det implicita beviljandeflödet löses dock in av en konfidentiell klient, även om den initierande klienten har en jokerteckensvars-URL registrerad. Det beror på att den konfidentiella klienten kan identifiera klienten som hämtade åtkomsttoken. Den konfidentiella klienten kan sedan använda åtkomsttoken för att hämta en ny åtkomsttoken för det underordnade API:et.

Dessutom kan program med anpassade signeringsnycklar inte användas som API:er på mellannivå i OBO-flödet. Detta omfattar företagsprogram som har konfigurerats för enkel inloggning. Om mellannivå-API:et använder en anpassad signeringsnyckel validerar inte det underordnade API:et signaturen för den åtkomsttoken som skickas till den. Detta resulterar i ett fel eftersom token som signerats med en nyckel som styrs av klienten inte kan accepteras på ett säkert sätt.

Protokolldiagram

Anta att användaren autentiserade ett program med hjälp av OAuth 2.0-auktoriseringskodens beviljandeflöde eller ett annat inloggningsflöde. I det här läget har programmet en åtkomsttoken för API A (token A) med användarens anspråk och medgivande för att få åtkomst till webb-API:et på mellannivå (API A). Api A måste nu göra en autentiserad begäran till det underordnade webb-API:et (API B).

Stegen som följer utgör OBO-flödet och förklaras med hjälp av följande diagram.

1. Klientprogrammet skickar en begäran till API A med token A (med ett aud anspråk på API A).
2. API A autentiserar till slutpunkten Microsofts identitetsplattform tokenutfärdar och begär en token för att få åtkomst till API B.
3. Slutpunkten Microsofts identitetsplattform tokenutfärdar verifierar API A:s autentiseringsuppgifter tillsammans med token A och utfärdar åtkomsttoken för API B (token B) till API A.
4. Token B anges av API A i auktoriseringshuvudet för begäran till API B.
5. Data från den skyddade resursen returneras av API B till API A och sedan till klienten.

I det här scenariot har mellannivåtjänsten ingen användarinteraktion för att få användarens medgivande att komma åt det underordnade API:et. Därför visas alternativet att bevilja åtkomst till det underordnade API:et i förväg som en del av medgivandesteget under autentiseringen. Information om hur du implementerar detta i din app finns i Få medgivande för mellannivåprogrammet.

Begäran om åtkomsttoken på mellannivå

Om du vill begära en åtkomsttoken gör du en HTTP POST till den klientspecifika Microsofts identitetsplattform tokenslutpunkten med följande parametrar.

https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Det finns två fall beroende på om klientprogrammet väljer att skyddas av en delad hemlighet eller ett certifikat.

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

När du använder en delad hemlighet innehåller en begäran om tjänst-till-tjänst-åtkomsttoken följande parametrar:

Exempel

Följande HTTP POST begär en åtkomsttoken och uppdateringstoken med user.read omfång för webb-API:et https://graph.microsoft.com . Begäran signeras med klienthemligheten och görs av en konfidentiell klient.

//line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=sampleCredentia1s
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiOiIyO{a lot of characters here}
&scope=https://graph.microsoft.com/user.read+offline_access
&requested_token_use=on_behalf_of

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

En begäran om tjänst-till-tjänst-åtkomsttoken med ett certifikat innehåller följande parametrar utöver parametrarna från föregående exempel:

Observera att parametrarna är nästan desamma som vid begäran av delad hemlighet, förutom att parametern client_secret ersätts med två parametrar: a client_assertion_type och client_assertion. Parametern client_assertion_type är inställd på urn:ietf:params:oauth:client-assertion-type:jwt-bearer och parametern client_assertion är inställd på den JWT-token som är signerad med certifikatets privata nyckel.

Exempel

Följande HTTP POST begär en åtkomsttoken med user.read omfång för webb-API:et https://graph.microsoft.com med ett certifikat. Begäran signeras med klienthemligheten och görs av en konfidentiell klient.

// line breaks for legibility only
    
POST /oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com/<tenant>
Content-Type: application/x-www-form-urlencoded
    
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&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}
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCIsImtpZCI6InowMzl6ZHNGdWl6cEJmQlZLMVRuMjVRSFlPMCJ9.eyJhdWQiO{a lot of characters here}
&requested_token_use=on_behalf_of
&scope=https://graph.microsoft.com/user.read+offline_access

Svar på åtkomsttoken på mellannivå

Ett lyckat svar är ett JSON OAuth 2.0-svar med följande parametrar.

Exempel på lyckat svar

I följande exempel visas ett lyckat svar på en begäran om en åtkomsttoken för webb-API:et https://graph.microsoft.com . Svaret innehåller en åtkomsttoken och en uppdateringstoken och signeras med certifikatets privata nyckel.

{
    "token_type": "Bearer",
    "scope": "https://graph.microsoft.com/user.read",
    "expires_in": 3269,
    "ext_expires_in": 0,
    "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQTZOVGFlN0NkV1c3UWZkQ0NDYy0tY0hGa18wZE50MVEtc2loVzRMd2RwQVZISGpnTVdQZ0tQeVJIaGlDbUN2NkdyMEpmYmRfY1RmMUFxU21TcFJkVXVydVJqX3Nqd0JoN211eHlBQSIsImFsZyI6IlJTMjU2IiwieDV0IjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIiwia2lkIjoiejAzOXpkc0Z1aXpwQmZCVksxVG4yNVFIWU8wIn0.eyJhdWQiOiJodHRwczovL2dyYXBoLm1pY3Jvc29mdC5jb20iLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDkzOTMwMzA1LCJuYmYiOjE0OTM5MzAzMDUsImV4cCI6MTQ5MzkzMzg3NSwiYWNyIjoiMCIsImFpbyI6IkFTUUEyLzhEQUFBQU9KYnFFWlRNTnEyZFcxYXpKN1RZMDlYeDdOT29EMkJEUlRWMXJ3b2ZRc1k9IiwiYW1yIjpbInB3ZCJdLCJhcHBfZGlzcGxheW5hbWUiOiJUb2RvRG90bmV0T2JvIiwiYXBwaWQiOiIyODQ2ZjcxYi1hN2E0LTQ5ODctYmFiMy03NjAwMzViMmYzODkiLCJhcHBpZGFjciI6IjEiLCJmYW1pbHlfbmFtZSI6IkNhbnVtYWxsYSIsImdpdmVuX25hbWUiOiJOYXZ5YSIsImlwYWRkciI6IjE2Ny4yMjAuMC4xOTkiLCJuYW1lIjoiTmF2eWEgQ2FudW1hbGxhIiwib2lkIjoiZDVlOTc5YzctM2QyZC00MmFmLThmMzAtNzI3ZGQ0YzJkMzgzIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTIxMjc1MjExODQtMTYwNDAxMjkyMC0xODg3OTI3NTI3LTI2MTE4NDg0IiwicGxhdGYiOiIxNCIsInB1aWQiOiIxMDAzM0ZGRkEwNkQxN0M5Iiwic2NwIjoiVXNlci5SZWFkIiwic3ViIjoibWtMMHBiLXlpMXQ1ckRGd2JTZ1JvTWxrZE52b3UzSjNWNm84UFE3alVCRSIsInRpZCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsInVuaXF1ZV9uYW1lIjoibmFjYW51bWFAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5hY2FudW1hQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJWR1ItdmtEZlBFQ2M1dWFDaENRSkFBIiwidmVyIjoiMS4wIn0.cubh1L2VtruiiwF8ut1m9uNBmnUJeYx4x0G30F7CqSpzHj1Sv5DCgNZXyUz3pEiz77G8IfOF0_U5A_02k-xzwdYvtJUYGH3bFISzdqymiEGmdfCIRKl9KMeoo2llGv0ScCniIhr2U1yxTIkIpp092xcdaDt-2_2q_ql1Ha_HtjvTV1f9XR3t7_Id9bR5BqwVX5zPO7JMYDVhUZRx08eqZcC-F3wi0xd_5ND_mavMuxe2wrpF-EZviO3yg0QVRr59tE3AoWl8lSGpVc97vvRCnp4WVRk26jJhYXFPsdk4yWqOKZqzr3IFGyD08WizD_vPSrXcCPbZP3XWaoTUKZSNJg",
    "refresh_token": "OAQABAAAAAABnfiG-mA6NTae7CdWW7QfdAALzDWjw6qSn4GUDfxWzJDZ6lk9qRw4An{a lot of characters here}"
}

Den här åtkomsttoken är en v1.0-formaterad token för Microsoft Graph. Detta beror på att tokenformatet baseras på resursen som används och inte är relaterad till de slutpunkter som används för att begära den. Microsoft Graph har konfigurerats för att acceptera v1.0-token, så Microsofts identitetsplattform genererar v1.0-åtkomsttoken när en klient begär token för Microsoft Graph. Andra appar kan indikera att de vill ha v2.0-formattoken, v1.0-formattoken eller till och med proprietära eller krypterade tokenformat. Både v1.0- och v2.0-slutpunkterna kan generera båda tokenformaten. På så sätt kan resursen alltid få rätt format för token oavsett hur eller var token begärs av klienten.

Exempel på felsvar

Ett felsvar returneras av tokenslutpunkten när du försöker hämta en åtkomsttoken för det underordnade API:et, om det underordnade API:et har en princip för villkorsstyrd åtkomst (till exempel multifaktorautentisering). Mellannivåtjänsten bör visa det här felet för klientprogrammet så att klientprogrammet kan tillhandahålla användarinteraktion för att uppfylla principen för villkorsstyrd åtkomst.

För att visa det här felet tillbaka till klienten svarar mellannivåtjänsten med HTTP 401 Obehörig och med en WWW-Authenticate HTTP-rubrik som innehåller felet och anspråksutmaningen. Klienten måste parsa det här huvudet och hämta en ny token från token utfärdaren genom att presentera anspråksutmaningen om det finns en sådan. Klienter bör inte försöka komma åt mellannivåtjänsten igen med hjälp av en cachelagrad åtkomsttoken.

{
    "error":"interaction_required",
    "error_description":"AADSTS50079: Due to a configuration change made by your administrator, or because you moved to a new location, you must enroll in multifactor authentication to access 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2017-05-01 22:43:20Z",
    "error_codes":[50079],
    "timestamp":"2017-05-01 22:43:20Z",
    "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd",
    "claims":"{\"access_token\":{\"polids\":{\"essential\":true,\"values\":[\"00aa00aa-bb11-cc22-dd33-44ee44ee44ee\"]}}}"
}

Använda åtkomsttoken för att komma åt den skyddade resursen

Nu kan mellannivåtjänsten använda den token som hämtades tidigare för att göra autentiserade begäranden till det underordnade webb-API:et Authorization genom att ange token i huvudet.

Exempel

    GET /v1.0/me HTTP/1.1
    Host: graph.microsoft.com
    Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw

SAML-försäkran som erhållits med ett OAuth2.0 OBO-flöde

Vissa OAuth-baserade webbtjänster måste ha åtkomst till andra webbtjänst-API:er som accepterar SAML-försäkran i icke-interaktiva flöden. Microsoft Entra-ID kan tillhandahålla en SAML-försäkran som svar på ett on-behalf-of-flöde som använder en SAML-baserad webbtjänst som målresurs.

Det här är ett icke-standardtillägg till OAuth 2.0 On-Behalf-Of-flödet som gör att ett OAuth2-baserat program kan komma åt webbtjänst-API-slutpunkter som använder SAML-token.

Hämta en SAML-token med hjälp av en OBO-begäran med en delad hemlighet

En tjänst-till-tjänst-begäran för en SAML-försäkran innehåller följande parametrar:

Svaret innehåller en SAML-token kodad i UTF8 och Base 64url.

• SubjectConfirmationData för en SAML-försäkran som kommer från ett OBO-anrop: Om målprogrammet kräver ett Recipient värde i SubjectConfirmationDatamåste värdet konfigureras som den första svars-URL:en för icke-wildcard i resursprogramkonfigurationen. Eftersom standardsvars-URL:en inte används för att fastställa Recipient värdet kan du behöva ändra ordning på svars-URL:erna i programkonfigurationen för att säkerställa att den första svars-URL:en för icke-wildcard används. Mer information finns i Svars-URL:er.
• Noden SubjectConfirmationData: Noden kan inte innehålla ett InResponseTo attribut eftersom den inte ingår i ett SAML-svar. Programmet som tar emot SAML-token måste kunna acceptera SAML-försäkran utan ett InResponseTo attribut.
• API-behörigheter: Du måste lägga till nödvändiga API-behörigheter i mellannivåprogrammet för att tillåta åtkomst till SAML-programmet, så att det kan begära en token för /.default SAML-programmets omfång.
• Medgivande: Medgivande måste beviljas för att ta emot en SAML-token som innehåller användardata i ett OAuth-flöde. Mer information finns i Få medgivande för mellannivåprogrammet.

Svar med SAML-försäkran

• token_type: Bearer
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• Resurs: https://api.contoso.com
• access_token: <SAML-försäkran>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Uppdatera token>

Få medgivande för mellannivåprogrammet

Målet med OBO-flödet är att säkerställa att rätt medgivande ges så att klientappen kan anropa mellannivåappen och mellannivåappen har behörighet att anropa serverdelsresursen. Beroende på arkitekturen eller användningen av ditt program bör du överväga följande för att säkerställa att OBO-flödet lyckas:

.default och kombinerat medgivande

Mellannivåprogrammet lägger till klienten i listan över kända klientprogram (knownClientApplications) i sitt manifest. Om en medgivandeprompt utlöses av klienten är medgivandeflödet både för sig självt och mellannivåprogrammet. På Microsofts identitetsplattform görs detta med hjälp av omfånget.default. Omfånget .default är ett särskilt omfång som används för att begära medgivande för att få åtkomst till alla omfång som programmet har behörighet för. Detta är användbart när programmet behöver åtkomst till flera resurser, men användaren bör bara uppmanas att ge sitt medgivande en gång.

När du utlöser en medgivandeskärm med kända klientprogram och .defaultvisar medgivandeskärmen behörigheter för både klienten till API:et på mellannivå och begär även de behörigheter som krävs av API:et på mellannivå. Användaren ger medgivande för båda programmen och sedan fungerar OBO-flödet.

Resurstjänsten (API) som identifieras i begäran ska vara det API som klientprogrammet begär en åtkomsttoken för till följd av användarens inloggning. Till exempel scope=openid https://middle-tier-api.example.com/.default (för att begära en åtkomsttoken för API:et på mellannivå) eller scope=openid offline_access .default (när en resurs inte identifieras är den standardinställningen Microsoft Graph).

Oavsett vilket API som identifieras i auktoriseringsbegäran kombineras medgivandeprompten med alla nödvändiga behörigheter som konfigurerats för klientappen. Alla nödvändiga behörigheter som konfigurerats för varje API på mellannivå som anges i klientens behörighetslista, som identifierade klienten som ett känt klientprogram, ingår också.

Förauktoriserade program

Resurser kan indikera att ett visst program alltid har behörighet att ta emot vissa omfång. Detta är användbart för att göra anslutningar mellan en klientdelsklient och en serverdelsresurs smidigare. En resurs kan deklarera flera förauktoriserade program (preAuthorizedApplications) i sitt manifest. Alla sådana program kan begära dessa behörigheter i ett OBO-flöde och ta emot dem utan att användaren ger sitt medgivande.

Administratörsmedgivande

En klientorganisationsadministratör kan garantera att program har behörighet att anropa sina nödvändiga API:er genom att ge administratörsmedgivande för mellannivåprogrammet. För att göra detta kan administratören hitta mellannivåprogrammet i klientorganisationen, öppna sidan med nödvändiga behörigheter och välja att ge behörighet för appen. Mer information om administratörsmedgivande finns i dokumentationen om medgivande och behörigheter.

Användning av ett enda program

I vissa scenarier kan du bara ha en enda parkoppling av mellannivå- och klientdelsklienten. I det här scenariot kan det vara enklare att göra detta till ett enda program, vilket negerar behovet av ett mellannivåprogram helt och hållet. Om du vill autentisera mellan klientdelen och webb-API:et kan du använda cookies, en id_token eller en åtkomsttoken som begärts för själva programmet. Begär sedan medgivande från det här enskilda programmet till serverdelsresursen.

Se även

Läs mer om OAuth 2.0-protokollet och ett annat sätt att utföra tjänst-till-tjänst-autentisering med klientautentiseringsuppgifter.

• OAuth 2.0-klientautentiseringsuppgifter beviljas i Microsofts identitetsplattform
• OAuth 2.0-kodflöde i Microsofts identitetsplattform
• Använda omfånget /.default