OpenID Connect w Platforma tożsamości Microsoft

OpenID Connect (OIDC) rozszerza protokół autoryzacji OAuth 2.0 do użycia jako inny protokół uwierzytelniania. Za pomocą funkcji OIDC można włączyć logowanie jednokrotne między aplikacjami z obsługą protokołu OAuth przy użyciu tokenu zabezpieczającego nazywanego tokenem identyfikatora.

Pełna specyfikacja OIDC jest dostępna na stronie internetowej OpenID Foundation pod adresem Specyfikacji OpenID Connect Core 1.0.

Przepływ protokołu: logowanie

Na poniższym diagramie przedstawiono podstawowy przepływ logowania openID Connect. Kroki opisane w przepływie zostały szczegółowo opisane w kolejnych sekcjach artykułu.

Włączanie tokenów identyfikatorów

Token identyfikatora wprowadzony przez program OpenID Connect jest wystawiany przez serwer autoryzacji, Platforma tożsamości Microsoft, gdy aplikacja kliencka żąda jednego podczas uwierzytelniania użytkownika. Token identyfikatora umożliwia aplikacji klienckiej zweryfikowanie tożsamości użytkownika i uzyskanie innych informacji (oświadczeń) o nich.

Tokeny identyfikatorów nie są domyślnie wystawiane dla aplikacji zarejestrowanej w Platforma tożsamości Microsoft. Tokeny identyfikatorów dla aplikacji są włączone przy użyciu jednej z następujących metod:

1. Zaloguj się do centrum administracyjnego usługi Microsoft Entra.
2. Przejdź do sekcji Identity>Applications> Rejestracje aplikacji>< your application Authentication (Uwierzytelnianie aplikacji).>>
3. W obszarze Konfiguracje platformy wybierz pozycję Dodaj platformę.
4. W otwartym okienku wybierz odpowiednią platformę dla aplikacji. Na przykład wybierz pozycję Sieć Web dla aplikacji internetowej.
5. W obszarze Identyfikatory URI przekierowania dodaj identyfikator URI przekierowania aplikacji. Na przykład https://localhost:8080/.
6. W obszarze Niejawne udzielanie i przepływy hybrydowe zaznacz pole wyboru Tokeny identyfikatorów (używane dla przepływów niejawnych i hybrydowych).

Lub:

1. Wybierz pozycję Identity>Applications> Rejestracje aplikacji>< your application Manifest( Manifest aplikacji).>>
2. Ustaw oauth2AllowIdTokenImplicitFlow wartość na true w manifeście aplikacji rejestracji aplikacji.

Jeśli tokeny identyfikatorów nie są włączone dla aplikacji, a jeden jest żądany, Platforma tożsamości Microsoft zwraca błąd podobny do następującegounsupported_response:

Podana wartość parametru wejściowego "response_type" nie jest dozwolona dla tego klienta. Oczekiwana wartość to "code".

Żądanie tokenu identyfikatora przez określenie elementu response_type id_token zostało wyjaśnione w sekcji Wyślij żądanie logowania w dalszej części artykułu.

Pobieranie dokumentu konfiguracji OpenID

Dostawcy openID, tacy jak Platforma tożsamości Microsoft, udostępniają dokument konfiguracji dostawcy OpenID w publicznie dostępnym punkcie końcowym zawierającym punkty końcowe OIDC dostawcy, obsługiwane oświadczenia i inne metadane. Aplikacje klienckie mogą używać metadanych do odnajdywania adresów URL używanych do uwierzytelniania i publicznych kluczy podpisywania usługi uwierzytelniania.

Biblioteki uwierzytelniania są najczęstszymi użytkownikami dokumentu konfiguracji OpenID, którego używają do odnajdywania adresów URL uwierzytelniania, publicznych kluczy podpisywania dostawcy i innych metadanych usługi. Jeśli biblioteka uwierzytelniania jest używana w aplikacji, prawdopodobnie nie będzie konieczne przekazywanie żądań kodu do i odpowiedzi z punktu końcowego dokumentu konfiguracji OpenID.

Znajdowanie identyfikatora URI dokumentu konfiguracji OpenID aplikacji

Każda rejestracja aplikacji w identyfikatorze Entra firmy Microsoft jest udostępniany publicznie dostępny punkt końcowy obsługujący dokument konfiguracji OpenID. Aby określić identyfikator URI punktu końcowego dokumentu konfiguracji dla aplikacji, dołącz dobrze znaną ścieżkę konfiguracji OpenID do adresu URL urzędu rejestracji aplikacji.

• Dobrze znana ścieżka dokumentu konfiguracji: /.well-known/openid-configuration
• Adres URL urzędu: https://login.microsoftonline.com/{tenant}/v2.0

Wartość zmiennej {tenant} zależy od odbiorców logowania aplikacji, jak pokazano w poniższej tabeli. Adres URL urzędu różni się również w zależności od wystąpienia chmury.

Wartość	Opis
common	Użytkownicy z osobistym kontem Microsoft i kontem służbowym z identyfikatora Microsoft Entra ID mogą logować się do aplikacji.
organizations	Tylko użytkownicy z kontami służbowymi z identyfikatora Microsoft Entra ID mogą logować się do aplikacji.
consumers	Tylko użytkownicy z osobistym kontem Microsoft mogą logować się do aplikacji.
Directory (tenant) ID lub contoso.onmicrosoft.com	Tylko użytkownicy z określonej dzierżawy firmy Microsoft Entra (członkowie katalogu z kontem służbowym lub gośćmi katalogu z osobistym kontem Microsoft) mogą logować się do aplikacji. Wartość może być nazwą domeny dzierżawy Microsoft Entra lub identyfikatorem dzierżawy w formacie GUID.

Napiwek

Należy pamiętać, że w przypadku korzystania z common urzędu lub consumers dla osobistych kont Microsoft aplikacja zasobów zużywających zasoby musi być skonfigurowana do obsługi takiego typu kont zgodnie z znakiemInAudience.

Aby znaleźć dokument konfiguracji OIDC w centrum administracyjnym firmy Microsoft Entra, zaloguj się do centrum administracyjnego firmy Microsoft Entra, a następnie:

1. Przejdź do sekcji Identity>Applications> Rejestracje aplikacji>< Our application Endpoints (Punkty końcowe aplikacji).>>
2. Znajdź identyfikator URI w dokumencie metadanych OpenID Connect.

Przykładowe żądanie

Następujące żądanie pobiera metadane konfiguracji OpenID z common punktu końcowego dokumentu konfiguracji OpenID urzędu w chmurze publicznej platformy Azure:

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Napiwek

Wypróbuj! Aby wyświetlić dokument konfiguracji OpenID dla urzędu aplikacji common , przejdź do https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration.

Przykładowa odpowiedź

Metadane konfiguracji są zwracane w formacie JSON, jak pokazano w poniższym przykładzie (obcięte dla zwięzłości). Metadane zwrócone w odpowiedzi JSON zostały szczegółowo opisane w specyfikacji odnajdywania OpenID Connect 1.0.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Wysyłanie żądania logowania

Aby uwierzytelnić użytkownika i zażądać tokenu identyfikatora do użycia w aplikacji, przekierowuj agenta użytkownika do punktu końcowego /authorize Platforma tożsamości Microsoft. Żądanie jest podobne do pierwszego etapu przepływu kodu autoryzacji OAuth 2.0, ale z następującymi różnicami:

• Uwzględnij openid zakres w parametrze scope .
• Określ id_token w parametrze response_type .
• Uwzględnij nonce parametr .

Przykładowe żądanie logowania (podziały wierszy uwzględnione tylko w celu zapewnienia czytelności):

GET 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
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

Parametr	Warunek	opis
tenant	Wymagania	Możesz użyć {tenant} wartości w ścieżce żądania, aby kontrolować, kto może zalogować się do aplikacji. Dozwolone wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawy 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	Wymagania	Identyfikator aplikacji (klienta) przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
response_type	Wymagania	Musi zawierać id_token logowanie openID Connect.
redirect_uri	Zalecane	Identyfikator URI przekierowania aplikacji, w którym można wysyłać i odbierać odpowiedzi uwierzytelniania przez aplikację. Musi dokładnie odpowiadać jednemu z identyfikatorów URI przekierowania zarejestrowanych w portalu, z tą różnicą, że musi być zakodowana pod adresem URL. Jeśli nie istnieje, punkt końcowy wybiera jeden zarejestrowany redirect_uri losowo, aby wysłać użytkownika z powrotem do.
scope	Wymagania	Rozdzielona spacjami lista zakresów. W przypadku programu OpenID Connect musi zawierać zakres openid, który przekłada się na uprawnienie Zaloguj się w interfejsie użytkownika zgody. Możesz również uwzględnić inne zakresy w tym żądaniu żądania zgody.
nonce	Wymagania	Wartość wygenerowana i wysłana przez aplikację w żądaniu tokenu identyfikatora. Ta sama nonce wartość jest uwzględniana w tokenie identyfikatora zwróconym do aplikacji przez Platforma tożsamości Microsoft. Aby zapobiec atakom powtarzania tokenu, aplikacja powinna sprawdzić, czy nonce wartość w tokenie identyfikatora jest tą samą wartością, która została wysłana podczas żądania tokenu. Wartość jest zazwyczaj unikatowym, losowym ciągiem.
response_mode	Zalecane	Określa metodę, która powinna służyć do wysyłania wynikowego kodu autoryzacji z powrotem do aplikacji. Możliwe wartości to form_post i fragment. W przypadku aplikacji internetowych zalecamy użycie polecenia response_mode=form_post, aby zapewnić najbezpieczniejszy transfer tokenów do aplikacji.
state	Zalecane	Wartość uwzględniona w żądaniu, który jest również zwracany 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, takie jak strona lub wyświetlanie, na których znajdował się użytkownik.
prompt	Opcjonalnie	Wskazuje wymagany typ interakcji użytkownika. Jedynymi prawidłowymi wartościami w tej chwili są login, none, consenti select_account. Oświadczenie prompt=login wymusza, aby użytkownik wprowadzał swoje poświadczenia na tym żądaniu, co neguje logowanie jednokrotne. Parametr prompt=none jest odwrotny i powinien być sparowany z elementem , login_hint aby wskazać, który użytkownik musi być zalogowany. Te parametry zapewniają, że użytkownik w ogóle nie wyświetla żadnego interakcyjnego monitu. Jeśli nie można ukończyć żądania w trybie dyskretnym za pomocą logowania jednokrotnego, Platforma tożsamości Microsoft zwróci błąd. Przyczyny obejmują brak zalogowanego użytkownika, sugerowany użytkownik nie jest zalogowany lub wielu użytkowników jest zalogowanych, ale nie podano żadnej wskazówki. Oświadczenie prompt=consent wyzwala okno dialogowe zgody OAuth po zalogowaniu się użytkownika. W oknie dialogowym zostanie wyświetlony monit o przyznanie użytkownikowi uprawnień do aplikacji. select_account Na koniec pokazuje użytkownikowi selektor konta, negując wylogowanie jednokrotne, ale zezwalając użytkownikowi na wybranie konta, za pomocą którego zamierza się zalogować, bez konieczności wprowadzania poświadczeń. Nie można użyć funkcji login_hint i select_account.
login_hint	Opcjonalnie	Za pomocą tego parametru można wstępnie wypełnić pole 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	Opcjonalnie	Obszar użytkownika w katalogu federacyjnym. Spowoduje to pominięcie procesu odnajdywania opartego na wiadomościach e-mail, który użytkownik przechodzi na stronie logowania w celu uzyskania nieco bardziej usprawnionego środowiska użytkownika. W przypadku dzierżaw, które są federacyjne za pośrednictwem katalogu lokalnego, takiego jak usługi AD FS, często powoduje to bezproblemowe logowanie z powodu istniejącej sesji logowania.

Na tym etapie użytkownik jest monitowany o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Platforma tożsamości Microsoft sprawdza, czy użytkownik wyraził zgodę na uprawnienia wskazane w parametrze scope zapytania. Jeśli użytkownik nie wyraził zgody na jakiekolwiek z tych uprawnień, Platforma tożsamości Microsoft monituje użytkownika o zgodę na wymagane uprawnienia. Możesz dowiedzieć się więcej na temat uprawnień, zgody i wielodostępnych aplikacji.

Po uwierzytelnieniu i udzielaniu zgody użytkownik Platforma tożsamości Microsoft zwraca odpowiedź do aplikacji przy użyciu wskazanego identyfikatora URI przekierowania przy użyciu metody określonej w parametrze response_mode .

Odpowiedź pomyślna

Pomyślna odpowiedź w przypadku użycia response_mode=form_post jest podobna do następującej:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Parametr	Opis
id_token	Token identyfikatora, którego zażądała aplikacja. Możesz użyć parametru id_token , aby zweryfikować tożsamość użytkownika i rozpocząć sesję z użytkownikiem. Aby uzyskać więcej informacji na temat tokenów identyfikatorów i ich zawartości, zobacz dokumentację tokenu identyfikatora.
state	state Jeśli parametr 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 identyfikatora URI przekierowania, aby aplikacja mogła je obsłużyć, na przykład:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

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 zidentyfikować główną przyczynę błędu uwierzytelniania.

Kody błędów dla błędów punktu końcowego autoryzacji

W poniższej tabeli opisano kody błędów, które można zwrócić w parametrze error odpowiedzi o błędzie:

Kod błędu	opis	Akcja klienta
invalid_request	Błąd protokołu, taki jak brak wymaganego parametru.	Napraw i prześlij ponownie żądanie. Ten błąd programowania powinien zostać przechwycony podczas testowania aplikacji.
unauthorized_client	Aplikacja kliencka nie może zażądać kodu autoryzacji.	Ten błąd może wystąpić, gdy aplikacja kliencka nie jest zarejestrowana w identyfikatorze Entra firmy Microsoft lub nie jest dodawana do dzierżawy firmy Microsoft Entra użytkownika. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.
access_denied	Właściciel zasobu odmówił zgody.	Aplikacja kliencka może powiadomić użytkownika o tym, że nie może kontynuować, chyba że użytkownik wyrazi zgodę.
unsupported_response_type	Serwer autoryzacji nie obsługuje typu odpowiedzi w żądaniu.	Napraw i prześlij ponownie żądanie. Ten błąd programowania powinien zostać przechwycony podczas testowania aplikacji.
server_error	Serwer napotkał nieoczekiwany błąd.	Ponów próbę żądania. Te błędy mogą wynikać z warunków tymczasowych. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona z powodu tymczasowego błędu.
temporarily_unavailable	Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie.	Ponów próbę żądania. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona z powodu stanu tymczasowego.
invalid_resource	Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, identyfikator Entra firmy Microsoft nie może go znaleźć lub został nieprawidłowo skonfigurowany.	Ten błąd wskazuje, że zasób, jeśli istnieje, nie został skonfigurowany w dzierżawie. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.

Weryfikowanie tokenu identyfikatora

Odbieranie tokenu identyfikatora w aplikacji może nie zawsze być wystarczające, aby w pełni uwierzytelnić użytkownika. Może być również konieczne zweryfikowanie podpisu tokenu identyfikatora i zweryfikowanie jego oświadczeń zgodnie z wymaganiami aplikacji. Podobnie jak wszyscy dostawcy OpenID, tokeny identyfikatorów Platforma tożsamości Microsoft są tokenami JSON Web Tokens (JWTs) podpisanymi przy użyciu kryptografii klucza publicznego.

Aplikacje internetowe i internetowe interfejsy API, które używają tokenów identyfikatorów do autoryzacji, muszą je zweryfikować, ponieważ takie aplikacje uzyskują dostęp do danych. Inne typy aplikacji mogą jednak nie korzystać z weryfikacji tokenu identyfikatora. Natywne i jednostronicowe aplikacje (SPA), na przykład rzadko korzystają z weryfikacji tokenu identyfikatora, ponieważ każda jednostka z fizycznym dostępem do urządzenia lub przeglądarki może potencjalnie pominąć walidację.

Dwa przykłady obejścia weryfikacji tokenu to:

• Dostarczanie fałszywych tokenów lub kluczy przez zmodyfikowanie ruchu sieciowego do urządzenia
• Debugowanie aplikacji i przechodzenie przez logikę walidacji podczas wykonywania programu.

Jeśli zweryfikujesz tokeny identyfikatorów w aplikacji, zalecamy , aby nie robić tego ręcznie. Zamiast tego użyj biblioteki weryfikacji tokenów, aby przeanalizować i zweryfikować tokeny. Biblioteki weryfikacji tokenów są dostępne dla większości języków programowania, struktur i platform.

Co należy zweryfikować w tokenie identyfikatora

Oprócz sprawdzania poprawności podpisu tokenu identyfikatora należy zweryfikować kilka jego oświadczeń zgodnie z opisem w artykule Weryfikowanie tokenu identyfikatora. Zobacz również Ważne informacje na temat podpisywania przerzucania klucza.

Kilka innych weryfikacji jest typowych i różnią się w zależności od scenariusza aplikacji, w tym:

• Upewnienie się, że użytkownik/organizacja zarejestrował się w aplikacji.
• Upewnienie się, że użytkownik ma odpowiednią autoryzację/uprawnienia
• Upewnienie się, że wystąpiła pewna siła uwierzytelniania, na przykład uwierzytelnianie wieloskładnikowe.

Po zweryfikowaniu tokenu identyfikatora możesz rozpocząć sesję z użytkownikiem i użyć informacji w oświadczeniach tokenu dotyczących personalizacji, wyświetlania lub przechowywania ich danych.

Diagram protokołu: uzyskiwanie tokenu dostępu

Wiele aplikacji musi nie tylko zalogować się do użytkownika, ale także uzyskać dostęp do chronionego zasobu, takiego jak internetowy interfejs API w imieniu użytkownika. Ten scenariusz łączy program OpenID Connect, aby uzyskać token identyfikatora na potrzeby uwierzytelniania użytkownika i protokołu OAuth 2.0 w celu uzyskania tokenu dostępu dla chronionego zasobu.

Pełny przepływ logowania i pozyskiwania tokenów openID Connect wygląda podobnie do tego diagramu:

Uzyskiwanie tokenu dostępu dla punktu końcowego UserInfo

Oprócz tokenu identyfikatora informacje uwierzytelnionego użytkownika są również udostępniane w punkcie końcowym OIDC UserInfo.

Aby uzyskać token dostępu dla punktu końcowego OIDC UserInfo, zmodyfikuj żądanie logowania zgodnie z opisem tutaj:

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Możesz użyć przepływu kodu autoryzacji, przepływu kodu urządzenia lub tokenu odświeżania zamiast response_type=token , aby uzyskać token dostępu dla aplikacji.

Pomyślna odpowiedź tokenu

Pomyślna odpowiedź z użycia polecenia response_mode=form_post:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Parametry odpowiedzi oznaczają to samo, niezależnie od przepływu użytego do ich uzyskania.

Parametr	Opis
access_token	Token używany do wywoływania punktu końcowego UserInfo.
token_type	Zawsze "Bearer"
expires_in	Czas wygaśnięcia tokenu dostępu w sekundach.
scope	Uprawnienia przyznane na tokenie dostępu. Ponieważ punkt końcowy UserInfo jest hostowany w programie Microsoft Graph, możliwe scope jest, aby zawierał inne osoby wcześniej przyznane aplikacji (na przykład User.Read).
id_token	Token identyfikatora, którego zażądała aplikacja. Możesz użyć tokenu identyfikatora, aby zweryfikować tożsamość użytkownika i rozpocząć sesję z użytkownikiem. Więcej szczegółów na temat tokenów identyfikatorów i ich zawartości znajdziesz w dokumentacji tokenu identyfikatora.
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 identyfikatora URI przekierowania, aby aplikacja mogła je odpowiednio obsłużyć:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

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 zidentyfikować główną przyczynę błędu uwierzytelniania.

Opis możliwych kodów błędów i zalecanych odpowiedzi klientów można znaleźć w temacie Kody błędów błędów dotyczących błędów punktu końcowego autoryzacji.

Jeśli masz kod autoryzacji i token identyfikatora, możesz zalogować użytkownika i uzyskać tokeny dostępu w ich imieniu. Aby zalogować użytkownika, należy zweryfikować token identyfikatora zgodnie z opisem w tokenach weryfikacji. Aby uzyskać tokeny dostępu, wykonaj kroki opisane w dokumentacji przepływu kodu OAuth.

Wywoływanie punktu końcowego UserInfo

Zapoznaj się z dokumentacją UserInfo, aby dowiedzieć się, jak wywołać punkt końcowy UserInfo za pomocą tego tokenu.

Wysyłanie żądania wylogowania

Aby wylogować użytkownika, wykonaj obie następujące operacje:

1. Przekieruj agenta użytkownika użytkownika do identyfikatora URI wylogowania Platforma tożsamości Microsoft.
2. Wyczyść pliki cookie aplikacji lub zakończ sesję użytkownika w aplikacji.

Jeśli nie możesz wykonać jednej z tych operacji, użytkownik może pozostać uwierzytelniony i nie zostanie wyświetlony monit o zalogowanie się przy następnym użyciu aplikacji.

Przekieruj agenta użytkownika do obiektu end_session_endpoint , jak pokazano w dokumencie konfiguracji OpenID Connect. Obiekt end_session_endpoint obsługuje żądania HTTP GET i POST.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Parametr	Warunek	opis
post_logout_redirect_uri	Zalecane	Adres URL, do którego użytkownik jest przekierowywany po pomyślnym wylogowaniu. Jeśli parametr nie jest uwzględniony, użytkownik jest wyświetlany ogólny komunikat wygenerowany przez Platforma tożsamości Microsoft. Ten adres URL musi być zgodny z jednym z identyfikatorów URI przekierowania zarejestrowanych dla aplikacji w portalu rejestracji aplikacji.
logout_hint	Opcjonalnie	Umożliwia wylogowanie się bez monitowania użytkownika o wybranie konta. Aby użyć logout_hintpolecenia , włącz login_hint opcjonalne oświadczenie w aplikacji klienckiej i użyj wartości opcjonalnego login_hint oświadczenia jako parametru logout_hint . Nie używaj nazw UPN ani numerów telefonów jako wartości parametru logout_hint .

Uwaga

Po pomyślnym wylogowaniu aktywne sesje zostaną ustawione na nieaktywne. Jeśli istnieje prawidłowy podstawowy token odświeżania (PRT) dla wylogowanego użytkownika i zostanie wykonane nowe logowanie, wylogowanie jednokrotne zostanie przerwane, a użytkownik zobaczy monit z selektorem konta. Jeśli wybrana opcja to połączone konto, które odwołuje się do prT, logowanie będzie kontynuowane automatycznie bez konieczności wstawiania nowych poświadczeń.

Wylogowanie jednokrotne

Po przekierowaniu użytkownika do end_session_endpoint aplikacji Platforma tożsamości Microsoft kończy sesję użytkownika dla tej aplikacji. Jednak użytkownik może być nadal zalogowany do innych aplikacji, które używają tych samych kont Microsoft do uwierzytelniania.

Gdy użytkownik zalogował się do wielu aplikacji internetowych lub SPA zarejestrowanych w tym katalogu (znanym również jako dzierżawa) logowanie jednokrotne umożliwia temu użytkownikowi natychmiastowe wylogowanie się ze wszystkich aplikacji przez wylogowanie się w jednej z aplikacji.

Aby włączyć logowanie jednokrotne dla aplikacji Entra, należy użyć funkcji wylogowywanie kanału frontonu OpenID Connect. Ta funkcja umożliwia aplikacji powiadamianie innych aplikacji o wylogowaniu użytkownika. Gdy użytkownik wyloguje się z jednej aplikacji, Platforma tożsamości Microsoft wysyła żądanie HTTP GET do adresu URL wylogowywania kanału frontonu każdej aplikacji, do której użytkownik jest obecnie zalogowany.

Te aplikacje muszą odpowiedzieć na to żądanie, wykonując następujące dwie akcje, aby logowanie jednokrotne zakończyło się pomyślnie:

1. Wyczyść dowolną sesję, która identyfikuje użytkownika.
2. Aplikacje muszą odpowiadać na to żądanie przez wyczyszczenie każdej sesji, która identyfikuje użytkownika i zwraca 200 odpowiedź.

Co to jest adres URL wylogowywania kanału frontonu?

Adres URL wylogowywania kanału frontu to miejsce, w którym aplikacja internetowa lub SPA odbiera żądanie wylogowania z serwera uwierzytelniania Entra i wykonuje funkcję wylogowywania jednokrotnego. Każda aplikacja ma jeden adres URL wylogowywania kanału frontu.

Kiedy należy ustawić adres URL wylogowywania kanału frontu?

Jeśli użytkownik lub deweloper ustalił, że dla aplikacji jest wymagane wylogowanie jednokrotne, musisz ustawić adres URL wylogowywania kanału frontu na potrzeby rejestracji aplikacji tej aplikacji. Po ustawieniu adresu URL wylogowywania kanału frontu dla rejestracji aplikacji Platforma tożsamości Microsoft wysyła żądanie HTTP GET do adresu URL wylogowywania kanału frontonu tej aplikacji, gdy zalogowany użytkownik wylogował się z innej aplikacji.

Jak skonfigurować logowanie jednokrotne przy użyciu funkcji wylogowywanie kanału frontu

Aby użyć funkcji wylogowywanie kanału frontowego dla zestawu aplikacji, należy wykonać następujące dwa zadania:

• Ustaw adres URL wylogowywania kanału frontonu w centrum administracyjnym firmy Microsoft Entra dla wszystkich aplikacji, które powinny zostać wylogowane jednocześnie. Każda aplikacja zazwyczaj ma własny dedykowany adres URL wylogowywania kanału frontonu.
• Edytuj kod aplikacji, aby nasłuchiwać żądania HTTP GET wysyłanego przez Platforma tożsamości Microsoft do adresu URL wylogowywania kanału frontu i odpowiadać na to żądanie, usuwając wszystkie sesje identyfikujące użytkownika i zwracając odpowiedź 200.

Jak wybrać adres URL wylogowywania kanału frontu

Adres URL wylogowywania kanału frontu powinien być adresem URL, który może odbierać żądania HTTP GET i odpowiadać na nie i powinien mieć możliwość wyczyszczenia każdej sesji identyfikującej użytkownika. Przykłady adresu URL wylogowywania kanału frontu mogą być następujące:

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Następne kroki

• Zapoznaj się z dokumentacją punktu końcowego UserInfo.
• Wypełnij wartości oświadczeń w tokenie danymi z systemów lokalnych.
• Uwzględnij własne oświadczenia w tokenach.