Microsoft Identity Platform a tok OAuth 2.0 On-Behalf-Of

Tok on-behalf-of (OBO) popisuje scénář webového rozhraní API, který používá jinou identitu než vlastní k volání jiného webového rozhraní API. V OAuth se označuje jako delegování, záměrem je předat identitu a oprávnění uživatele prostřednictvím řetězu žádostí.

Aby služba střední vrstvy měla provádět ověřené požadavky na podřízenou službu, musí zabezpečit přístupový token z platformy Microsoft Identity Platform. Používá pouze delegovaná rozsahy, nikoli role aplikací. Role zůstanou připojené k objektu zabezpečení (uživateli) a nikdy k aplikaci provozující jménem uživatele. Dochází k tomu, aby uživatel získal oprávnění k prostředkům, ke kterým by neměl mít přístup.

Tento článek popisuje, jak vaši aplikaci programovat přímo s použitím protokolu. Pokud je to možné, doporučujeme místo získávání tokenů a volání zabezpečených webových rozhraní API raději používat podporované knihovny MSAL (Microsoft Authentication Libraries). Příklady najdete také v ukázkových aplikacích, které používají KNIHOVNU MSAL .

Omezení klienta

Pokud instanční objekt požadoval token jen pro aplikaci a odeslal ho do rozhraní API, toto rozhraní API si pak vymění token, který nepředstavuje původní instanční objekt. Důvodem je to, že tok OBO funguje jenom pro objekty zabezpečení uživatele. Místo toho musí k získání tokenu jen pro aplikaci použít tok přihlašovacích údajů klienta. V případě jednostrákových aplikací (SPA) by místo toho měly předávat přístupový token důvěrnému klientovi střední vrstvy, aby místo toho prováděly toky OBO.

Pokud klient používá implicitní tok k získání id_token a má v adrese URL odpovědi také zástupné náčiní, id_token nejde použít pro tok OBO. Zástupný znak je adresa URL, která končí znakem * . Pokud https://myapp.com/* byla například adresa URL odpovědi, id_token se nedá použít, protože není dostatečně specifická k identifikaci klienta. Tím by se zabránilo vystavení tokenu. Přístupové tokeny získané prostřednictvím toku implicitního udělení se však uplatní důvěrným klientem, i když má iniciační klient zaregistrovanou adresu URL odpovědi se zástupným znakem. Důvodem je to, že důvěrný klient může identifikovat klienta, který získal přístupový token. Důvěrný klient pak může přístupový token použít k získání nového přístupového tokenu pro podřízené rozhraní API.

Kromě toho se aplikace s vlastními podpisovými klíči nedají použít jako rozhraní API střední vrstvy v toku OBO. To zahrnuje podnikové aplikace nakonfigurované pro jednotné přihlašování. Pokud rozhraní API střední vrstvy používá vlastní podpisový klíč, podřízené rozhraní API neověří podpis přístupového tokenu, který se mu předá. Výsledkem je chyba, protože tokeny podepsané klíčem řízeným klientem nelze bezpečně přijmout.

Diagram protokolu

Předpokládejme, že uživatel ověřil aplikaci pomocí toku udělení autorizačního kódu OAuth 2.0 nebo jiného toku přihlašování. V tomto okamžiku má aplikace přístupový token pro rozhraní API A (token A) s deklaracemi identity uživatele a souhlasí s přístupem k webovému rozhraní API střední vrstvy (API A). Teď musí rozhraní API A provést ověřený požadavek na podřízené webové rozhraní API (API B).

Následující kroky představují tok OBO a jsou vysvětleny pomocí následujícího diagramu.

1. Klientská aplikace odešle požadavek na rozhraní API A s tokenem A (s aud deklarací identity rozhraní API A).
2. Rozhraní API A se ověřuje v koncovém bodu vystavení tokenu Microsoft Identity Platform a vyžádá si token pro přístup k rozhraní API B.
3. Koncový bod vystavení tokenu Microsoft Identity Platform ověřuje přihlašovací údaje rozhraní API A společně s tokenem A a vydává přístupový token pro rozhraní API B (token B) do rozhraní API A.
4. Token B je nastaven rozhraním API A v autorizační hlavičce požadavku na rozhraní API B.
5. Data ze zabezpečeného prostředku vrátí rozhraní API B do rozhraní API A a pak klientovi.

V tomto scénáři nemá služba střední vrstvy žádnou interakci uživatele, aby získal souhlas uživatele s přístupem k podřízené rozhraní API. Proto se možnost udělení přístupu k podřízenému rozhraní API zobrazí předem v rámci kroku souhlasu během ověřování. Informace o tom, jak ji implementovat ve vaší aplikaci, najdete v tématu Získání souhlasu pro aplikaci střední vrstvy.

Žádost o přístupový token střední vrstvy

Pokud chcete požádat o přístupový token, nastavte http POST do koncového bodu tokenu platformy Microsoft Identity Platform pro konkrétního tenanta s následujícími parametry.

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

Existují dva případy v závislosti na tom, jestli se klientská aplikace rozhodne zabezpečit sdíleným tajným kódem nebo certifikátem.

První případ: Žádost o přístupový token se sdíleným tajným kódem

Při použití sdíleného tajného kódu požadavek na přístupový token služby obsahuje následující parametry:

Příklad

Následující http POST požaduje přístupový token a obnovovací token s oborem user.readhttps://graph.microsoft.com pro webové rozhraní API. Požadavek je podepsaný tajným kódem klienta a je proveden důvěrným klientem.

//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

Druhý případ: Žádost o přístupový token s certifikátem

Žádost o přístupový token service-to-service s certifikátem obsahuje kromě parametrů z předchozího příkladu také následující parametry:

Všimněte si, že parametry jsou téměř stejné jako v případě požadavku sdíleným tajným kódem, s tím rozdílem, že client_secret parametr je nahrazen dvěma parametry: a client_assertion_type .client_assertion Parametr client_assertion_type je nastaven urn:ietf:params:oauth:client-assertion-type:jwt-bearer na a client_assertion parametr je nastaven na token JWT, který je podepsaný privátním klíčem certifikátu.

Příklad

Následující http POST požádá o přístupový token s oborem user.read webového https://graph.microsoft.com rozhraní API s certifikátem. Požadavek je podepsaný tajným kódem klienta a je proveden důvěrným klientem.

// 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

Odpověď přístupového tokenu střední vrstvy

Úspěšná odpověď je odpověď JSON OAuth 2.0 s následujícími parametry.

Příklad odpovědi na úspěch

Následující příklad ukazuje úspěšnou odpověď na žádost o přístupový token pro https://graph.microsoft.com webové rozhraní API. Odpověď obsahuje přístupový token a obnovovací token a je podepsaný privátním klíčem certifikátu.

{
    "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}"
}

Tento přístupový token je token ve formátu v1.0 pro Microsoft Graph. Důvodem je to, že formát tokenu je založený na používaném prostředku a nesouvisí s koncovými body použitými k jeho vyžádání. Microsoft Graph je nastavený tak, aby přijímal tokeny v1.0, takže platforma Microsoft Identity Platform vytváří přístupové tokeny v1.0, když klient požádá o tokeny pro Microsoft Graph. Jiné aplikace můžou indikovat, že chtějí tokeny ve formátu v2.0, v1.0 nebo dokonce proprietární nebo šifrované formáty tokenů. Koncové body v1.0 i v2.0 můžou generovat jeden formát tokenu. Tímto způsobem může prostředek vždy získat správný formát tokenu bez ohledu na to, jak nebo kde je token požadován klientem.

Příklad odpovědi na chybu

Koncový bod tokenu vrátí chybovou odpověď při pokusu o získání přístupového tokenu pro podřízené rozhraní API, pokud má podřízené rozhraní API nastavené zásady podmíněného přístupu (například vícefaktorové ověřování). Služba střední vrstvy by měla tuto chybu zobrazit klientské aplikaci, aby klientská aplikace mohla poskytnout interakci uživatele, aby splňovala zásady podmíněného přístupu.

Chcete-li tuto chybu zobrazit zpět klientovi, služba střední vrstvy odpoví http 401 Neautorizováno a hlavičkou HTTP s ověřováním WWW obsahující chybu a výzvu deklarace identity. Klient musí parsovat tuto hlavičku a získat nový token od vystavitele tokenu tím, že předá výzvu deklarace identity, pokud existuje. Klienti by se neměli opakovat při přístupu ke službě střední vrstvy pomocí přístupového tokenu uloženého v mezipaměti.

{
    "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\"]}}}"
}

Použití přístupového tokenu pro přístup k zabezpečenému prostředku

Služba střední vrstvy teď může token získaný dříve použít k provádění ověřených požadavků na podřízené webové rozhraní API nastavením tokenu Authorization v hlavičce.

Příklad

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

Kontrolní výrazy SAML získané s tokem OAuth2.0 OBO

Některé webové služby založené na OAuth potřebují přístup k jiným rozhraním API webových služeb, která přijímají kontrolní výrazy SAML v neinteraktivních tocích. Microsoft Entra ID může poskytnout kontrolní výraz SAML v reakci na tok On-Behalf-Of, který používá webovou službu založenou na SAML jako cílový prostředek.

Toto je nestandardní rozšíření toku OAuth 2.0 On-Behalf-Of, které umožňuje aplikaci založené na OAuth2 přistupovat ke koncovým bodům rozhraní API webové služby, které využívají tokeny SAML.

Získání tokenu SAML pomocí požadavku OBO se sdíleným tajným kódem

Požadavek na službu pro kontrolní výraz SAML obsahuje následující parametry:

Odpověď obsahuje token SAML kódovaný v kódování UTF8 a Base 64url.

• SubjectConfirmationData pro kontrolní výraz SAML zdrojový z volání OBO: Pokud cílová aplikace vyžaduje Recipient hodnotu v SubjectConfirmationData, musí být tato hodnota nakonfigurována jako první adresa URL odpovědi newildcard v konfiguraci aplikace prostředků. Vzhledem k tomu, že výchozí adresa URL odpovědi se k určení Recipient hodnoty nepoužívá, budete pravděpodobně muset změnit pořadí adres URL odpovědí v konfiguraci aplikace, aby se zajistilo, že se použije první adresa URL odpovědi, která není zpřístupněná. Další informace najdete v tématu Adresy URL odpovědí.
• Uzel SubjectConfirmationData: Uzel nemůže obsahovat InResponseTo atribut, protože není součástí odpovědi SAML. Aplikace, která přijímá token SAML, musí být schopná přijmout kontrolní výraz SAML bez atributu InResponseTo .
• Oprávnění rozhraní API: Musíte do aplikace střední vrstvy přidat potřebná oprávnění rozhraní API, aby umožňovala přístup k aplikaci SAML, aby mohla požádat o token pro /.default obor aplikace SAML.
• Souhlas: Souhlas: Souhlas musí být udělen pro příjem tokenu SAML obsahujícího uživatelská data v toku OAuth. Informace najdete v tématu Získání souhlasu pro aplikaci střední vrstvy.

Odpověď s kontrolním výrazem SAML

• token_type: Nosný
• expires_in: 3296
• ext_expires_in: 0
• expires_on: 1529627844
• Zdrojů: https://api.contoso.com
• access_token: <Kontrolní výraz SAML>
• issued_token_type: urn:ietf:params:oauth:token-type:saml2
• refresh_token: <Obnovovací token>

Získání souhlasu pro aplikaci střední vrstvy

Cílem toku OBO je zajistit správné vyjádření souhlasu, aby klientská aplikace mohl volat aplikaci střední vrstvy a aplikace střední vrstvy má oprávnění volat back-endový prostředek. V závislosti na architektuře nebo využití vaší aplikace byste měli zvážit následující skutečnosti, abyste zajistili, že tok OBO bude úspěšný:

.default a sloučený souhlas

Aplikace střední vrstvy přidá klienta do seznamu známých klientských aplikací (knownClientApplications) v manifestu. Pokud klient aktivuje výzvu k vyjádření souhlasu, je tok souhlasu pro sebe i aplikaci střední vrstvy. Na platformě Microsoft Identity Platform se to provádí pomocí .default oboru. Obor .default je speciální obor, který se používá k vyžádání souhlasu s přístupem ke všem oborům, ke kterým má aplikace oprávnění. To je užitečné, když aplikace potřebuje přístup k více prostředkům, ale uživatel by měl být vyzván pouze jednou k vyjádření souhlasu.

Při aktivaci obrazovky souhlasu pomocí známých klientských aplikací a .defaultna obrazovce souhlasu se zobrazují oprávnění pro klienta k rozhraní API střední vrstvy a také žádost o oprávnění vyžadovaná rozhraním API střední vrstvy. Uživatel poskytne souhlas pro obě aplikace a pak funguje tok OBO.

Služba prostředků (API) identifikovaná v požadavku by měla být rozhraní API, pro které klientská aplikace požaduje přístupový token v důsledku přihlášení uživatele. Například scope=openid https://middle-tier-api.example.com/.default (pro vyžádání přístupového tokenu pro rozhraní API střední vrstvy) nebo scope=openid offline_access .default (pokud prostředek není identifikovaný, použije se jako výchozí Microsoft Graph).

Bez ohledu na to, které rozhraní API je identifikováno v žádosti o autorizaci, se výzva k vyjádření souhlasu zkombinuje se všemi požadovanými oprávněními nakonfigurovanými pro klientskou aplikaci. Všechna požadovaná oprávnění nakonfigurovaná pro každé rozhraní API střední vrstvy uvedená v seznamu požadovaných oprávnění klienta, která identifikovala klienta jako známou klientskou aplikaci, jsou také zahrnuta.

Předvytvářené aplikace

Prostředky můžou indikovat, že daná aplikace má vždy oprávnění přijímat určité obory. To je užitečné k tomu, aby připojení mezi front-endovým klientem a back-endovým prostředkem byla plynulejší. Prostředek může v manifestu deklarovat více předauthorizovaných aplikací (preAuthorizedApplications). Každá taková aplikace může požádat o tato oprávnění v toku OBO a přijímat je bez poskytnutí souhlasu uživatele.

Souhlas správce

Správce tenanta může zaručit, že aplikace mají oprávnění volat požadovaná rozhraní API tím, že poskytne souhlas správce pro aplikaci střední vrstvy. K tomu může správce najít aplikaci střední vrstvy ve svém tenantovi, otevřít požadovanou stránku oprávnění a rozhodnout se udělit oprávnění pro aplikaci. Další informace o souhlasu správce najdete v dokumentaci k vyjádření souhlasu a oprávnění.

Použití jedné aplikace

V některých scénářích byste mohli mít pouze jednu dvojici prostřední vrstvy a front-endového klienta. V tomto scénáři byste mohli snadněji vytvořit jednu aplikaci a úplně tak negovat potřebu střední vrstvy. K ověření mezi front-endem a webovým rozhraním API můžete použít soubory cookie, id_token nebo přístupový token požadovaný pro samotnou aplikaci. Potom požádejte o souhlas této jedné aplikace s back-endovým prostředkem.

Viz také

Přečtěte si další informace o protokolu OAuth 2.0 a dalším způsobem, jak provádět službu ověřování pomocí přihlašovacích údajů klienta.

• Udělení přihlašovacích údajů klienta OAuth 2.0 na platformě Microsoft Identity Platform
• Tok kódu OAuth 2.0 na platformě Microsoft Identity Platform
• /.default Použití oboru