Udostępnij za pośrednictwem


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.

Pokazuje przepływ OAuth2.0 On-Behalf-Of

  1. Aplikacja kliencka wysyła żądanie do interfejsu API A z tokenem A (z oświadczeniem aud interfejsu API A).
  2. 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.
  3. 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.
  4. Token B jest ustawiany przez interfejs API A w nagłówku autoryzacji żądania do interfejsu API B.
  5. 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 Recipient wartości w SubjectConfirmationDataelemecie , 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ślania Recipient wartoś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 atrybutu InResponseTo .
  • 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 /.default zakresu 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>

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:

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.

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.