przepływ przyznawania niejawnego Platforma tożsamości Microsoft i protokołu OAuth 2.0

Platforma tożsamości Microsoft obsługuje niejawny przepływ udzielania OAuth 2.0 zgodnie z opisem w specyfikacji protokołu OAuth 2.0. Definiującą charakterystykę niejawnego udzielenia jest to, że tokeny (tokeny identyfikatorów lub tokeny dostępu) są zwracane bezpośrednio z punktu końcowego /authorize zamiast punktu końcowego /token. Jest to często używane w ramach przepływu kodu autoryzacji, w tym, co jest nazywane "przepływem hybrydowym" — pobieranie tokenu identyfikatora w żądaniu /authorize wraz z kodem autoryzacji.

W tym artykule opisano sposób programowania bezpośrednio względem protokołu w aplikacji w celu żądania tokenów z identyfikatora Entra firmy Microsoft. 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. Przyjrzyj się również przykładowym aplikacjom korzystającym z biblioteki MSAL.

Preferuj przepływ kodu uwierzytelniania

W przypadku niektórych przeglądarek usuwających obsługę plików cookie innych firm niejawny przepływ udzielania nie jest już odpowiednią metodą uwierzytelniania. Dyskretne funkcje logowania jednokrotnego (SSO) w przepływie niejawnym nie działają bez plików cookie innych firm, co powoduje przerwanie aplikacji podczas próby uzyskania nowego tokenu. Zdecydowanie zalecamy, aby wszystkie nowe aplikacje używały przepływu kodu autoryzacji, który obsługuje teraz aplikacje jednostronicowe zamiast niejawnego przepływu. Istniejące aplikacje jednostronicowe powinny być również migrowane do przepływu kodu autoryzacji.

Diagram protokołu

Na poniższym diagramie przedstawiono wygląd całego niejawnego przepływu logowania oraz sekcje opisane szczegółowo w poszczególnych krokach.

Odpowiednie scenariusze dla niejawnego udzielania OAuth2

Niejawne przyznanie jest niezawodne tylko dla początkowej, interaktywnej części przepływu logowania, gdzie brak plików cookie innych firm nie ma wpływu na Twoją aplikację. To ograniczenie oznacza, że należy używać go wyłącznie w ramach przepływu hybrydowego, w którym aplikacja żąda kodu, a także tokenu z punktu końcowego autoryzacji. W przepływie hybrydowym aplikacja otrzymuje kod, który można zrealizować na potrzeby tokenu odświeżania, dzięki czemu sesja logowania aplikacji pozostaje prawidłowa z upływem czasu.

Kiedy należy zezwolić na wystawianie tokenu dostępu lub tokenu identyfikatora w przypadku żądania przy użyciu niejawnego udzielenia lub przepływu hybrydowego?

Niejawne udzielanie i przepływ hybrydowy nie są tak bezpieczne, jak inne przepływy OAuth. Jeśli nie jest to absolutnie wymagane, nie należy zezwalać na wystawianie tokenu dostępu lub identyfikatora w przypadku żądania użycia niejawnego udzielenia lub przepływu hybrydowego w rejestracji aplikacji. Jeśli (lub deweloperzy) używasz biblioteki MSAL (Microsoft Authentication Library) w aplikacji do implementowania uwierzytelniania i autoryzacji, żadne pole nie musi być włączone.

Jeśli jednak (lub deweloperzy) nie korzystasz z biblioteki MSAL w aplikacji, zapoznaj się z poniższą tabelą, aby zrozumieć, kiedy należy włączyć token dostępu lub token identyfikatora.

Typ tworzonej aplikacji	Tokeny, które należy włączyć w rejestracji aplikacji
SPA (jednostronicowa aplikacja), która nie używa przepływu kodu autoryzacji z PKCE	Tokeny dostępu i tokeny identyfikatorów
Aplikacja internetowa lub SPA, która wywołuje internetowy interfejs API za pośrednictwem języka JavaScript przy użyciu przepływu niejawnego	Tokeny dostępu i tokeny identyfikatorów
Aplikacja internetowa ASP.NET Core i inne aplikacje internetowe korzystające z uwierzytelniania hybrydowego	Tokeny identyfikatorów

Wysyłanie żądania logowania

Aby początkowo zalogować użytkownika do aplikacji, możesz wysłać żądanie uwierzytelniania OpenID Connect i pobrać go id_token z Platforma tożsamości Microsoft.

Ważne

Aby pomyślnie zażądać tokenu identyfikatora i/lub tokenu dostępu, rejestracja aplikacji w centrum administracyjnym firmy Microsoft Entra — Rejestracje aplikacji musi mieć włączony odpowiedni niejawny przepływ udzielania, wybierając tokeny identyfikatorów i tokeny dostępu w sekcji Niejawne udzielanie i przepływy hybrydowe. Jeśli nie jest włączona, unsupported_response zostanie zwrócony błąd:

The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910

Parametr	Type	Opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Dozwolone wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje dotyczące protokołu. W przypadku scenariuszy gościa, w których logujesz użytkownika z jednej dzierżawy do innej dzierżawy, musisz podać identyfikator dzierżawy, aby poprawnie zalogować się do dzierżawy zasobów.
client_id	wymagane	Identyfikator aplikacji (klienta), który jest przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
response_type	wymagane	Musi zawierać id_token logowanie openID Connect. Może również zawierać element response_type, token. Użycie token tutaj umożliwi aplikacji natychmiastowe odbieranie tokenu dostępu z autoryzowanego punktu końcowego bez konieczności przesyłania drugiego żądania do autoryzowanego punktu końcowego. Jeśli używasz token response_type, parametr musi zawierać zakres wskazujący, scope dla którego zasobu ma zostać wystawiony token (na przykład user.read w programie Microsoft Graph). Może również zawierać code element zamiasttoken, aby podać kod autoryzacji do użycia w przepływie kodu autoryzacji. Ta id_token+code odpowiedź jest czasami nazywana przepływem hybrydowym.
redirect_uri	zalecane	Identyfikator URI przekierowania aplikacji, w którym można wysyłać i odbierać odpowiedzi uwierzytelniania przez aplikację. Musi być dokładnie zgodny z jednym z identyfikatorów URI przekierowania zarejestrowanych w portalu, z wyjątkiem tego, że musi być zakodowany pod adresem URL.
scope	wymagane	Rozdzielona spacjami lista zakresów. W przypadku programu OpenID Connect (id_tokens) musi zawierać zakres openid, który przekłada się na uprawnienie "Zaloguj się" w interfejsie użytkownika zgody. Opcjonalnie możesz również uwzględnić email zakresy i profile w celu uzyskania dostępu do dodatkowych danych użytkownika. Możesz również uwzględnić inne zakresy w tym żądaniu żądania zgody na różne zasoby, jeśli zażądano tokenu dostępu.
response_mode	optional	Określa metodę, która powinna służyć do wysyłania wynikowego tokenu z powrotem do aplikacji. Domyślnie zapytanie dotyczy tylko tokenu dostępu, ale fragment, jeśli żądanie zawiera id_token.
state	zalecane	Wartość uwzględniona w żądaniu, która zostanie również zwrócona w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerzowanym żądań między witrynami. Stan jest również 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.
nonce	wymagane	Wartość uwzględniona w żądaniu wygenerowana przez aplikację, która zostanie uwzględniona w wynikowym tokenie identyfikatora jako oświadczenie. Następnie aplikacja może zweryfikować tę wartość, aby wyeliminować ataki ponownego odtwarzania tokenu. Wartość jest zazwyczaj losowym, unikatowym ciągiem, który może służyć do identyfikowania źródła żądania. Wymagane tylko wtedy, gdy zażądano id_token.
prompt	optional	Wskazuje wymagany typ interakcji użytkownika. Jedynymi prawidłowymi wartościami w tej chwili są login, none, select_accounti consent. prompt=login wymusi na tym żądaniu wprowadzenie poświadczeń przez użytkownika, co spowoduje negowanie logowania jednokrotnego. prompt=none jest przeciwieństwem — zapewni to, że użytkownik nie będzie w ogóle wyświetlał żadnych interakcyjnych monitów. Jeśli nie można ukończyć żądania w trybie dyskretnym za pośrednictwem logowania jednokrotnego, Platforma tożsamości Microsoft zwróci błąd. prompt=select_account Wysyła użytkownika do selektora konta, w którym będą wyświetlane wszystkie konta zapamiętane w sesji. prompt=consent Spowoduje to wyzwolenie okna dialogowego zgody OAuth po zalogowaniu się użytkownika z prośbą o udzielenie uprawnień aplikacji.
login_hint	optional	Tego parametru można użyć do wstępnego wypełnienia pola nazwy użytkownika i adresu e-mail strony logowania użytkownika, jeśli znasz nazwę użytkownika z wyprzedzeniem. Często aplikacje używają tego parametru podczas ponownego uwierzytelniania po wyodrębnieniu opcjonalnego login_hint oświadczenia z wcześniejszego logowania.
domain_hint	optional	Jeśli zostanie to uwzględnione, spowoduje to pominięcie procesu odnajdywania opartego na wiadomości e-mail, który użytkownik przechodzi na stronie logowania, co prowadzi do nieco bardziej usprawnionego środowiska użytkownika. Ten parametr jest często używany w przypadku aplikacji biznesowych działających w jednej dzierżawie, gdzie podają nazwę domeny w danej dzierżawie, przekazując użytkownika do dostawcy federacyjnego dla tej dzierżawy. Ta wskazówka uniemożliwia gościom logowanie się do tej aplikacji i ogranicza użycie poświadczeń w chmurze, takich jak FIDO.

W tym momencie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Platforma tożsamości Microsoft zapewni również, że użytkownik wyraził zgodę na uprawnienia wskazane w parametrze scope zapytania. Jeśli użytkownik nie wyraził zgody na żadne z tych uprawnień, poprosi użytkownika o wyrażenie zgody na wymagane uprawnienia. Aby uzyskać więcej informacji, zobacz uprawnienia, zgoda i aplikacje wielodostępne.

Gdy użytkownik uwierzytelni i udzieli zgody, Platforma tożsamości Microsoft zwróci odpowiedź do aplikacji pod wskazanym redirect_uriadresem , używając metody określonej w parametrze response_mode .

Odpowiedź pomyślna

Pomyślna odpowiedź przy użyciu metody response_mode=fragment i response_type=id_token+code wygląda następująco (z podziałami wierszy na czytelność):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345

Parametr	Opis
code	Uwzględnione, jeśli response_type zawiera codeelement . Jest to kod autoryzacji odpowiedni do użycia w przepływie kodu autoryzacji.
access_token	Uwzględnione, jeśli response_type zawiera tokenelement . Token dostępu, którego zażądała aplikacja. Token dostępu nie powinien być zdekodowany ani w inny sposób sprawdzany, powinien być traktowany jako nieprzezroczystym ciągiem.
token_type	Uwzględnione, jeśli response_type zawiera tokenelement . Zawsze będzie Bearerto .
expires_in	Uwzględnione, jeśli response_type zawiera tokenelement . Wskazuje liczbę sekund, przez które token jest prawidłowy dla celów buforowania.
scope	Uwzględnione, jeśli response_type zawiera tokenelement . Wskazuje zakresy, dla których access_token będą prawidłowe. Może nie zawierać wszystkich żądanych zakresów, jeśli nie mają zastosowania do użytkownika. Na przykład zakresy tylko firmy Microsoft żądane podczas logowania przy użyciu konta osobistego.
id_token	Podpisany token internetowy JSON (JWT). Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. Aby uzyskać więcej informacji na temat tokenów identyfikatorów, zobacz id_token reference. Uwaga: podano tylko wtedy, gdy openid zakres został żądany i response_type uwzględniony id_tokens.
state	Jeśli parametr stanu jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne.

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

Odpowiedzi na błędy mogą być również wysyłane do redirect_uri aplikacji, aby mogła je odpowiednio obsłużyć:

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication

Parametr	Opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów występujących błędów i może służyć do reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc deweloperowi zidentyfikować główną przyczynę błędu uwierzytelniania.

Uzyskiwanie tokenów dostępu w trybie dyskretnym

Po zalogowaniu użytkownika do aplikacji jednostronicowej możesz dyskretnie uzyskać tokeny dostępu do wywoływania internetowych interfejsów API zabezpieczonych przez Platforma tożsamości Microsoft, takich jak program Microsoft Graph. Nawet jeśli token został już otrzymany przy użyciu token response_type, możesz użyć tej metody, aby uzyskać tokeny do dodatkowych zasobów bez przekierowywania użytkownika do ponownego logowania.

Ważne

Ta część niejawnego przepływu jest mało prawdopodobne, aby działała w przypadku aplikacji, ponieważ jest używana w różnych przeglądarkach z powodu domyślnego usunięcia plików cookie innych firm. Mimo że nadal działa to w przeglądarkach opartych na chromium, które nie znajdują się w programie Incognito, deweloperzy powinni ponownie rozważyć użycie tej części przepływu. W przeglądarkach, które nie obsługują plików cookie innych firm, zostanie wyświetlony błąd wskazujący, że żaden użytkownik nie jest zalogowany, ponieważ pliki cookie sesji strony logowania zostały usunięte przez przeglądarkę.

W normalnym przepływie OpenID Connect/OAuth należy to zrobić, wysyłając żądanie do punktu końcowego Platforma tożsamości Microsoft/token. Możesz wysłać żądanie w ukrytym elempcie iframe, aby uzyskać nowe tokeny dla innych internetowych interfejsów API:

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com

Aby uzyskać szczegółowe informacje na temat parametrów zapytania w adresie URL, zobacz wysyłanie żądania logowania.

Napiwek

Spróbuj skopiować i wkleić poniższe żądanie do karty przeglądarki! (Nie zapomnij zastąpić login_hint wartości poprawną wartością dla użytkownika)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}

Należy pamiętać, że będzie to działać nawet w przeglądarkach bez obsługi plików cookie innych firm, ponieważ wprowadzasz to bezpośrednio na pasku przeglądarki, w przeciwieństwie do otwierania go w ramce iframe.

Dzięki parametrowi to żądanie zakończy się powodzeniem prompt=none lub niepowodzeniem natychmiast i powróci do aplikacji. Odpowiedź zostanie wysłana do aplikacji pod wskazanym redirect_uriadresem , przy użyciu metody określonej w parametrze response_mode .

Odpowiedź pomyślna

Pomyślna odpowiedź przy użyciu metody response_mode=fragment wygląda następująco:

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read

Parametr	Opis
access_token	Uwzględnione, jeśli response_type zawiera tokenelement . Token dostępu, którego zażądała aplikacja, w tym przypadku dla programu Microsoft Graph. Token dostępu nie powinien być zdekodowany ani w inny sposób sprawdzany, powinien być traktowany jako nieprzezroczystym ciągiem.
token_type	Zawsze będzie Bearerto .
expires_in	Wskazuje liczbę sekund, przez które token jest prawidłowy dla celów buforowania.
scope	Wskazuje zakresy, dla których token dostępu będzie prawidłowy. Może nie zawierać wszystkich żądanych zakresów, jeśli nie mają one zastosowania do użytkownika (w przypadku żądań tylko firmy Microsoft w przypadku żądań dotyczących zakresów tylko w przypadku, gdy konto osobiste jest używane do logowania).
id_token	Podpisany token internetowy JSON (JWT). Uwzględnione, jeśli response_type zawiera id_tokenelement . Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. Aby uzyskać więcej informacji na temat id_tokens, zobacz dokumentacjęid_token. Uwaga: podano tylko wtedy, gdy openid zażądano zakresu.
state	Jeśli parametr stanu jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne.

Odpowiedź błędna

Odpowiedzi na błędy mogą być również wysyłane do redirect_uri aplikacji, aby mogła je odpowiednio obsłużyć. W przypadku programu prompt=noneoczekiwany błąd będzie:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently

Parametr	Opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów występujących błędów i może służyć do reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc deweloperowi zidentyfikować główną przyczynę błędu uwierzytelniania.

Jeśli ten błąd zostanie wyświetlony w żądaniu elementu iframe, użytkownik musi zalogować się interaktywnie, aby pobrać nowy token. Możesz wybrać obsługę tego przypadku w dowolny sposób dla aplikacji.

Odświeżanie tokenów

Niejawne przyznanie nie zapewnia tokenów odświeżania. Zarówno tokeny identyfikatorów, jak i tokeny dostępu wygasają po krótkim czasie, więc aplikacja musi być przygotowana do okresowego odświeżania tych tokenów. Aby odświeżyć dowolny typ tokenu, możesz wykonać to samo ukryte żądanie elementu iframe z góry przy użyciu parametru prompt=none w celu kontrolowania zachowania platformy tożsamości. Jeśli chcesz otrzymać nowy token identyfikatora, upewnij się, że używasz id_token parametru response_type scope=openidi , a także parametru nonce .

W przeglądarkach, które nie obsługują plików cookie innych firm, spowoduje to błąd wskazujący, że żaden użytkownik nie jest zalogowany.

Wysyłanie żądania wylogowania

Program OpenID Connect end_session_endpoint umożliwia aplikacji wysyłanie żądania do Platforma tożsamości Microsoft na zakończenie sesji użytkownika i czyszczenie plików cookie ustawionych przez Platforma tożsamości Microsoft. Aby w pełni wylogować użytkownika z aplikacji internetowej, aplikacja powinna zakończyć własną sesję z użytkownikiem (zwykle przez wyczyszczenie pamięci podręcznej tokenu lub usunięcie plików cookie), a następnie przekierowanie przeglądarki do:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/

Parametr	Type	Opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Dozwolone wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje dotyczące protokołu.
post_logout_redirect_uri	zalecane	Adres URL, do którego użytkownik powinien zostać zwrócony po zakończeniu wylogowywania. Ta wartość musi być zgodna z jednym z identyfikatorów URI przekierowania zarejestrowanych dla aplikacji. Jeśli nie zostanie uwzględniony, użytkownik zostanie wyświetlony ogólny komunikat przez Platforma tożsamości Microsoft.

Zobacz też

• Przejdź do przykładów biblioteki MSAL JS, aby rozpocząć kodowanie.
• Przejrzyj przepływ kodu autoryzacji jako nowszą, lepszą alternatywę dla niejawnego przyznania.