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

  • Artykuł

Poświadczenia klienta OAuth 2.0 umożliwiają przepływowi usługi sieci Web (poufnego klienta) używanie własnych poświadczeń zamiast personifikacji użytkownika w celu uwierzytelnienia podczas wywoływania innej usługi internetowej. Grant określony w RFC 6749, czasami nazywany dwunogim uwierzytelnianiem OAuth, może służyć 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ą działać 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, 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. Możesz również odwołać się do przykładowych aplikacji korzystających z biblioteki MSAL. W ramach uwagi bocznej tokeny odświeżania nigdy nie zostaną przyznane za pomocą tego przepływu jako client_id i client_secret (co byłoby wymagane do uzyskania tokenu odświeżania) może zamiast tego służyć do uzyskania tokenu dostępu.

W celu zapewnienia wyższego poziomu Platforma tożsamości Microsoft umożliwia również usłudze wywołującej uwierzytelnianie przy użyciu certyfikatu lub poświadczeń federacyjnych zamiast wspólnego wpisu tajnego. Ponieważ są używane własne poświadczenia aplikacji, te poświadczenia muszą być bezpieczne. Nigdy nie należy publikować tych poświadczeń w kodzie źródłowym, osadzać je na stronach internetowych ani używać 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 showing the client credentials flow

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ą najbardziej typowe w identyfikatorze Entra firmy Microsoft i zalecamy ich obsługę 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 otrzyma token z Platforma tożsamości Microsoft, może zdekodować token i wyodrębnić identyfikator aplikacji klienta z appid oświadczeń i iss . Następnie porównuje aplikację z listą kontroli dostępu (ACL), którą obsługuje. Stopień szczegółowości i metody listy ACL może się znacznie różnić między zasobami.

Typowym przypadkiem użycia jest użycie listy ACL do uruchamiania testów dla aplikacji internetowej lub internetowego interfejsu API. Internetowy interfejs API może udzielić tylko podzestawu pełnych uprawnień do określonego klienta. Aby uruchomić kompleksowe testy interfejsu API, możesz utworzyć klienta testowego, który uzyskuje tokeny z Platforma tożsamości Microsoft, a następnie wysyła je do interfejsu API. Następnie interfejs API sprawdza listę ACL dla identyfikatora aplikacji testowego klienta w celu uzyskania pełnego dostępu do całej funkcjonalności interfejsu API. Jeśli używasz tego rodzaju listy ACL, upewnij się, że sprawdzasz nie tylko wartość obiektu appid wywołującego, ale także sprawdź, czy iss wartość tokenu jest zaufana.

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

Kontrolowanie tokenów bez roles oświadczenia

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 mogą być wystawiane bez roles oświadczenia. 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 do aplikacji bez ról, upewnij się, że wymagania dotyczące przypisywania są włączone dla aplikacji. Spowoduje to zablokowanie użytkownikom i aplikacjom bez przypisanych ról w celu uzyskania 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 skonfiguruj wymagane role aplikacji, wybierając te uprawnienia w rejestracji aplikacji klienckiej. Jeśli nie uwidoczniłeś żadnych ról aplikacji w rejestracji aplikacji interfejsu API, nie będzie można określić uprawnień aplikacji do tego interfejsu API w rejestracji aplikacji klienckiej w centrum administracyjnym firmy Microsoft Entra.

Podczas uwierzytelniania jako aplikacji (w przeciwieństwie do użytkownika) nie można używać uprawnień delegowanych, ponieważ nie ma żadnego użytkownika do działania w imieniu aplikacji. 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 . Aplikacja często ma sens, aby pokazać ten widok połączenia dopiero po zalogowaniu się użytkownika przy użyciu konta Microsoft służbowego.

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 dotyczącymi protokołu Platforma tożsamości Microsoft.

Żądanie uprawnień od administratora katalogu

Gdy wszystko będzie gotowe do żądania uprawnień od administratora organizacji, możesz przekierować użytkownika do punktu końcowego zgody administratora Platforma tożsamości Microsoft.

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

Pro tip: Spróbuj wkleić następujące żądanie 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 Wymagania Dzierżawa katalogu, z której chcesz zażądać uprawnień. Może to być w formacie GUID lub przyjaznej nazwy. Jeśli nie wiesz, do której dzierżawy należy użytkownik i chcesz zezwolić im na logowanie się przy użyciu dowolnej dzierżawy, użyj polecenia common.
client_id Wymagania Identyfikator aplikacji (klienta) przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
redirect_uri Wymagania Identyfikator URI przekierowania, w którym ma zostać wysłana odpowiedź do obsługi aplikacji. Musi być dokładnie zgodny z jednym z identyfikatorów URI przekierowania zarejestrowanych w portalu, z tą różnicą, że musi być zakodowany pod adresem URL i może mieć dodatkowe segmenty ścieżki.
state Zalecane Wartość uwzględniona w żądaniu zwróconym również 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ń aplikacji żądanych 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żawa katalogu, która przyznała aplikacji uprawnienia, których zażądała, w formacie GUID.
state 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.
admin_consent Ustaw wartość True.
Odpowiedź błędna

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 /token Platforma tożsamości Microsoft. Istnieje kilka różnych przypadków:

Pierwszy przypadek: żądanie tokenu dostępu z udostępnionym wpisem tajnym

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=sampleCredentials
&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 Wymagania Dzierżawa katalogu, w którym aplikacja planuje działać w formacie GUID lub nazwy domeny.
client_id Wymagania Identyfikator aplikacji przypisany do aplikacji. Te informacje można znaleźć w portalu, w którym zarejestrowano aplikację.
scope Wymagania Wartość przekazana dla parametru scope w tym żądaniu powinna być identyfikatorem zasobu (identyfikatorem URI aplikacji) żądanego zasobu umieszczonego 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 Platforma tożsamości 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 o /.default zakresie, zobacz dokumentację dotyczącą zgody.
client_secret Wymagania Wpis tajny klienta wygenerowany dla aplikacji w portalu rejestracji aplikacji. Klucz tajny klienta musi być zakodowany w adresie URL przed wysłaniem. Wzorzec uwierzytelniania podstawowego zamiast podawania poświadczeń w nagłówku autoryzacji na RFC 6749 jest również obsługiwany.
grant_type Wymagania Musi być ustawiona wartość 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 Wymagania Dzierżawa katalogu, w którym aplikacja planuje działać w formacie GUID lub nazwy domeny.
client_id Wymagania Identyfikator aplikacji (klienta) przypisany do aplikacji.
scope Wymagania Wartość przekazana dla parametru scope w tym żądaniu powinna być identyfikatorem zasobu (identyfikatorem URI aplikacji) żądanego zasobu umieszczonego 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 Platforma tożsamości 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 o /.default zakresie, zobacz dokumentację dotyczącą zgody.
client_assertion_type Wymagania Wartość musi być ustawiona na 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. Przeczytaj o poświadczeniach certyfikatu , aby dowiedzieć się, jak zarejestrować certyfikat i format potwierdzenia.
grant_type Wymagania Musi być ustawiona wartość client_credentials.

Parametry żądania opartego na certyfikatach różnią się tylko w jeden sposób od udostępnionego żądania opartego na wpisach tajnych: client_secret parametr jest zastępowany przez client_assertion_type parametry i client_assertion .

Trzeci przypadek: żądanie tokenu dostępu z poświadczeniami federacyjnymi

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 Wymagania Asercja (token internetowy JWT lub JSON), którą aplikacja pobiera od innego dostawcy tożsamości poza Platforma tożsamości Microsoft, na przykład Kubernetes. Specyfika tego zestawu JWT musi być zarejestrowana w aplikacji jako poświadczenie tożsamości federacyjnej. Przeczytaj o federacji tożsamości obciążeń, aby dowiedzieć się, jak skonfigurować i używać asercji generowanych przez innych dostawców tożsamości.

Wszystkie elementy w żądaniu są takie same jak przepływ oparty na certyfikatach, z kluczowym wyjątkiem źródła elementu 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 obciążenia, gdzie tożsamość aplikacji na innej platformie tożsamości jest używana do uzyskiwania tokenów wewnątrz Platforma tożsamości Microsoft. Jest to najlepsze rozwiązanie w przypadku scenariuszy między chmurami, takich jak hostowanie zasobów obliczeniowych poza platformą Azure, ale uzyskiwanie dostępu do interfejsów API chronionych przez Platforma tożsamości Microsoft. Aby uzyskać informacje o wymaganym formacie zestawów JWTs utworzonych 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 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ł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.

Odpowiedź błędna

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 ułatwiającego diagnostykę między składnikami.

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 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Spróbuj wykonać następujące polecenie w terminalu, aby zastąpić token własnym.

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

Przykłady kodu i inne dokumenty

Przeczytaj dokumentację przeglądu poświadczeń klienta z biblioteki Microsoft Authentication Library

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 konsola Node.js Aplikacja Node.js, która wyświetla użytkowników dzierżawy, wysyłając zapytanie do programu Microsoft Graph przy użyciu tożsamości aplikacji