przepływ Platforma tożsamości Microsoft i OAuth 2.0 On-Behalf-Of
Przepływ on-behalf-of (OBO) opisuje scenariusz internetowego interfejsu API przy użyciu tożsamości innej niż własna do wywoływania innego internetowego interfejsu API. Określany jako delegowanie w usłudze OAuth, celem jest przekazanie tożsamości i uprawnień użytkownika za pośrednictwem łańcucha żądań.
Aby usługa warstwy środkowej wysyłała uwierzytelnione żądania do usługi podrzędnej, musi zabezpieczyć token dostępu z Platforma tożsamości Microsoft. Używa tylko zakresów delegowanych, a nie ról aplikacji. Role pozostają dołączone do podmiotu zabezpieczeń (użytkownika) i nigdy nie do aplikacji działającej w imieniu użytkownika. Dzieje się tak, aby uniemożliwić użytkownikowi uzyskanie uprawnień do zasobów, do których nie powinien mieć dostępu.
W tym artykule opisano, jak programować aplikację bezpośrednio w oparciu o protokół. Jeśli to możliwe, zalecamy używanie obsługiwanych bibliotek Microsoft Authentication Libraries (MSAL) zamiast uzyskiwania tokenów i wywoływania zabezpieczonych internetowych interfejsów API. Zapoznaj się również z przykładami przykładowymi aplikacjami korzystającymi z biblioteki MSAL .
Ograniczenia klienta
Jeśli jednostka usługi zażądała tokenu tylko aplikacji i wysłała go do interfejsu API, ten interfejs API wymieni token, który nie reprezentuje oryginalnej jednostki usługi. Dzieje się tak, ponieważ przepływ OBO działa tylko dla podmiotów zabezpieczeń użytkowników. Zamiast tego należy użyć przepływu poświadczeń klienta, aby uzyskać token tylko dla aplikacji. W przypadku aplikacji jednostronicowych (SPA) należy przekazać token dostępu do poufnego klienta warstwy środkowej, aby zamiast tego wykonywać przepływy OBO.
Jeśli klient korzysta z niejawnego przepływu w celu uzyskania id_token, a także ma symbole wieloznaczne w adresie URL odpowiedzi, nie można użyć id_token dla przepływu OBO. Symbol wieloznaczny to adres URL kończący się znakiem * . Jeśli na przykład był to adres URL odpowiedzi, https://myapp.com/* nie można użyć id_token, ponieważ nie jest wystarczająco szczegółowy, aby zidentyfikować klienta. Uniemożliwiłoby to wystawianie tokenu. Jednak tokeny dostępu uzyskane za pośrednictwem niejawnego przepływu udzielania są obsługiwane przez poufnego klienta, nawet jeśli klient inicjujący ma zarejestrowany adres URL odpowiedzi z symbolem wieloznacznymi. Jest to spowodowane tym, że poufny klient może zidentyfikować klienta, który uzyskał token dostępu. Poufny klient może następnie użyć tokenu dostępu do uzyskania nowego tokenu dostępu dla podrzędnego interfejsu API.
Ponadto aplikacje z niestandardowymi kluczami podpisywania nie mogą być używane jako interfejsy API warstwy środkowej w przepływie OBO. Obejmuje to aplikacje dla przedsiębiorstw skonfigurowane do logowania jednokrotnego. Jeśli interfejs API warstwy środkowej używa niestandardowego klucza podpisywania, interfejs API podrzędny nie zweryfikuje sygnatury przekazanego do niego tokenu dostępu. Powoduje to błąd, ponieważ tokeny podpisane przy użyciu klucza kontrolowanego przez klienta nie mogą być bezpiecznie akceptowane.
Diagram protokołu
Załóżmy, że użytkownik uwierzytelnił aplikację przy użyciu przepływu udzielania kodu autoryzacji OAuth 2.0 lub innego przepływu logowania. W tym momencie aplikacja ma token dostępu dla interfejsu API A (token A ) z oświadczeniami użytkownika i zgodą na dostęp do internetowego interfejsu API (API A) warstwy środkowej. Teraz interfejs API A musi wysłać uwierzytelnione żądanie do podrzędnego internetowego interfejsu API (API B).
Kroki, które należy wykonać, stanowią przepływ OBO i zostały wyjaśnione za pomocą poniższego diagramu.
- Aplikacja kliencka wysyła żądanie do interfejsu API A z tokenem A (z oświadczeniem
audinterfejsu API A). - Interfejs API A uwierzytelnia się w punkcie końcowym wystawiania tokenu Platforma tożsamości Microsoft i żąda tokenu dostępu do interfejsu API B.
- Punkt końcowy wystawiania tokenu Platforma tożsamości Microsoft weryfikuje poświadczenia interfejsu API A wraz z tokenem A i wystawia token dostępu dla interfejsu API B (token B) do interfejsu API A.
- Token B jest ustawiany przez interfejs API A w nagłówku autoryzacji żądania do interfejsu API B.
- Dane z zabezpieczonego zasobu są zwracane przez interfejs API B do interfejsu API A, a następnie do klienta.
W tym scenariuszu usługa warstwy środkowej nie ma interakcji użytkownika w celu uzyskania zgody użytkownika na dostęp do podrzędnego interfejsu API. W związku z tym opcja udzielenia dostępu do podrzędnego interfejsu API jest przedstawiana z góry w ramach kroku zgody podczas uwierzytelniania. Aby dowiedzieć się, jak zaimplementować tę funkcję w aplikacji, zobacz Uzyskiwanie zgody dla aplikacji warstwy środkowej.
Żądanie tokenu dostępu warstwy środkowej
Aby zażądać tokenu dostępu, utwórz adres HTTP POST do punktu końcowego tokenu specyficznego dla dzierżawy Platforma tożsamości Microsoft z następującymi parametrami.
https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
Ostrzeżenie
NIE wysyłaj tokenów dostępu, które zostały wystawione w warstwie środkowej do dowolnego miejsca, z wyjątkiem zamierzonej grupy odbiorców tokenu. Tokeny dostępu wystawione w warstwie środkowej są przeznaczone tylko do użytku przez warstwę środkową w celu komunikowania się z zamierzonym punktem końcowym odbiorców.
Zagrożenia bezpieczeństwa związane z przekazywaniem tokenów dostępu z zasobu warstwy środkowej do klienta (zamiast samego klienta uzyskującego tokeny dostępu):
- Zwiększone ryzyko przechwycenia tokenu w przypadku naruszonych kanałów SSL/TLS.
- Brak możliwości spełnienia scenariuszy powiązania tokenu i dostępu warunkowego wymagających kroku oświadczenia (na przykład uwierzytelniania wieloskładnikowego, częstotliwości logowania).
- Niezgodność z zasadami opartymi na urządzeniach skonfigurowanymi przez administratora (na przykład mdm, zasadami opartymi na lokalizacji).
Istnieją dwa przypadki w zależności od tego, czy aplikacja kliencka wybierze zabezpieczenie za pomocą wspólnego wpisu tajnego, czy certyfikatu.
Pierwszy przypadek: żądanie tokenu dostępu z udostępnionym wpisem tajnym
W przypadku korzystania z udostępnionego wpisu tajnego żądanie tokenu dostępu typu service-to-service zawiera następujące parametry:
| Parametr | Type | Opis |
|---|---|---|
grant_type |
Wymagania | Typ żądania tokenu. W przypadku żądania używającego JWT wartość musi mieć wartość urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Wymagania | Identyfikator aplikacji (klienta), który jest przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji. |
client_secret |
Wymagania | Wpis tajny klienta wygenerowany dla aplikacji w centrum administracyjnym firmy Microsoft Entra — Rejestracje aplikacji. Wzorzec uwierzytelniania podstawowego zamiast podawania poświadczeń w nagłówku autoryzacji na RFC 6749 jest również obsługiwany. |
assertion |
Wymagania | Token dostępu, który został wysłany do interfejsu API warstwy środkowej. Ten token musi mieć oświadczenie odbiorców (aud) aplikacji tworzącej to żądanie OBO (aplikacja oznaczona przez client-id pole). Aplikacje nie mogą zrealizować tokenu dla innej aplikacji (na przykład jeśli klient wysyła interfejs API token przeznaczony dla programu Microsoft Graph, interfejs API nie może zrealizować go przy użyciu OBO. Zamiast tego powinien odrzucić token). |
scope |
Wymagania | Rozdzielona spacją lista zakresów dla żądania tokenu. Aby uzyskać więcej informacji, zobacz zakresy. |
requested_token_use |
Wymagania | Określa sposób przetwarzania żądania. W przepływie OBO wartość musi być ustawiona na on_behalf_of. |
Przykład
Następujący kod HTTP POST żąda tokenu dostępu i tokenu odświeżania z user.read zakresem internetowego interfejsu https://graph.microsoft.com API. Żądanie jest podpisane przy użyciu klucza tajnego klienta i jest wykonywane przez poufnego klienta.
//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
Drugi przypadek: żądanie tokenu dostępu z certyfikatem
Żądanie tokenu dostępu do usługi z certyfikatem zawiera następujące parametry oprócz parametrów z poprzedniego przykładu:
| Parametr | Type | Opis |
|---|---|---|
grant_type |
Wymagania | Typ żądania tokenu. W przypadku żądania używającego JWT wartość musi mieć wartość urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id |
Wymagania | Identyfikator aplikacji (klienta), który jest przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji. |
client_assertion_type |
Wymagania | Wartość musi mieć wartość urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion |
Wymagania | Potwierdzenie (token internetowy JSON), który należy utworzyć i podpisać przy użyciu certyfikatu zarejestrowanego jako poświadczenia aplikacji. Aby dowiedzieć się, jak zarejestrować certyfikat i format asercji, zobacz poświadczenia certyfikatu. |
assertion |
Wymagania | Token dostępu, który został wysłany do interfejsu API warstwy środkowej. Ten token musi mieć oświadczenie odbiorców (aud) aplikacji tworzącej to żądanie OBO (aplikacja oznaczona przez client-id pole). Aplikacje nie mogą zrealizować tokenu dla innej aplikacji (na przykład jeśli klient wysyła interfejs API token przeznaczony dla programu MS Graph, interfejs API nie może go zrealizować przy użyciu OBO. Zamiast tego powinien odrzucić token). |
requested_token_use |
Wymagania | Określa sposób przetwarzania żądania. W przepływie OBO wartość musi być ustawiona na on_behalf_of. |
scope |
Wymagania | Rozdzielona spacjami lista zakresów żądania tokenu. Aby uzyskać więcej informacji, zobacz zakresy. |
Zwróć uwagę, że parametry są prawie takie same jak w przypadku żądania przez wspólny klucz tajny, z tą różnicą, że client_secret parametr jest zastępowany przez dwa parametry: a client_assertion_type i client_assertion. Parametr client_assertion_type jest ustawiony na urn:ietf:params:oauth:client-assertion-type:jwt-bearer wartość , a client_assertion parametr jest ustawiony na token JWT podpisany przy użyciu klucza prywatnego certyfikatu.
Przykład
Następujący kod HTTP POST żąda tokenu dostępu z user.read zakresem internetowego interfejsu https://graph.microsoft.com API z certyfikatem. Żądanie jest podpisane przy użyciu klucza tajnego klienta i jest wykonywane przez poufnego klienta.
// 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
Odpowiedź tokenu dostępu warstwy środkowej
Odpowiedź na powodzenie to odpowiedź JSON OAuth 2.0 z następującymi parametrami.
| Parametr | Opis |
|---|---|
token_type |
Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje Platforma tożsamości Microsoft jest Bearer. Aby uzyskać więcej informacji na temat tokenów elementu nośnego, zobacz OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). |
scope |
Zakres dostępu udzielony w tokenie. |
expires_in |
Czas (w sekundach) prawidłowy token dostępu. |
access_token |
Żądany token dostępu. Usługa wywołująca może używać tego tokenu do uwierzytelniania w usłudze odbierającej. |
refresh_token |
Token odświeżania dla żądanego tokenu dostępu. Usługa wywołująca może użyć tego tokenu, aby zażądać innego tokenu dostępu po wygaśnięciu bieżącego tokenu dostępu. Token odświeżania jest udostępniany tylko wtedy, gdy offline_access zażądano zakresu. |
Przykład odpowiedzi na powodzenie
W poniższym przykładzie przedstawiono pomyślną odpowiedź na żądanie tokenu dostępu dla internetowego interfejsu https://graph.microsoft.com API. Odpowiedź zawiera token dostępu i token odświeżania i jest podpisany przy użyciu klucza prywatnego certyfikatu.
{
"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}"
}
Ten token dostępu jest tokenem w formacie 1.0 dla programu Microsoft Graph. Dzieje się tak, ponieważ format tokenu jest oparty na zasobie, do którego uzyskuje się dostęp i nie ma związku z punktami końcowymi używanymi do żądania. Program Microsoft Graph jest skonfigurowany do akceptowania tokenów w wersji 1.0, dlatego Platforma tożsamości Microsoft tworzy tokeny dostępu w wersji 1.0, gdy klient żąda tokenów dla programu Microsoft Graph. Inne aplikacje mogą wskazywać, że mają tokeny w formacie 2.0, tokeny w formacie 1.0, a nawet zastrzeżone lub zaszyfrowane formaty tokenów. Punkty końcowe w wersji 1.0 i 2.0 mogą emitować dowolny format tokenu. Dzięki temu zasób może zawsze uzyskać odpowiedni format tokenu niezależnie od tego, jak lub gdzie token jest żądany przez klienta.
Ostrzeżenie
Nie próbuj weryfikować ani odczytywać tokenów dla żadnego interfejsu API, którego nie jesteś właścicielem, w tym tokenów w tym przykładzie, w kodzie. Tokeny dla usługi firmy Microsoft mogą używać specjalnego formatu, który nie będzie weryfikowany jako JWT, a także może być szyfrowany dla użytkowników klienta (konta Microsoft). Podczas odczytywania tokenów jest przydatnym narzędziem do debugowania i uczenia, nie należy brać zależności od tego w kodzie ani zakładać konkretnych informacji o tokenach, które nie są przeznaczone dla kontrolującego interfejsu API.
Przykład odpowiedzi na błąd
Odpowiedź o błędzie jest zwracana przez punkt końcowy tokenu podczas próby uzyskania tokenu dostępu dla podrzędnego interfejsu API, jeśli interfejs API podrzędny ma ustawione zasady dostępu warunkowego (takie jak uwierzytelnianie wieloskładnikowe). Usługa warstwy środkowej powinna spowodować wyświetlenie tego błędu w aplikacji klienckiej, aby aplikacja kliencka mogła zapewnić interakcję użytkownika w celu spełnienia zasad dostępu warunkowego.
Aby wyświetlić ten błąd z powrotem do klienta, usługa warstwy środkowej odpowiada za pomocą protokołu HTTP 401 Brak autoryzacji i nagłówka HTTP uwierzytelniania WWW zawierającego błąd i wyzwanie oświadczenia. Klient musi przeanalizować ten nagłówek i uzyskać nowy token od wystawcy tokenu, przedstawiając wyzwanie oświadczeń, jeśli istnieje. Klienci nie powinni ponawiać próby uzyskania dostępu do usługi warstwy środkowej przy użyciu buforowanego tokenu dostępu.
{
"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\"]}}}"
}
Uzyskiwanie dostępu do zabezpieczonego zasobu przy użyciu tokenu dostępu
Teraz usługa warstwy środkowej może używać tokenu uzyskanego wcześniej, aby wysyłać uwierzytelnione żądania do podrzędnego internetowego interfejsu API, ustawiając token w nagłówku Authorization .
Przykład
GET /v1.0/me HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Asercji SAML uzyskanych przy użyciu przepływu OAuth2.0 OBO
Niektóre usługi internetowe oparte na protokole OAuth muszą uzyskiwać dostęp do innych interfejsów API usługi internetowej, które akceptują asercji SAML w nieinterakcyjnych przepływach. Identyfikator Entra firmy Microsoft może dostarczyć asercji SAML w odpowiedzi na przepływ On-Behalf-Of, który używa usługi internetowej opartej na protokole SAML jako zasobu docelowego.
Jest to niestandardowe rozszerzenie przepływu OAuth 2.0 On-Behalf-Of, które umożliwia aplikacji opartej na protokole OAuth2 dostęp do punktów końcowych interfejsu API usługi internetowej korzystających z tokenów JĘZYKA SAML.
Napiwek
Po wywołaniu usługi internetowej chronionej przy użyciu protokołu SAML z aplikacji internetowej frontonu można po prostu wywołać interfejs API i zainicjować normalny przepływ uwierzytelniania interakcyjnego przy użyciu istniejącej sesji użytkownika. Przepływ OBO należy używać tylko wtedy, gdy wywołanie typu service-to-service wymaga tokenu SAML w celu zapewnienia kontekstu użytkownika.
Uzyskiwanie tokenu SAML przy użyciu żądania OBO z udostępnionym wpisem tajnym
Żądanie service-to-service dla asercji SAML zawiera następujące parametry:
| Parametr | Type | Opis |
|---|---|---|
| grant_type | wymagane | Typ żądania tokenu. W przypadku żądania używającego JWT wartość musi mieć wartość urn:ietf:params:oauth:grant-type:jwt-bearer. |
| assertion | wymagane | Wartość tokenu dostępu używanego w żądaniu. |
| client_id | wymagane | Identyfikator aplikacji przypisany do usługi wywołującej podczas rejestracji za pomocą identyfikatora Entra firmy Microsoft. Aby znaleźć identyfikator aplikacji w centrum administracyjnym firmy Microsoft Entra, przejdź do pozycji Aplikacje> tożsamości>Rejestracje aplikacji a następnie wybierz nazwę aplikacji. |
| client_secret | wymagane | Klucz zarejestrowany dla usługi wywołującej w identyfikatorze Entra firmy Microsoft. Ta wartość powinna być zanotowany w momencie rejestracji. Wzorzec uwierzytelniania podstawowego zamiast podawania poświadczeń w nagłówku autoryzacji na RFC 6749 jest również obsługiwany. |
| zakres | wymagane | Rozdzielona spacjami lista zakresów żądania tokenu. Aby uzyskać więcej informacji, zobacz zakresy. Sam sam język SAML nie ma pojęcia zakresów, ale służy do identyfikowania docelowej aplikacji SAML, dla której chcesz otrzymać token. W przypadku tego przepływu OBO wartość zakresu musi zawsze być identyfikatorem jednostki SAML z dołączonym identyfikatorem /.default . Na przykład w przypadku, gdy identyfikator jednostki aplikacji SAML to https://testapp.contoso.com, żądany zakres powinien mieć wartość https://testapp.contoso.com/.default. Jeśli identyfikator jednostki nie zaczyna się od schematu identyfikatora URI, takiego jak https:, firma Microsoft Entra prefiksuje identyfikator jednostki za pomocą polecenia spn:. W takim przypadku musisz zażądać zakresu spn:<EntityID>/.default, na przykład spn:testapp/.default w przypadku, gdy identyfikator jednostki to testapp. Żądana wartość zakresu określa wynikowy Audience element w tokenie SAML, który może być ważny dla aplikacji SAML odbierającej token. |
| requested_token_use | wymagane | Określa sposób przetwarzania żądania. W przepływie On-Behalf-Of wartość musi mieć wartość on_behalf_of. |
| requested_token_type | wymagane | Określa typ żądanego tokenu. Wartość może być urn:ietf:params:oauth:token-type:saml2 lub urn:ietf:params:oauth:token-type:saml1 w zależności od wymagań zasobu, do których uzyskuje się dostęp. |
Odpowiedź zawiera token SAML zakodowany w formacie UTF8 i Base 64url.
- SubjectConfirmationData dla asercji SAML pochodzącej z wywołania OBO: jeśli aplikacja docelowa wymaga
Recipientwartości wSubjectConfirmationDataelemecie , wartość musi być skonfigurowana jako pierwszy niewildcard Adres URL odpowiedzi w konfiguracji aplikacji zasobów. Ponieważ domyślny adres URL odpowiedzi nie jest używany do określaniaRecipientwartości, może być konieczne zmiana kolejności adresów URL odpowiedzi w konfiguracji aplikacji, aby upewnić się, że jest używany pierwszy adres URL odpowiedzi innej niżwildcard. Aby uzyskać więcej informacji, zobacz Adresy URL odpowiedzi. - Węzeł SubjectConfirmationData: węzeł nie może zawierać atrybutu
InResponseTo, ponieważ nie jest częścią odpowiedzi SAML. Aplikacja odbierający token SAML musi mieć możliwość akceptowania asercji SAML bez atrybutuInResponseTo. - Uprawnienia interfejsu API: musisz dodać niezbędne uprawnienia interfejsu API w aplikacji warstwy środkowej, aby zezwolić na dostęp do aplikacji SAML, aby mogła zażądać tokenu dla
/.defaultzakresu aplikacji SAML. - Zgoda: Zgoda musi zostać udzielona w celu otrzymania tokenu SAML zawierającego dane użytkownika w przepływie protokołu OAuth. Aby uzyskać informacje, zobacz Uzyskiwanie zgody dla aplikacji warstwy środkowej.
Odpowiedź z asercją SAML
| Parametr | Opis |
|---|---|
| token_type | Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje identyfikator Entra firmy Microsoft, jest bearer. Aby uzyskać więcej informacji na temat tokenów elementu nośnego, zobacz OAuth 2.0 Authorization Framework: Bearer Token Usage (RFC 6750). |
| zakres | Zakres dostępu udzielony w tokenie. |
| expires_in | Czas ważności tokenu dostępu (w sekundach). |
| expires_on | Czas wygaśnięcia tokenu dostępu. Data jest reprezentowana jako liczba sekund od 1970-01-01T0:0:0Z UTC do czasu wygaśnięcia. Ta wartość służy do określania okresu istnienia buforowanych tokenów. |
| zasób | Identyfikator URI identyfikatora aplikacji usługi odbierania (zabezpieczony zasób). |
| access_token | Parametr, który zwraca asercji SAML. |
| refresh_token | Token odświeżania. Usługa wywołująca może użyć tego tokenu, aby zażądać innego tokenu dostępu po wygaśnięciu bieżącej asercji SAML. |
- token_type: Nośny
- expires_in: 3296
- ext_expires_in: 0
- expires_on: 1529627844
- Zasobów:
https://api.contoso.com - access_token: <asercji SAML>
- issued_token_type: urn:ietf:params:oauth:token-type:saml2
- refresh_token: <odświeżanie tokenu>
Uzyskiwanie zgody dla aplikacji warstwy środkowej
Celem przepływu OBO jest zapewnienie prawidłowej zgody, aby aplikacja kliencka mogła wywołać aplikację warstwy środkowej, a aplikacja warstwy środkowej ma uprawnienia do wywoływania zasobu zaplecza. W zależności od architektury lub użycia aplikacji należy wziąć pod uwagę następujące kwestie, aby upewnić się, że przepływ OBO zakończy się pomyślnie:
Domyślna i połączona zgoda
Aplikacja warstwy środkowej dodaje klienta do listy znanych aplikacji klienckich (knownClientApplications) w manifeście. Jeśli klient wyzwoli monit o wyrażenie zgody, przepływ zgody jest zarówno dla siebie, jak i aplikacji warstwy środkowej. W Platforma tożsamości Microsoft odbywa się to przy użyciu .default zakresu. Zakres .default jest specjalnym zakresem używanym do żądania zgody na dostęp do wszystkich zakresów, dla których aplikacja ma uprawnienia. Jest to przydatne, gdy aplikacja musi uzyskać dostęp do wielu zasobów, ale użytkownik powinien być monitowany tylko o zgodę raz.
Podczas wyzwalania ekranu zgody przy użyciu znanych aplikacji klienckich i .defaultna ekranie zgody są wyświetlane uprawnienia zarówno klienta do interfejsu API warstwy środkowej, jak i żądania uprawnień wymaganych przez interfejs API warstwy środkowej. Użytkownik udziela zgody dla obu aplikacji, a następnie działa przepływ OBO.
Usługa zasobów (API) zidentyfikowana w żądaniu powinna być interfejsem API, dla którego aplikacja kliencka żąda tokenu dostępu w wyniku logowania użytkownika. Na przykład scope=openid https://middle-tier-api.example.com/.default (aby zażądać tokenu dostępu dla interfejsu API warstwy środkowej) lub scope=openid offline_access .default (jeśli zasób nie jest identyfikowany, domyślnie jest używany program Microsoft Graph).
Niezależnie od tego, który interfejs API jest identyfikowany w żądaniu autoryzacji, monit o wyrażenie zgody jest połączony ze wszystkimi wymaganymi uprawnieniami skonfigurowanymi dla aplikacji klienckiej. Wszystkie wymagane uprawnienia skonfigurowane dla każdego interfejsu API warstwy środkowej wymienionej na liście wymaganych uprawnień klienta, które zidentyfikowały klienta jako znaną aplikację kliencką, są również uwzględniane.
Aplikacje wstępnie uwierzytelnione
Zasoby mogą wskazywać, że dana aplikacja zawsze ma uprawnienia do odbierania określonych zakresów. Jest to przydatne, aby połączenia między klientem frontonu a zasobem zaplecza były bardziej bezproblemowe. Zasób może zadeklarować wiele wstępnie uwierzytelnionych aplikacji (preAuthorizedApplications) w manifeście. Każda taka aplikacja może zażądać tych uprawnień w przepływie OBO i otrzymać je bez wyrażania zgody przez użytkownika.
zgoda administratora
Administrator dzierżawy może zagwarantować, że aplikacje mają uprawnienia do wywoływania wymaganych interfejsów API, udzielając zgody administratora dla aplikacji warstwy środkowej. W tym celu administrator może znaleźć aplikację warstwy środkowej w swojej dzierżawie, otworzyć wymaganą stronę uprawnień i wybrać uprawnienie dla aplikacji. Aby dowiedzieć się więcej na temat zgody administratora, zobacz dokumentację dotyczącą zgody i uprawnień.
Korzystanie z pojedynczej aplikacji
W niektórych scenariuszach można mieć tylko jedną parę klientów warstwy środkowej i frontonu. W tym scenariuszu łatwiej jest uczynić tę pojedynczą aplikację, co całkowicie neguje potrzebę zastosowania aplikacji warstwy środkowej. Aby uwierzytelnić się między frontonem a internetowym interfejsem API, możesz użyć plików cookie, id_token lub tokenu dostępu żądanego dla samej aplikacji. Następnie zażądaj zgody z tej pojedynczej aplikacji na zasób zaplecza.
Zobacz też
Dowiedz się więcej na temat protokołu OAuth 2.0 i innego sposobu wykonywania usługi w celu uwierzytelniania za pomocą poświadczeń klienta.