Obsługa przepływu uwierzytelniania w bibliotece Microsoft Authentication Library (MSAL)

Biblioteka Microsoft Authentication Library (MSAL) obsługuje kilka uprawnień autoryzacyjnych i powiązanych przepływów tokenów do użycia przez różne typy aplikacji i scenariusze.

Przepływ uwierzytelniania	Umożliwia	Obsługiwane typy aplikacji
Kod autoryzacji	Logowanie użytkownika i dostęp do API sieciowych na rzecz użytkownika.	Pulpit Rozwiązania mobilne Aplikacja jednostronicowa (SPA) (wymaga PKCE) Sieć Web
Poświadczenia klienta	Dostęp do internetowych interfejsów API przy użyciu tożsamości samej aplikacji. Zazwyczaj używane do komunikacji między serwerami i zautomatyzowanych skryptów, które nie wymagają interakcji z użytkownikiem.	Daemon
Kod urządzenia	Logowanie użytkownika i dostęp do internetowych interfejsów API w imieniu użytkownika na urządzeniach z ograniczonymi danymi wejściowymi, takich jak inteligentne telewizory i urządzenia IoT. Używane również przez aplikacje interfejsu wiersza polecenia.	Desktop, Mobile
Implicitne przyznanie	Logowanie użytkownika i dostęp do API sieciowych na rzecz użytkownika. Nie używaj tego przepływu — zamiast tego użyj kodu autoryzacji z PKCE.	* Aplikacja jednostronicowa (SPA) * Sieć
W imieniu (OBO)	Dostęp z internetowego interfejsu API "nadrzędnego" do internetowego interfejsu API "podrzędnego" w imieniu użytkownika. Tożsamość użytkownika i uprawnienia delegowane są przekazywane do podrzędnego interfejsu API z nadrzędnego interfejsu API.	Web API
Nazwa użytkownika/hasło (ROPC)	Umożliwia aplikacji logowanie użytkownika przez bezpośrednie obsługiwanie hasła. Nie używaj tego przepływu.	Desktop, Mobile
Zintegrowane uwierzytelnianie systemu Windows (IWA)	Umożliwia aplikacjom na komputerach przyłączonych do domeny lub Microsoft Entra uzyskiwanie tokenu w sposób dyskretny (bez interakcji z użytkownikiem).	Desktop, Mobile

Tokeny

Aplikacja może używać co najmniej jednego przepływu uwierzytelniania. Każdy przepływ używa niektórych typów tokenów do uwierzytelniania, autoryzacji i odświeżania tokenu, a niektóre używają również kodu autoryzacji.

Przepływ lub akcja uwierzytelniania	Wymaga	Token identyfikatora	Token dostępu	Odświeżanie tokenu	Kod autoryzacji
Przepływ kodu autoryzacji
Poświadczenia klienta			(tylko dla aplikacji)
Przepływ kodu urządzenia
Przepływ implicit
Przepływ „w imieniu”	token dostępu
Nazwa użytkownika/hasło (ROPC)	nazwa użytkownika, hasło
Hybrydowy przepływ OIDC
Odświeżanie realizacji tokenu	token odświeżania

Uwierzytelnianie interakcyjne i nieinterakcyjne

Kilka z tych przepływów obsługuje pozyskiwanie tokenów interakcyjnych i nieinterakcyjnych.

• Interakcyjne — użytkownik może zostać poproszony o podanie danych wejściowych przez serwer autoryzacji. Na przykład aby się zalogować, przeprowadzić uwierzytelnianie wieloskładnikowe (MFA) lub udzielić zgody na więcej uprawnień dostępu do zasobów.
• Nieinterakcyjne (dyskretne) — użytkownik może nie być monitowany o podanie danych wejściowych. Nazywana również pozyskiwaniem tokenu dyskretnego, aplikacja próbuje uzyskać token przy użyciu metody, w której serwer autoryzacji może nie monitować użytkownika o podanie danych wejściowych.

Aplikacja oparta na protokole MSAL powinna najpierw spróbować uzyskać token w trybie dyskretnym i wrócić do metody interaktywnej tylko wtedy, gdy próba nieinterakacyjna zakończy się niepowodzeniem. Aby uzyskać więcej informacji na temat tego wzorca, zobacz Uzyskiwanie i buforowanie tokenów przy użyciu biblioteki Microsoft Authentication Library (MSAL).

Kod autoryzacji

Przyznawanie kodu autoryzacji OAuth 2.0 może być używane przez aplikacje internetowe, aplikacje jednostronicowe (SPA) i aplikacje natywne (mobilne i klasyczne) w celu uzyskania dostępu do chronionych zasobów, takich jak internetowe interfejsy API.

Gdy użytkownicy logują się do aplikacji internetowych, aplikacja otrzymuje kod autoryzacji, który może wymienić na token dostępu, aby wywołać interfejsy API.

Na poniższym diagramie aplikacja:

1. Żąda kodu autoryzacji, który został wymieniony na token dostępu
2. Używa tokenu dostępu do wywoływania internetowego interfejsu API, programu Microsoft Graph

Ograniczenia dotyczące kodu autoryzacji

• Aplikacje jednostronicowe wymagają klucza dowodowego dla wymiany kodu (PKCE) podczas korzystania z przepływu udzielania kodu autoryzacji. Protokół PKCE jest obsługiwany przez bibliotekę MSAL.

• Specyfikacja protokołu OAuth 2.0 wymaga użycia kodu autoryzacji do uzyskania tokenu dostępu tylko raz.

  Jeśli spróbujesz uzyskać token dostępu wiele razy z tym samym kodem autoryzacji, platforma tożsamości Microsoft zwróci błąd podobny do poniższego. Niektóre biblioteki i struktury żądają automatycznie kodu autoryzacji, a żądanie kodu ręcznie w takich przypadkach spowoduje również ten błąd.

  AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.
  

Poświadczenia klienta

Przepływ poświadczeń klienta OAuth 2.0 umożliwia dostęp do zasobów hostowanych w Internecie przy użyciu tożsamości aplikacji. Ten typ uprawnień jest często używany do interakcji między serwerami, które muszą działać w tle bez natychmiastowej interakcji z użytkownikiem. Tego typu aplikacje są często nazywane daemonami lub kontami usługi.

Przepływ autoryzacji przy użyciu poświadczeń klienta pozwala usłudze internetowej (poufny klient) na używanie własnych poświadczeń zamiast podszywania się pod użytkownika w celu uwierzytelnienia podczas wywoływania innej usługi internetowej. W tym scenariuszu klient jest zazwyczaj usługą internetową warstwy środkowej, usługą demona lub witryną internetową. W celu zapewnienia wyższego poziomu bezpieczeństwa platforma tożsamości Microsoft umożliwia również usłudze wywołującej użycie certyfikatu (zamiast wspólnego sekretu) jako poświadczenia.

Sekrety aplikacji

Na poniższym diagramie aplikacja:

1. Uzyskuje token przy użyciu tajnego klucza aplikacji lub poświadczeń hasła
2. Używa tokenu do żądania zasobu

Certyfikaty

Na poniższym diagramie aplikacja:

1. Uzyskuje token za pomocą poświadczeń certyfikatowych.
2. Używa tokenu do żądania zasobu

Te poświadczenia klienta muszą być następujące:

• Zarejestrowane w usłudze Microsoft Entra ID
• Przekazywane podczas konstruowania poufnego obiektu aplikacji klienckiej w kodzie

Ograniczenia dotyczące poświadczeń klienta

Przepływ poufnego klienta nie jest wspierany na platformach mobilnych, takich jak Android, iOS lub UWP. Aplikacje mobilne są uznawane za publiczne aplikacje klienckie, które nie mogą zagwarantować poufności swoich poświadczeń.

Kod urządzenia

Przepływ kodu urządzenia OAuth 2.0 umożliwia użytkownikom logowanie się do urządzeń z ograniczonymi danymi wejściowymi, takimi jak inteligentne telewizory, urządzenia IoT i drukarki. Uwierzytelnianie interakcyjne przy użyciu identyfikatora Entra firmy Microsoft wymaga przeglądarki internetowej. Jeśli urządzenie lub system operacyjny nie udostępnia przeglądarki internetowej, przepływ kodu urządzenia umożliwia użytkownikowi interaktywne logowanie się za pomocą innego urządzenia, takiego jak komputer lub telefon komórkowy.

Korzystając z przepływu kodu urządzenia, aplikacja uzyskuje tokeny za pośrednictwem dwuetapowego procesu przeznaczonego dla tych urządzeń i systemów operacyjnych. Przykłady takich aplikacji obejmują te uruchomione na urządzeniach IoT i narzędzia interfejsu wiersza polecenia (CLI).

Na poniższym diagramie:

1. Za każdym razem, gdy wymagane jest uwierzytelnianie użytkownika, aplikacja udostępnia kod i prosi użytkownika o użycie innego urządzenia, takiego jak smartfon połączony z Internetem, aby odwiedził adres URL (na przykład https://microsoft.com/devicelogin). Następnie użytkownik zostanie poproszony o wprowadzenie kodu i przejście przez standardową procedurę uwierzytelniania, w tym monity o wyrażenie zgody i uwierzytelnianie wieloskładnikowe, jeśli to konieczne.
2. Po pomyślnym uwierzytelnieniu aplikacja wiersza polecenia odbiera wymagane tokeny za pośrednictwem kanału zaplecza i używa ich do wykonywania potrzebnych wywołań internetowego interfejsu API.

Ograniczenia dotyczące kodu urządzenia

• Przepływ kodu urządzenia jest dostępny tylko dla publicznych aplikacji klienckich.
• Podczas inicjowania publicznej aplikacji klienckiej w bibliotece MSAL użyj jednego z następujących formatów autoryzacji:
  • Dzierżawa: https://login.microsoftonline.com/{tenant}/, gdzie {tenant} jest identyfikatorem dzierżawy lub nazwą domeny skojarzona z dzierżawą.
  • Konta służbowe i szkolne: https://login.microsoftonline.com/organizations/.

Niejawne udzielenie

Niejawny przepływ autoryzacji został zastąpiony przepływem kodu autoryzacji z użyciem PKCE jako preferowanym i bardziej bezpiecznym sposobem przyznawania tokenów dla jednostronicowych aplikacji po stronie klienta (SPA).

Ostrzeżenie

Nie zaleca się już używania niejawnego przepływu udzielania. Jeśli tworzysz SPA, zamiast tego użyj przepływu kodu autoryzacji z PKCE.

Jednostronicowe aplikacje internetowe napisane w języku JavaScript (w tym struktury, takie jak Angular, Vue.js lub React.js) są pobierane z serwera, a ich kod działa bezpośrednio w przeglądarce. Ponieważ ich kod po stronie klienta jest uruchamiany w przeglądarce, a nie na serwerze internetowym, mają różne właściwości zabezpieczeń niż tradycyjne aplikacje internetowe po stronie serwera. Przed udostępnieniem klucza dowodowego dla wymiany kodu (PKCE) dla przepływu kodu autoryzacji niejawny przepływ udzielania był używany przez dostawcy usług w celu zwiększenia czasu odpowiedzi i wydajności uzyskiwania tokenów dostępu.

Niejawny przepływ udzielania OAuth 2.0 umożliwia uzyskiwanie przez aplikację tokenów dostępu z platformy tożsamości Microsoft bez przeprowadzania wymiany poświadczeń serwera backendowego. Niejawny przepływ udzielania umożliwia aplikacji logowanie użytkownika, utrzymywanie sesji i uzyskiwanie tokenów dla innych internetowych interfejsów API z poziomu kodu JavaScript pobranego i uruchamianego przez agenta użytkownika (zazwyczaj przeglądarki internetowej).

Ograniczenia dotyczące niejawnego udzielania

Niejawny przepływ udzielania nie obejmuje scenariuszy aplikacji korzystających z międzyplatformowych struktur Języka JavaScript, takich jak Electron lub React Native. Platformy międzyplatformowe, takie jak te, wymagają dalszych możliwości interakcji z natywnymi platformami komputerowymi i mobilnymi, na których działają.

Tokeny wystawione za pośrednictwem niejawnego trybu przepływu mają ograniczenie długości, ponieważ są zwracane do przeglądarki według adresu URL (gdzie response_mode to query lub fragment). Niektóre przeglądarki ograniczają długość adresu URL na pasku przeglądarki i kończą się niepowodzeniem, gdy jest za długa. W związku z tym te ukryte tokeny przepływu nie zawierają groups ani wids żądań.

W imieniu (OBO)

Przepływ uwierzytelniania OAuth 2.0 w imieniu jest używany, gdy aplikacja wywołuje usługę lub web API, do wywołania której potrzebne jest kolejne usługi lub web API. Chodzi o propagowanie delegowanej tożsamości użytkownika i uprawnień za pośrednictwem łańcucha żądań. Aby usługa warstwy środkowej wysyłała uwierzytelnione żądania do usługi podrzędnej, musi zabezpieczyć token dostępu z Platforma tożsamości Microsoft w imieniu użytkownika.

Na poniższym diagramie:

1. Aplikacja uzyskuje token dostępu dla internetowego interfejsu API.
2. Klient (aplikacja internetowa, desktopowa, mobilna lub jednostronicowa) wywołuje chroniony interfejs API, dodając token dostępu jako token nosiciela w nagłówku uwierzytelniania żądania HTTP. Internetowy interfejs API uwierzytelnia użytkownika.
3. Gdy klient wywołuje internetowy interfejs API, internetowy interfejs API żąda innego tokenu w imieniu użytkownika.
4. Chroniony internetowy interfejs API używa tego tokenu do wywoływania podrzędnego internetowego interfejsu API w imieniu użytkownika. Internetowy interfejs API może również później żądać tokenów dla innych podrzędnych interfejsów API (ale nadal w imieniu tego samego użytkownika).

Nazwa użytkownika/hasło (ROPC)

Przyznawanie uprawnień dostępu hasłem właściciela zasobu OAuth 2.0 (ROPC) umożliwia aplikacji logowanie użytkownika bezpośrednio poprzez wykorzystanie hasła. W aplikacji klasycznej możesz użyć przepływu nazwy użytkownika/hasła, aby uzyskać token w trybie dyskretnym. W przypadku korzystania z aplikacji nie jest wymagany żaden interfejs użytkownika.

Ostrzeżenie

Zrezygnowano z procesu ROPC, użyj bardziej bezpiecznego procesu. Postępuj zgodnie z tym przewodnikiem , aby uzyskać wskazówki dotyczące migracji. ROPC wymaga wysokiego stopnia zaufania i ujawnienia poświadczeń. Aby uzyskać więcej informacji, zobacz Jakie jest rozwiązanie rosnącego problemu haseł?.

Na poniższym diagramie aplikacja:

1. Uzyskuje token, wysyłając nazwę użytkownika i hasło do dostawcy tożsamości
2. Wywołuje internetowy interfejs API przy użyciu tokenu

Aby uzyskać token dyskretnie na komputerach przyłączonych do domeny systemu Windows, zalecamy zintegrowane uwierzytelnianie systemu Windows (IWA) zamiast ROPC. W innych scenariuszach użyj przepływu kodu dla urządzenia.

Ograniczenia dla ROPC

Następujące ograniczenia dotyczą aplikacji przy użyciu przepływu ROPC:

• Logowanie jednokrotne nie jest obsługiwane.
• Uwierzytelnianie wieloskładnikowe (MFA) nie jest obsługiwane.
  • Zanim zaczniesz korzystać z tego przepływu, skonsultuj się z administratorem dzierżawcy — uwierzytelnianie wieloskładnikowe jest często używaną funkcją.
• Dostęp warunkowy jest nieobsługiwany.
• ROPC działa tylko dla kont służbowych lub szkolnych.
• Osobiste konta Microsoft (MSA) nie są obsługiwane przez ROPC.
• ROPC jest obsługiwany w aplikacjach desktopowych .NET i ASP.NET Core.
• ROPC nie jest obsługiwany w aplikacjach Platformy uniwersalnej systemu Windows (UWP).
• RopC w usłudze Azure AD B2C jest obsługiwany tylko dla kont lokalnych.
  • Aby uzyskać informacje o ROPC w usługach MSAL.NET i Azure AD B2C, zobacz Używanie ROPC z Azure AD B2C.

Zintegrowane uwierzytelnianie systemu Windows (IWA)

Biblioteka MSAL obsługuje zintegrowane uwierzytelnianie Windows (IWA) dla aplikacji desktopowych i mobilnych uruchamianych na komputerach przyłączonych do domeny lub komputerach z systemem Windows przyłączonych do Microsoft Entra. Korzystając z IWA, te aplikacje uzyskują token w sposób niewidoczny, bez konieczności interakcji użytkownika z interfejsem.

Na poniższym diagramie aplikacja:

1. Uzyskuje token przy użyciu zintegrowanego uwierzytelniania systemu Windows
2. Używa tokenu do żądania zasobu

Ograniczenia dla IWA

Zgodność

Zintegrowane uwierzytelnianie systemu Windows (IWA) jest włączone dla aplikacji .NET desktopowych, .NET i aplikacji na Platformę Uniwersalną Windows.

IWA obsługuje tylko użytkowników federacyjnych usług AD FS — użytkowników utworzonych w usłudze Active Directory i wspieranych przez Microsoft Entra ID. Użytkownicy utworzeni bezpośrednio w usłudze Microsoft Entra ID, bez zaplecza Active Directory (zarządzani użytkownicy), nie mogą używać tego przepływu uwierzytelniania.

Uwierzytelnianie wieloskładnikowe (MFA)

Uwierzytelnianie nieinterakcyjne (dyskretne) IWA może zakończyć się niepowodzeniem, jeśli usługa MFA jest włączona w dzierżawie firmy Microsoft Entra, a wyzwanie uwierzytelniania wieloskładnikowego jest wystawiane przez identyfikator firmy Microsoft Entra. W przypadku niepowodzenia interfejsu IWA należy wrócić do interaktywnej metody uwierzytelniania zgodnie z wcześniejszym opisem.

Identyfikator entra firmy Microsoft używa sztucznej inteligencji do określenia, kiedy wymagane jest uwierzytelnianie dwuskładnikowe. Uwierzytelnianie dwuskładnikowe jest zwykle wymagane, gdy użytkownik loguje się z innego kraju/regionu, gdy jest połączony z siecią firmową bez korzystania z sieci VPN, a czasami gdy jest połączony* za pośrednictwem sieci VPN. Ponieważ konfiguracja i częstotliwość wyzwań uwierzytelniania wieloskładnikowego mogą znajdować się poza kontrolą dewelopera, aplikacja powinna bezpiecznie obsługiwać niepowodzenie pozyskiwania tokenu dyskretnego IWA.

Ograniczenia identyfikatora URI autorytetu

Jednostka autoryzacyjna przekazana podczas konstruowania publicznej aplikacji klienckiej musi być jednym z następujących elementów:

• https://login.microsoftonline.com/{tenant}/ — To uprawnienie wskazuje aplikację jednostanowiskową, której odbiorcy logowania są ograniczeni do użytkowników w określonej dzierżawie Microsoft Entra. Wartość {tenant} może być identyfikatorem dzierżawy w formularzu GUID lub nazwą domeny skojarzona z dzierżawą.
• https://login.microsoftonline.com/organizations/ — Ten urząd oznacza aplikację wielodostępną, której odbiorcami logowania są użytkownicy w dowolnej dzierżawie Microsoft Entra.

Wartości autoryzacji nie mogą zawierać /common ani /consumers, ponieważ osobiste konta Microsoft (MSA) nie są obsługiwane przez usługę IWA.

Wymagania dotyczące zgody

Ponieważ IWA jest cichym przepływem:

• Użytkownik aplikacji musi wcześniej wyrazić zgodę na korzystanie z aplikacji.

  LUB

• Administrator dzierżawy musi wcześniej wyrazić zgodę na wszystkich użytkowników w dzierżawie w celu korzystania z aplikacji.

Aby spełnić oba wymagania, należy wykonać jedną z tych operacji:

• Jako deweloper aplikacji wybrałeś opcję Grant w portalu Azure dla siebie.
• Administrator dzierżawy wybrał pozycję Udziel/odwołaj zgodę administratora dla {domeny dzierżawy} na karcie Uprawnienia interfejsu API rejestracji aplikacji w witrynie Azure Portal. Zobacz Dodawanie uprawnień dostępu do internetowego interfejsu API.
• Udostępniono użytkownikom sposób wyrażania zgody na aplikację; zobacz Zgoda użytkownika.
• Udostępniono administratorowi dzierżawy sposób wyrażania zgody na aplikację; zobacz Zgoda administratora.

Aby uzyskać więcej informacji na temat zgody, zobacz Uprawnienia i zgoda.

Następny krok

Dowiedz się więcej o uzyskiwaniu i buforowaniu tokenów używanych w tych przepływach:

Uzyskiwanie i buforowanie tokenów przy użyciu biblioteki Microsoft Authentication Library (MSAL)