Autoryzowanie dostępu do aplikacji internetowych przy użyciu warstwy OpenID Connect i usługi Azure Active Directory
Ostrzeżenie
Ta zawartość dotyczy starszego punktu końcowego Azure AD w wersji 1.0. Użyj Platforma tożsamości Microsoft dla nowych projektów.
OpenID Connect to prosta warstwa tożsamości oparta na protokole OAuth 2.0. Protokół OAuth 2.0 definiuje mechanizmy uzyskiwania i używania tokenów dostępu do chronionych zasobów, ale nie definiują standardowych metod dostarczania informacji o tożsamości. OpenID Connect implementuje uwierzytelnianie jako rozszerzenie procesu autoryzacji OAuth 2.0. Zawiera on informacje o użytkowniku końcowym w formie id_token , który weryfikuje tożsamość użytkownika i udostępnia podstawowe informacje o profilu użytkownika.
OpenID Connect jest naszym zaleceniem, jeśli tworzysz aplikację internetową hostowaną na serwerze i uzyskujesz dostęp za pośrednictwem przeglądarki.
Rejestrowanie aplikacji w dzierżawie usługi AD
Najpierw zarejestruj aplikację w dzierżawie usługi Azure Active Directory (Azure AD). Spowoduje to nadanie aplikacji identyfikatora oraz umożliwi jej otrzymywanie tokenów.
Zaloguj się w witrynie Azure Portal.
Wybierz dzierżawę Azure AD, wybierając konto w prawym górnym rogu strony, a następnie wybierając nawigację Przełącz katalog, a następnie wybierając odpowiednią dzierżawę.
- Pomiń ten krok, jeśli masz tylko jedną dzierżawę Azure AD w ramach konta lub jeśli wybrano już odpowiednią dzierżawę Azure AD.
W Azure Portal wyszukaj i wybierz pozycję Azure Active Directory.
W menu po lewej stronie usługi Azure Active Directory wybierz pozycję Rejestracje aplikacji, a następnie wybierz pozycję Nowa rejestracja.
Postępuj zgodnie z monitami i utwórz nową aplikację. Nie ma znaczenia, czy jest to aplikacja internetowa lub aplikacja publiczna (mobilna & klasyczna) na potrzeby tego samouczka, ale jeśli chcesz użyć konkretnych przykładów dla aplikacji internetowych lub publicznych aplikacji klienckich, zapoznaj się z naszymi przewodnikami Szybki start.
- Nazwa to nazwa aplikacji; opisuje aplikację innym użytkownikom.
- W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym i konta osobiste Microsoft.
- Podaj identyfikator URI przekierowania. W przypadku aplikacji internetowych jest to podstawowy adres URL aplikacji, pod którym użytkownicy mogą się logować. Na przykład
http://localhost:12345. W przypadku klienta publicznego (mobilnego & desktop) Azure AD używa go do zwracania odpowiedzi tokenu. Wprowadź wartość specyficzną dla swojej aplikacji. Na przykładhttp://MyFirstAADApp.
Po zakończeniu rejestracji Azure AD przypisze aplikacji unikatowy identyfikator klienta (identyfikator aplikacji). Ta wartość jest potrzebna w następnych sekcjach, więc skopiuj ją ze strony aplikacji.
Aby znaleźć aplikację w Azure Portal, wybierz pozycję Rejestracje aplikacji, a następnie wybierz pozycję Wyświetl wszystkie aplikacje.
Przepływ uwierzytelniania w przypadku protokołu OpenID Connect
Najbardziej podstawowy przepływ logowania zawiera następujące kroki — każdy z nich został szczegółowo opisany poniżej.
Dokument metadanych OpenID Connect
OpenID Connect opisuje dokument metadanych, który zawiera większość informacji wymaganych przez aplikację do logowania. Obejmuje to informacje, takie jak adresy URL do użycia i lokalizację publicznych kluczy podpisywania usługi. Dokument metadanych OpenID Connect można znaleźć pod adresem:
https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration
Metadane to prosty dokument JavaScript Object Notation (JSON). Przykład można znaleźć w poniższym fragmencie kodu. Zawartość fragmentu kodu jest w pełni opisana w specyfikacji OpenID Connect. Pamiętaj, że podanie identyfikatora dzierżawy zamiast common elementu {tenant} powyżej spowoduje zwrócenie identyfikatorów URI specyficznych dla dzierżawy w zwróconym obiekcie JSON.
{
"authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
"token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
"token_endpoint_auth_methods_supported":
[
"client_secret_post",
"private_key_jwt",
"client_secret_basic"
],
"jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
"userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
...
}
Jeśli aplikacja ma niestandardowe klucze podpisywania w wyniku używania funkcji mapowania oświadczeń , musisz dołączyć appid parametr zapytania zawierający identyfikator aplikacji, aby uzyskać jwks_uri informacje o kluczu podpisywania aplikacji. Na przykład: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e zawiera znak jwks_uri z .https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e
Wysyłanie żądania logowania
Gdy aplikacja internetowa musi uwierzytelniać użytkownika, musi kierować użytkownika do punktu końcowego /authorize . To żądanie jest podobne do pierwszego etapu przepływu kodu autoryzacji OAuth 2.0 z kilkoma ważnymi różnicami:
- Żądanie musi zawierać zakres
openidw parametrzescope. - Parametr
response_typemusi zawierać wartośćid_token. - Żądanie musi zawierać
nonceparametr .
W związku z tym przykładowe żądanie będzie wyglądać następująco:
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7
| Parametr | Typ | Opis |
|---|---|---|
| Dzierżawy | 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 identyfikatory dzierżawy, na przykład 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 lub contoso.onmicrosoft.comcommon dla tokenów niezależnych od dzierżawy |
| client_id | wymagane | Identyfikator aplikacji przypisany do aplikacji po zarejestrowaniu jej w Azure AD. Można to znaleźć w Azure Portal. Kliknij pozycję Azure Active Directory, kliknij pozycję Rejestracje aplikacji, wybierz aplikację i znajdź identyfikator aplikacji na stronie aplikacji. |
| response_type | wymagane | Musi zawierać id_token logowanie openID Connect. Może również obejmować inne response_types, takie jak code lub token. |
| scope | zalecane | Specyfikacja openID Connect wymaga zakresu openid, który przekłada się na uprawnienie "Zaloguj się" w interfejsie użytkownika zgody. Te i inne zakresy OIDC są ignorowane w punkcie końcowym w wersji 1.0, ale nadal jest najlepszym rozwiązaniem dla klientów zgodnych ze standardami. |
| nonce | wymagane | Wartość uwzględniona w żądaniu wygenerowana przez aplikację, która jest uwzględniona w wyniku id_token jako oświadczenie. Następnie aplikacja może zweryfikować tę wartość w celu ograniczenia ataków powtarzania tokenu. Wartość jest zazwyczaj losowym, unikatowym ciągiem lub identyfikatorem GUID, który może służyć do identyfikowania źródła żądania. |
| redirect_uri | zalecane | Redirect_uri aplikacji, w której można wysyłać i odbierać odpowiedzi uwierzytelniania przez aplikację. Musi dokładnie odpowiadać jednemu z redirect_uris, który został zarejestrowany w portalu, z wyjątkiem tego, że musi być zakodowany w adresie URL. Jeśli nie ma, agent użytkownika zostanie odesłany do jednego z identyfikatorów URI przekierowania zarejestrowanych dla aplikacji, losowo. Maksymalna długość to 255 bajtów |
| response_mode | optional | Określa metodę, która powinna służyć do wysyłania wynikowych authorization_code z powrotem do aplikacji. Obsługiwane wartości dotyczą form_postwpisu formularza HTTP i fragmentfragmentu adresu URL. W przypadku aplikacji internetowych zalecamy użycie metody response_mode=form_post w celu zapewnienia najbezpieczniejszego transferu tokenów do aplikacji. Wartością domyślną dla dowolnego przepływu, w tym id_token jest fragment. |
| stan | zalecane | Wartość uwzględniona w żądaniu zwróconym w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania fałszerzowaniu żą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ł. |
| Wierszu | optional | Wskazuje typ wymaganej interakcji użytkownika. Obecnie jedynymi prawidłowymi wartościami są "login", "none" i "consent". prompt=login wymusza, aby użytkownik wprowadzał swoje poświadczenia na tym żądaniu, negując logowanie jednokrotne. prompt=none jest odwrotnie - gwarantuje, że użytkownik nie jest w ogóle wyświetlany z żadnym interakcyjnym monitem. Jeśli nie można ukończyć żądania w trybie dyskretnym za pośrednictwem logowania jednokrotnego, punkt końcowy zwróci błąd. prompt=consent wyzwala okno dialogowe zgody OAuth po zalogowaniu się użytkownika z prośbą o udzielenie uprawnień do aplikacji. |
| login_hint | optional | Można użyć do wstępnego wypełnienia pola nazwa użytkownika/adres e-mail strony logowania użytkownika, jeśli znasz swoją nazwę użytkownika przed upływem czasu. Często aplikacje używają tego parametru podczas ponownego uwierzytelniania, po wyodrębnieniu nazwy użytkownika z poprzedniego preferred_username logowania przy użyciu oświadczenia. |
W tym momencie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania.
Przykładowa odpowiedź
Przykładowa odpowiedź wysłana do określonego redirect_uri w żądaniu logowania po uwierzytelnieniu użytkownika może wyglądać następująco:
POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345
| Parametr | Opis |
|---|---|
| id_token | Żądana id_token aplikacja. Możesz użyć polecenia id_token , aby zweryfikować tożsamość użytkownika i rozpocząć sesję z użytkownikiem. |
| stan | Wartość uwzględniona w żądaniu, które jest również zwracane w odpowiedzi tokenu. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerowania żądań między witrynami. Stan jest również używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelniania, na przykład strony lub widoku, na której znajdowały się. |
Odpowiedź na błąd
Odpowiedzi na błędy mogą być również wysyłane do redirect_uri aplikacji, aby mogła je odpowiednio obsłużyć:
POST / HTTP/1.1
Host: localhost:12345
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óry może służyć do klasyfikowania typów błędów, które występują 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. |
Kody błędów dla błędów punktu końcowego autoryzacji
W poniższej tabeli opisano różne kody błędów, które można zwrócić w error parametrze 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. Jest to błąd programistyczny i zazwyczaj jest przechwytywane podczas testowania początkowego. |
| unauthorized_client | Aplikacja kliencka nie może zażądać kodu autoryzacji. | Zwykle dzieje się tak, gdy aplikacja kliencka nie jest zarejestrowana w Azure AD lub nie jest dodawana do dzierżawy Azure AD użytkownika. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do Azure AD. |
| Access_denied | Odmowa zgody właściciela zasobu | Aplikacja kliencka może powiadomić użytkownika, ż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. Jest to błąd programistyczny i zazwyczaj jest przechwytywane podczas testowania początkowego. |
| 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 tymczasowego warunku. |
| invalid_resource | Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, Azure AD nie może go odnaleźć lub nie został poprawnie skonfigurowany. | Oznacza to, ż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 Azure AD. |
Weryfikowanie id_token
Po prostu otrzymanie elementu id_token nie jest wystarczające do uwierzytelnienia użytkownika. Musisz zweryfikować podpis i zweryfikować oświadczenia zgodnie id_token z wymaganiami aplikacji. Punkt końcowy Azure AD używa tokenów sieci Web JSON (JWTs) i kryptografii klucza publicznego do podpisywania tokenów i sprawdzania, czy są prawidłowe.
Możesz sprawdzić poprawność id_token kodu klienta, ale typowym rozwiązaniem jest wysłanie żądania id_token do serwera zaplecza i przeprowadzenie tam walidacji.
Możesz również zweryfikować dodatkowe oświadczenia w zależności od scenariusza. Niektóre typowe weryfikacje obejmują:
- Upewnienie się, że użytkownik/organizacja zarejestrował się w aplikacji.
- Upewnienie się, że użytkownik ma odpowiednią autoryzację/uprawnienia przy użyciu
widsoświadczeń lubroles. - Upewnienie się, że wystąpiła pewna siła uwierzytelniania, taka jak uwierzytelnianie wieloskładnikowe.
Po zweryfikowaniu id_tokenelementu można rozpocząć sesję z użytkownikiem i użyć oświadczeń w elemecie id_token , aby uzyskać informacje o użytkowniku w aplikacji. Te informacje mogą być używane do wyświetlania, rekordów, personalizacji itp. Aby uzyskać więcej informacji na temat id_tokens oświadczeń i oświadczeń, przeczytaj artykuł AAD id_tokens.
Wysyłanie żądania wylogowania
Jeśli chcesz wylogować użytkownika z aplikacji, nie wystarczy wyczyścić pliki cookie aplikacji lub zakończyć sesję z użytkownikiem. Musisz również przekierować użytkownika do end_session_endpoint wylogowania. Jeśli to nie zrobisz, użytkownik będzie mógł ponownie uwierzytelnić aplikację bez ponownego wprowadzania poświadczeń, ponieważ będzie miał prawidłową sesję logowania jednokrotnego z punktem końcowym Azure AD.
Możesz po prostu przekierować użytkownika do end_session_endpoint listy w dokumencie metadanych OpenID Connect:
GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
| Parametr | Typ | Opis |
|---|---|---|
| post_logout_redirect_uri | zalecane | Adres URL, do którego użytkownik powinien zostać przekierowany po pomyślnym wylogowaniu. Ten adres URL musi być zgodny z jednym z identyfikatorów URI przekierowania zarejestrowanych dla aplikacji w portalu rejestracji aplikacji. Jeśli post_logout_redirect_uri nie zostanie uwzględniona, zostanie wyświetlony ogólny komunikat. |
Wylogowanie jednokrotne
Po przekierowaniu użytkownika do programu end_session_endpointAzure AD wyczyści sesję użytkownika z przeglądarki. Jednak użytkownik może nadal być zalogowany do innych aplikacji, które używają Azure AD do uwierzytelniania. Aby umożliwić tym aplikacjom jednoczesne wylogowanie użytkownika, Azure AD wysyła żądanie HTTP GET do rejestracji LogoutUrl wszystkich aplikacji, do których użytkownik jest obecnie zalogowany. Aplikacje muszą odpowiadać na to żądanie, usuwając wszystkie sesje identyfikujące użytkownika i zwracając 200 odpowiedź. Jeśli chcesz obsługiwać logowanie jednokrotne w aplikacji, musisz zaimplementować taki kod LogoutUrl w kodzie aplikacji. Można ustawić LogoutUrl z poziomu Azure Portal:
- Zaloguj się w witrynie Azure Portal.
- Wybierz usługę Active Directory, klikając swoje konto w prawym górnym rogu strony.
- W panelu nawigacji po lewej stronie wybierz pozycję Azure Active Directory, a następnie wybierz pozycję Rejestracje aplikacji i wybierz aplikację.
- Kliknij pozycję Ustawienia, a następnie znajdź pole tekstowe Adres URL wylogowywania.
Pozyskiwanie tokenów
Wiele aplikacji internetowych musi nie tylko zalogować użytkownika, ale także uzyskać dostęp do usługi internetowej w imieniu tego użytkownika przy użyciu protokołu OAuth. Ten scenariusz łączy program OpenID Connect na potrzeby uwierzytelniania użytkowników podczas jednoczesnego uzyskiwania elementu authorization_code , który może służyć do access_tokens korzystania z przepływu kodu autoryzacji OAuth.
Uzyskiwanie tokenów dostępu
Aby uzyskać tokeny dostępu, należy zmodyfikować żądanie logowania z powyższego:
// Line breaks for legibility only
GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345 // Your registered Redirect Uri, url encoded
&response_mode=form_post // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F // The identifier of the protected resource (web API) that your application needs access to
&state=12345 // Any value, provided by your app
&nonce=678910 // Any value, provided by your app
Uwzględniając zakresy uprawnień w żądaniu i używając response_type=code+id_tokenpolecenia , authorize punkt końcowy gwarantuje, że użytkownik wyraził zgodę na uprawnienia wskazane w parametrze scope zapytania i zwróci aplikacji kod autoryzacji do wymiany tokenu dostępu.
Pomyślna odpowiedź
Pomyślna odpowiedź wysłana redirect_uri do metody przy użyciu response_mode=form_postwygląda następująco:
POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345
| Parametr | Opis |
|---|---|
| id_token | Żądana id_token aplikacja. Możesz użyć polecenia id_token , aby zweryfikować tożsamość użytkownika i rozpocząć sesję z użytkownikiem. |
| kod | Authorization_code żądana przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Authorization_codes są krótkotrwałe i zwykle wygasają po około 10 minutach. |
| stan | 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ź na błąd
Odpowiedzi na błędy mogą być również wysyłane do redirect_uri aplikacji, aby 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óry może służyć do klasyfikowania typów błędów, które występują, 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. |
Opis możliwych kodów błędów i zalecanej akcji klienta można znaleźć w temacie Kody błędów dla błędów punktu końcowego autoryzacji.
Po uzyskaniu autoryzacji code i elemencie id_tokenmożesz zalogować użytkownika i uzyskać tokeny dostępu w ich imieniu. Aby zalogować użytkownika, musisz zweryfikować id_token dokładnie to, co opisano powyżej. Aby uzyskać tokeny dostępu, możesz wykonać kroki opisane w sekcji "Używanie kodu autoryzacji do żądania tokenu dostępu" w dokumentacji przepływu kodu OAuth.
Następne kroki
- Dowiedz się więcej o tokenach dostępu.
- Dowiedz się więcej o
id_tokenoświadczeniach i .