Udostępnij za pośrednictwem


Platforma tożsamości firmy Microsoft i przepływ poświadczeń klienta OAuth 2.0

Przepływ przyznawania poświadczeń dla klienta OAuth 2.0 pozwala usłudze internetowej (poufny klient) używać własnych poświadczeń do uwierzytelniania, bez podszywania się pod użytkownika, gdy wywołuje inną usługę sieciową. Grant określony w RFC 6749, czasami nazywany dwunożnym OAuth, może być używany do uzyskiwania dostępu do zasobów hostowanych w Internecie przy użyciu tożsamości aplikacji. Ten typ jest często używany w przypadku interakcji serwer-serwer, które muszą być uruchamiane w tle, bez natychmiastowej interakcji z użytkownikiem i jest często określane jako demony lub konta usług .

W przepływie poświadczeń klienta uprawnienia są przyznawane bezpośrednio do samej aplikacji przez administratora. Gdy aplikacja przedstawia token do zasobu, zasób wymusza, że sama aplikacja ma autoryzację do wykonania akcji, ponieważ nie ma żadnego użytkownika zaangażowanego w uwierzytelnianie. W tym artykule opisano oba kroki niezbędne do wykonania następujących czynności:

W tym artykule opisano sposób programowania bezpośrednio względem protokołu w aplikacji. Jeśli to możliwe, zalecamy użycie obsługiwanych bibliotek uwierzytelniania firmy Microsoft (MSAL), aby uzyskać tokeny i wywołać zabezpieczone internetowe interfejsy API. Możesz również zapoznać się z przykładowymi aplikacjami korzystającymi z biblioteki MSAL. Na marginesie, tokeny odświeżania nigdy nie będą przyznawane przy użyciu tego przepływu, jako że client_id i client_secret (który byłby wymagany do uzyskania tokenu odświeżania) mogą być użyte do uzyskania tokenu dostępu.

Aby zapewnić wyższy poziom bezpieczeństwa, platforma tożsamości firmy Microsoft umożliwia też usłudze wywołującej uwierzytelnianie przy użyciu certyfikatu lub poświadczeń federacyjnych zamiast wspólnej tajemnicy. Ponieważ są używane własne poświadczenia aplikacji, te poświadczenia muszą być bezpieczne. Nigdy opublikować to poświadczenie w kodzie źródłowym, osadzić je na stronach internetowych lub użyć go w szeroko rozproszonej aplikacji natywnej.

Diagram protokołu

Cały przepływ poświadczeń klienta wygląda podobnie do poniższego diagramu. W dalszej części tego artykułu opisano poszczególne kroki.

diagram przedstawiający przepływ poświadczeń klienta

Uzyskiwanie bezpośredniej autoryzacji

Aplikacja zazwyczaj otrzymuje bezpośrednią autoryzację w celu uzyskania dostępu do zasobu na jeden z dwóch sposobów:

Te dwie metody są najczęściej stosowane w Microsoft Entra ID i zalecamy je dla klientów i zasobów wykonujących przepływ poświadczeń klienta. Zasób może również autoryzować swoich klientów na inne sposoby. Każdy serwer zasobów może wybrać metodę, która ma największe znaczenie dla swojej aplikacji.

Listy kontroli dostępu

Dostawca zasobów może wymusić sprawdzanie autoryzacji na podstawie listy identyfikatorów aplikacji (klienta), do których zna i przyznaje określony poziom dostępu. Gdy zasób odbiera token z platformy tożsamości firmy Microsoft, może zdekodować token i wyodrębnić identyfikator aplikacji klienta z roszczeń appid i iss. Następnie porównuje aplikację z listą kontroli dostępu (ACL), którą obsługuje. Stopień szczegółowości i metody ACL mogą się prawdopodobnie znacznie różnić między zasobami.

Typowym przypadkiem użycia jest wykorzystanie ACL do przeprowadzania testów na aplikacji internetowej lub na internetowym interfejsie API. Internetowy interfejs API może udzielić tylko podzestawu pełnych uprawnień dla określonego klienta. Aby uruchomić kompleksowe testy interfejsu API, możesz utworzyć klienta testowego, który uzyskuje tokeny z platformy tożsamości firmy Microsoft, a następnie wysyła je do interfejsu API. Następnie API sprawdza ACL dla aplikacji testowego klienta, aby uzyskać pełny dostęp do całej funkcjonalności API. Jeśli używasz tego rodzaju listy ACL, upewnij się, że nie tylko wartość appid obiektu wywołującego jest zweryfikowana, ale także że wartość iss tokena jest zaufana.

Ten typ autoryzacji jest typowy dla procesów działających w tle i kont usług, które muszą uzyskiwać dostęp do danych należących do użytkowników indywidualnych, posiadających osobiste konta Microsoft. W przypadku danych należących do organizacji zalecamy uzyskanie niezbędnej autoryzacji za pośrednictwem uprawnień aplikacji.

Kontrolowanie tokenów bez roszczenia roles

Aby włączyć ten wzorzec autoryzacji opartej na listach ACL, identyfikator Entra firmy Microsoft nie wymaga autoryzacji aplikacji do pobierania tokenów dla innej aplikacji. W związku z tym tokeny tylko dla aplikacji można wystawiać bez oświadczenia roles. Aplikacje, które uwidaczniają interfejsy API, muszą implementować kontrole uprawnień w celu akceptowania tokenów.

Jeśli chcesz uniemożliwić aplikacjom uzyskiwanie tokenów dostępu tylko dla aplikacji bez przypisanych ról, upewnij się, że wymagania dotyczące przypisywania są włączone dla twojej aplikacji. Spowoduje to uniemożliwienie użytkownikom i aplikacjom bez przypisanych ról uzyskanie tokenu dla tej aplikacji.

Uprawnienia aplikacji

Zamiast używać list ACL, możesz użyć interfejsów API, aby uwidocznić zestaw uprawnień aplikacji . Są one przyznawane aplikacji przez administratora organizacji i mogą być używane tylko do uzyskiwania dostępu do danych należących do tej organizacji i jej pracowników. Na przykład program Microsoft Graph uwidacznia kilka uprawnień aplikacji w celu wykonania następujących czynności:

  • Odczytywanie poczty we wszystkich skrzynkach pocztowych
  • Odczytywanie i zapisywanie poczty we wszystkich skrzynkach pocztowych
  • Wyślij wiadomość e-mail jako dowolny użytkownik
  • Odczytywanie danych katalogu

Aby używać ról aplikacji (uprawnień aplikacji) z własnym interfejsem API (w przeciwieństwie do programu Microsoft Graph), musisz najpierw uwidocznić role aplikacji w rejestracji aplikacji interfejsu API w centrum administracyjnym firmy Microsoft Entra. Następnie skonfigurować role aplikacji wymagane, wybierając te uprawnienia podczas rejestracji aplikacji klienckiej. Jeśli nie określiłeś żadnych ról aplikacji w rejestracji aplikacji interfejsu API, nie będziesz mógł określić uprawnień aplikacji do tego interfejsu API w rejestracji aplikacji klienckiej w centrum administracyjnym Microsoft Entra.

Podczas uwierzytelniania się jako aplikacja (w przeciwieństwie do uwierzytelniania się jako użytkownik), nie można używać delegowanych uprawnień, ponieważ nie ma użytkownika, który mógłby działać w jego imieniu. Musisz użyć uprawnień aplikacji, znanych również jako role aplikacji, które są przyznawane przez administratora lub przez właściciela interfejsu API.

Aby uzyskać więcej informacji na temat uprawnień aplikacji, zobacz Uprawnienia i zgoda.

Zazwyczaj podczas tworzenia aplikacji korzystającej z uprawnień aplikacji aplikacja wymaga strony lub widoku, na którym administrator zatwierdza uprawnienia aplikacji. Ta strona może być częścią przepływu logowania aplikacji, części ustawień aplikacji lub dedykowanego przepływu połączenia . Często warto wyświetlić widok połączenia dopiero po zalogowaniu się użytkownika przy użyciu konta Microsoft służbowego lub szkolnego.

Jeśli zalogujesz użytkownika do aplikacji, możesz zidentyfikować organizację, do której należy użytkownik, zanim poprosisz użytkownika o zatwierdzenie uprawnień aplikacji. Chociaż nie jest to ściśle konieczne, może to pomóc w utworzeniu bardziej intuicyjnego środowiska dla użytkowników. Aby zalogować użytkownika, postępuj zgodnie z samouczkami Microsoft Identity Platform Protocol.

Żądanie uprawnień od administratora katalogu

Gdy jesteś gotowy do żądania uprawnień od administratora organizacji, możesz przekierować użytkownika na platformę tożsamości Microsoft punkt końcowy wyrażania zgody przez administratora.

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

Porada eksperta: Sprawdź wklejenie następującego żądania w przeglądarce.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions
Parametr Warunek Opis
tenant Wymagane Najemca katalogu, od którego chcesz uzyskać uprawnienia. Może to być w formacie GUID lub przyjaznej nazwy. Jeśli nie wiesz, do którego najemcy należy użytkownik i chcesz umożliwić mu logowanie się z użyciem dowolnego najemcy, użyj common.
client_id Wymagane Identyfikator aplikacji (klienta) przypisany do Twojej aplikacji przez Microsoft Entra admin center – App registrations.
redirect_uri Wymagane Identyfikator URI przekierowania, na który ma zostać wysłana odpowiedź, aby aplikacja mogła ją obsłużyć. Musi dokładnie odpowiadać jednemu z identyfikatorów URI przekierowania zarejestrowanych w portalu, z tą różnicą, że musi być zakodowany w formacie URL i może mieć dodatkowe segmenty ścieżki.
state Zalecane Wartość uwzględniona w żądaniu, która jest również zwracana w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Stan jest używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia, na przykład strony lub widoku, na której się znajdowały.

W tym momencie identyfikator Entra firmy Microsoft wymusza, że tylko administrator dzierżawy może zalogować się w celu ukończenia żądania. Administrator zostanie poproszony o zatwierdzenie wszystkich bezpośrednich uprawnień aplikacyjnych, które zostały przez Ciebie zażądane dla aplikacji w portalu rejestracji aplikacji.

Odpowiedź pomyślna

Jeśli administrator zatwierdzi uprawnienia aplikacji, pomyślna odpowiedź wygląda następująco:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parametr Opis
tenant Dzierżawca katalogu, który przyznał Twojej aplikacji żądane uprawnienia, w formacie GUID.
state Wartość uwzględniona w żądaniu, która jest również zwracana w odpowiedzi na token. Może to być ciąg dowolnej zawartości. Stan jest używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia, na przykład strony lub widoku, na której się znajdowały.
admin_consent Ustaw wartość true.
Odpowiedź na błąd

Jeśli administrator nie zatwierdzi uprawnień aplikacji, odpowiedź, która zakończyła się niepowodzeniem, wygląda następująco:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametr Opis
error Ciąg kodu błędu, którego można użyć do klasyfikowania typów błędów i którego można użyć do reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu głównej przyczyny błędu.

Po otrzymaniu pomyślnej odpowiedzi z punktu końcowego aprowizacji aplikacji aplikacja uzyskała uprawnienia bezpośrednie aplikacji, których zażądała. Teraz możesz zażądać tokenu dla żądanego zasobu.

Uzyskiwanie tokenu

Po uzyskaniu niezbędnej autoryzacji dla aplikacji przejdź do uzyskiwania tokenów dostępu dla interfejsów API. Aby uzyskać token przy użyciu udzielenia poświadczeń klienta, wyślij żądanie POST do platformy tożsamości /token Microsoft. Istnieje kilka różnych przypadków:

Pierwszy przypadek: żądanie tokenu dostępu z współdzielonym sekretem

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=qWgdYAmab0YSkuL1qKv5bPX
&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'
Parametr Warunek Opis
tenant Wymagane Jednostka dzierżawy katalogu, przeciwko której aplikacja planuje działać, w formacie GUID lub nazwy domeny.
client_id Wymagane Identyfikator aplikacji przypisany do aplikacji. Te informacje można znaleźć w portalu, w którym zarejestrowano aplikację.
scope Wymagane Wartość przekazana dla parametru scope w tym żądaniu powinna być identyfikatorem zasobu (identyfikatorem URI aplikacji) żądanego zasobu, z sufiksem .default. Wszystkie uwzględnione zakresy muszą dotyczyć jednego zasobu. Uwzględnienie zakresów dla wielu zasobów spowoduje wystąpienie błędu.
W przykładzie programu Microsoft Graph wartość to https://graph.microsoft.com/.default. Ta wartość informuje platformę tożsamości firmy Microsoft, że ze wszystkich uprawnień aplikacji bezpośrednich skonfigurowanych dla aplikacji punkt końcowy powinien wydać token dla tych skojarzonych z zasobem, którego chcesz użyć. Aby dowiedzieć się więcej na temat zakresu /.default, zobacz dokumentację zgody .
client_secret Wymagane Tajny klucz klienta, który wygenerowałeś dla swojej aplikacji w portalu rejestracji aplikacji. Klucz tajny klienta musi być zakodowany w adresie URL przed wysłaniem. Wzorzec uwierzytelniania podstawowego, polegający na podawaniu poświadczeń bezpośrednio w nagłówku autoryzacji, zgodnie ze standardem RFC 6749, jest również obsługiwany.
grant_type Wymagane Musi być ustawione na client_credentials.

Drugi przypadek: żądanie tokenu dostępu z certyfikatem

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
Parametr Warunek Opis
tenant Wymagane Aplikacja ma działać przeciwko dzierżawcy katalogu w formacie GUID lub nazwy domeny.
client_id Wymagane Identyfikator aplikacji (klienta) przypisany do aplikacji.
scope Wymagane Wartość przekazana dla parametru scope w tym żądaniu powinna być identyfikatorem zasobu (identyfikatorem URI aplikacji) żądanego zasobu, z sufiksem .default. Wszystkie uwzględnione zakresy muszą dotyczyć jednego zasobu. Uwzględnienie zakresów dla wielu zasobów spowoduje wystąpienie błędu.
W przykładzie programu Microsoft Graph wartość to https://graph.microsoft.com/.default. Ta wartość informuje platformę tożsamości firmy Microsoft, że ze wszystkich uprawnień aplikacji bezpośrednich skonfigurowanych dla aplikacji punkt końcowy powinien wydać token dla tych skojarzonych z zasobem, którego chcesz użyć. Aby dowiedzieć się więcej na temat zakresu /.default, zobacz dokumentację zgody .
client_assertion_type Wymagane Wartość musi być ustawiona na urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion Wymagane Potwierdzenie (token internetowy JSON), który należy utworzyć i podpisać przy użyciu certyfikatu zarejestrowanego jako poświadczenia aplikacji. Przeczytaj o uwierzytelnieniach certyfikatu, aby dowiedzieć się, jak zarejestrować certyfikat i format potwierdzenia.
grant_type Wymagane Musi być ustawione na client_credentials.

Parametry żądania opartego na certyfikatach różnią się tylko w jeden sposób od żądania opartego na współużytkowanym sekrecie: parametr client_secret jest zastępowany przez parametry client_assertion_type i client_assertion.

Trzeci przypadek: żądanie token dostępu z poświadczeniem federacyjnym

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
Parametr Warunek Opis
client_assertion Wymagane Asercja (token internetowy JWT lub JSON), którą aplikacja pobiera od innego dostawcy tożsamości spoza platformy tożsamości firmy Microsoft, takiej jak Kubernetes. Specyfika tego JWT powinna zostać zarejestrowana w aplikacji jako poświadczenie tożsamości federacyjnej. Przeczytaj o federacji tożsamości obciążeń, aby poznać sposób konfiguracji i używania asercji generowanych przez innych dostawców tożsamości.

Wszystko w żądaniu jest takie samo jak w przypadku przepływu opartego na certyfikatach, z istotnym wyjątkiem dotyczącym źródła client_assertion. W tym przepływie aplikacja nie tworzy samej asercji JWT. Zamiast tego aplikacja używa zestawu JWT utworzonego przez innego dostawcę tożsamości. Jest to nazywane federacją tożsamości dla obciążenia , gdzie tożsamość aplikacji na innej platformie tożsamości jest używana do uzyskiwania tokenów wewnątrz platformy tożsamości firmy Microsoft. Jest to najlepsze rozwiązanie w przypadku scenariuszy obejmujących wiele chmur, takich jak hostowanie obliczeń poza platformą Azure, ale uzyskiwanie dostępu do interfejsów API chronionych przez platformę tożsamości firmy Microsoft. Aby uzyskać informacje o wymaganym formacie tokenów JWT wydanych przez innych dostawców tożsamości, przeczytaj o formacie asercji .

Odpowiedź pomyślna

Pomyślna odpowiedź z dowolnej metody wygląda następująco:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Parametr Opis
access_token Żądany token dostępu. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API.
token_type Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje platforma tożsamości firmy Microsoft, jest bearer.
expires_in Czas ważności tokenu dostępu (w sekundach).

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ług 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 konsumenckich (konta Microsoft). Odczytywanie tokenów jest przydatnym narzędziem do debugowania i uczenia się, ale nie należy polegać na tym w kodzie ani zakładać szczególnych informacji o tokenach, które nie są przeznaczone dla API, które kontrolujesz.

Odpowiedź na błąd

Odpowiedź na błąd (400 Nieprawidłowe żądanie) wygląda następująco:

{
  "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"
}
Parametr Opis
error Ciąg kodu błędu, którego można użyć do klasyfikowania typów błędów występujących i reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu głównej przyczyny błędu uwierzytelniania.
error_codes Lista kodów błędów specyficznych dla usługi STS, które mogą pomóc w diagnostyce.
timestamp Czas wystąpienia błędu.
trace_id Unikatowy identyfikator żądania, który pomoże w diagnostyce.
correlation_id Unikatowy identyfikator żądania w celu ułatwienia diagnostyki w całym systemie.

Używanie tokenu

Po uzyskaniu tokenu użyj tokenu, aby wysyłać żądania do zasobu. Po wygaśnięciu tokenu powtórz żądanie do punktu końcowego /token, aby uzyskać nowy token dostępu.

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

Spróbuj wykonać następujące polecenie w terminalu, upewniając się, że zamienisz token na własny.

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

Przykłady kodu i inne dokumenty

Przeczytaj dokumentację przeglądową poświadczeń klienta z biblioteki uwierzytelniania Microsoftu.

Przykład Platforma Opis
active-directory-dotnetcore-daemon-v2 .NET 6.0+ Aplikacja ASP.NET Core, która wyświetla użytkowników dzierżawy wykonującej zapytanie dotyczące programu Microsoft Graph przy użyciu tożsamości aplikacji, a nie w imieniu użytkownika. W przykładzie pokazano również odmianę używającą certyfikatów do uwierzytelniania.
active-directory-dotnet-daemon-v2 ASP.NET MVC Aplikacja internetowa, która synchronizuje dane z programu Microsoft Graph przy użyciu tożsamości aplikacji, a nie w imieniu użytkownika.
ms-identity-javascript-nodejs-console Node.js konsola Aplikacja Node.js, która wyświetla użytkowników dzierżawcy, wysyłając zapytanie do usługi Microsoft Graph przy użyciu tożsamości aplikacji