Udostępnij za pośrednictwem

Platforma tożsamości firmy Microsoft i poświadczenia hasła właściciela zasobu OAuth 2.0

  • Artykuł

Platforma tożsamości firmy Microsoft obsługuje Poświadczenie hasła właściciela zasobu (ROPC, Resource Owner Password Credentials) OAuth 2.0, co pozwala aplikacji logować użytkownika przez bezpośrednią obsługę jego hasła. 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. Ponadto, przyjrzyj się przykładowym aplikacjom korzystającym z biblioteki MSAL.

Ostrzeżenie

Firma Microsoft zaleca, aby nie korzystać z przepływu ROPC; jest on niezgodny z uwierzytelnianiem wieloskładnikowym (MFA). W większości scenariuszy dostępne są bezpieczniejsze alternatywy i zalecane. Ten przepływ wymaga bardzo wysokiego poziomu zaufania w aplikacji i niesie ze sobą ryzyko, które nie są obecne w innych przepływach. Tego przepływu należy używać tylko wtedy, gdy bardziej bezpieczne przepływy nie są opłacalne.

Ważny

  • Platforma tożsamości Microsoft obsługuje tylko udzielanie ROPC w ramach dzierżaw firmy Microsoft, a nie kont osobistych. Oznacza to, że należy użyć punktu dostępu specyficznego dla dzierżawy (https://login.microsoftonline.com/{TenantId_or_Name}) lub punktu dostępu organizations.
  • Konta osobiste zaproszone do obszaru Microsoft Entra nie mogą używać przepływu ROPC.
  • Konta, które nie mają haseł, nie mogą zalogować się przy użyciu rozwiązania ROPC, co oznacza, że funkcje takie jak logowanie sms, fiDO i aplikacja Authenticator nie będą działać z tym przepływem. Jeśli aplikacja lub użytkownicy wymagają tych funkcji, użyj typu przyznawania innego niż ROPC.
  • Jeśli użytkownicy muszą używać uwierzytelniania wieloskładnikowego (MFA), aby zalogować się do aplikacji, zostaną zablokowani.
  • ROPC nie jest obsługiwany w scenariuszach federacji tożsamości hybrydowej (na przykład, Microsoft Entra ID i AD FS używane do uwierzytelniania kont lokalnych). Jeśli użytkownicy są przekierowani na pełną stronę do lokalnego dostawcy tożsamości, identyfikator Entra firmy Microsoft nie może przetestować nazwy użytkownika i hasła względem tego dostawcy tożsamości. Uwierzytelnianie przekazywane jest obsługiwane jednak w przypadku uwierzytelniania ROPC.
  • Wyjątkiem od scenariusza federacji tożsamości hybrydowej byłoby następujące: Zasady Home Realm Discovery z AllowCloudPasswordValidation ustawione na wartość TRUE umożliwią działanie przepływu ROPC dla użytkowników federowanych, gdy hasło lokalne zostaje zsynchronizowane z chmurą. Więcej informacji znajdziesz w Włączanie bezpośredniego uwierzytelniania za pomocą ROPC użytkowników federacyjnych dla starszych aplikacji.
  • Hasła z wiodącymi lub końcowymi odstępami nie są obsługiwane przez proces uwierzytelniania ROPC.

Jak przeprowadzić migrację od ROPC

Ponieważ uwierzytelnianie wieloskładnikowe staje się bardziej powszechne, niektóre internetowe interfejsy API firmy Microsoft będą akceptować tokeny dostępu tylko wtedy, gdy zostały spełnione wymagania uwierzytelniania wieloskładnikowego. Aplikacje i platformy testowe oparte na ROPC zostaną zablokowane. Microsoft Entra nie wystawi tokenu lub żądanie zostanie odrzucone przez zasób.

Jeśli używasz ROPC do uzyskiwania tokenów, aby wywoływać chronione podrzędne interfejsy API, przeprowadź migrację do bezpiecznej strategii pozyskiwania tokenów.

Gdy kontekst użytkownika jest dostępny

Jeśli użytkownik końcowy musi uzyskać dostęp do zasobu, aplikacja kliencka działająca w ich imieniu powinna używać formy uwierzytelniania interakcyjnego. Użytkownik końcowy będzie proszony o uwierzytelnianie wieloskładnikowe tylko po wyświetleniu monitu w przeglądarce.

  • W przypadku aplikacji internetowych:
  • Interfejsy API sieci Web nie mogą wyświetlić przeglądarki. Zamiast tego muszą odesłać wyzwanie z powrotem do aplikacji klienckiej. Aby uzyskać szczegółowe informacje, zobacz interfejsy API sieci Web i stawianie wyzwań użytkownikom w interfejsach API sieci Web.
  • Aplikacje komputerowe powinny używać uwierzytelniania opartego na brokerze. Brokerzy korzystają z uwierzytelniania opartego na przeglądarce, dzięki czemu mogą wymagać uwierzytelniania wieloskładnikowego oraz zapewniać najbardziej bezpieczną konfigurację.
  • Aplikacje mobilne powinny być również skonfigurowane do korzystania z uwierzytelniania opartego na brokerze (Authenticator, Portal firmy).

Gdy kontekst użytkownika jest niedostępny

Przykładami scenariuszy, w których nie występuje kontekst użytkownika, mogą być, ale nie są ograniczone do następujących:

  • Skrypt działający w ramach pipeline'u CI.
  • Usługa, która musi wywołać zasób we własnym imieniu, bez danych użytkownika.

Deweloperzy aplikacji powinni używać uwierzytelniania jednostki usługi, co przedstawiono w przykładach demona . Uwierzytelnianie wieloskładnikowe nie ma zastosowania do podmiotów usługi.

Istnieje wiele sposobów uwierzytelniania jako jednostki usługi:

  • Jeśli Twoja aplikacja działa na Azure, użyj tożsamości zarządzanej. Tożsamość zarządzana eliminuje nakład pracy związany z zarządzaniem i rotacją tajemnic oraz certyfikatów.
  • Jeśli twoja aplikacja działa w systemie zarządzanym przez innego dostawcę tożsamości zgodnego z protokołem OAuth2, takiego jak GitHub, użyj Poświadczeń Tożsamości Federacyjnych.
  • Jeśli nie możesz użyć tożsamości zarządzanej ani tożsamości federacyjnej, użyj poświadczenia certyfikatu .

Ostrzeżenie

Nie używaj uwierzytelniania jednostki usługi, gdy kontekst użytkownika jest dostępny. Dostęp wyłącznie przez aplikację z natury ma wysoki poziom uprawnień, często zapewniając dostęp na poziomie całego dzierżawcy i potencjalnie pozwalając złośliwemu podmiotowi na dostęp do danych wszystkich klientów.

Diagram protokołu

Na poniższym diagramie przedstawiono przepływ ROPC.

Diagram przedstawiający przepływ uwierzytelniania hasłem właściciela zasobu

Żądanie autoryzacji

Przepływ ROPC jest pojedynczym żądaniem; wysyła identyfikację klienta i poświadczenia użytkownika do dostawcy tożsamości i otrzymuje tokeny w zamian. Przed wykonaniem tej czynności klient musi zażądać adresu e-mail użytkownika (UPN) i hasła. Natychmiast po pomyślnym żądaniu klient powinien bezpiecznie odrzucić poświadczenia użytkownika z pamięci. Nigdy nie może ich uratować.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password
Parametr Warunek Opis
tenant Wymagane Tenant katalogu, do którego chcesz zalogować użytkownika. Format tenanta może być w formacie GUID lub przyjazna nazwa. Nie można jednak ustawić parametru na wartość common lub consumers, ale może być ustawiona na wartość organizations.
client_id Wymagane Identyfikator aplikacji (klienta), który Centrum administracyjne Microsoft Entra – strona Rejestracje aplikacji przypisała do aplikacji.
grant_type Wymagane Musi być ustawione na password.
username Wymagane Adres e-mail użytkownika.
password Wymagane Hasło użytkownika.
scope Zalecane Lista rozdzielona spacjami zakresów , lub uprawnień, które aplikacja wymaga. W przepływie interaktywnym administrator lub użytkownik musi z wyprzedzeniem wyrazić zgodę na te zakresy.
client_secret Czasami wymagane Jeśli aplikacja jest klientem publicznym, nie można uwzględnić client_secret lub client_assertion. Jeśli aplikacja jest poufnym klientem, musi zostać uwzględniona.
client_assertion Czasami wymagane Inna forma client_secretwygenerowana przy użyciu certyfikatu. Aby uzyskać więcej informacji, zobacz dane uwierzytelniające certyfikatu .

Pomyślna odpowiedź uwierzytelniania

W poniższym przykładzie przedstawiono pomyślną odpowiedź tokenu:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Parametr Format Opis
token_type Struna Zawsze ustaw na Bearer.
scope Oddzielone spacjami ciągi Jeśli zwrócono token dostępu, ten parametr zawiera listę zakresów, dla których token dostępu jest prawidłowy.
expires_in Int Liczba sekund ważności dołączonego tokenu dostępu.
access_token Nieprzezroczysty ciąg Wystawione dla zakresów , które zostały żądane.
id_token JWT Wystawiono, jeśli oryginalny parametr scope zawierał zakres openid.
refresh_token Nieprzezroczysty ciąg Wystawiono, jeśli oryginalny parametr scope zawierał offline_access.

Token odświeżania może być użyty do uzyskiwania nowych tokenów dostępu i nowych tokenów odświeżania, korzystając z tego samego przepływu opisanego w dokumentacji przepływu kodu OAuth .

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

Jeśli użytkownik nie podał poprawnej nazwy użytkownika lub hasła lub klient nie otrzymał żądanej zgody, uwierzytelnianie zakończy się niepowodzeniem.

Błąd Opis Akcja klienta
invalid_grant Uwierzytelnianie nie powiodło się Poświadczenia były nieprawidłowe lub klient nie ma zgody na żądane zakresy. Jeśli zakresy nie zostaną przyznane, zostanie zwrócony błąd consent_required. Aby rozwiązać ten błąd, klient powinien wysłać użytkownika do interakcyjnego monitu przy użyciu widoku internetowego lub przeglądarki.
invalid_request Żądanie zostało nieprawidłowo skonstruowane Rodzaj uprawnienia nie jest obsługiwany w kontekstach uwierzytelniania /common ani /consumers. Zamiast tego użyj /organizations lub identyfikatora dzierżawy.

Dowiedz się więcej

Aby zapoznać się z przykładową implementacją przepływu ROPC, zobacz aplikację konsolową .NET i przykład kodu na GitHubie.