Udostępnij za pośrednictwem

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

  • Artykuł

Tokeny dostępu umożliwiają klientom bezpieczne wywoływanie internetowych interfejsów API chronionych przez platformę Azure. Istnieje kilka sposobów uzyskiwania tokenu przy użyciu biblioteki Microsoft Authentication Library (MSAL). Niektóre wymagają interakcji użytkownika za pośrednictwem przeglądarki internetowej, a inne nie wymagają interakcji z użytkownikiem. Zazwyczaj metoda używana do uzyskiwania tokenu zależy od tego, czy aplikacja jest publiczną aplikacją kliencką (klasyczną lub mobilną), czy poufnym aplikacją kliencką (aplikacją internetową, internetowym interfejsem API lub aplikacją demona).

Biblioteka MSAL buforuje token po jego uzyskaniu. Kod aplikacji powinien najpierw spróbować uzyskać token w trybie dyskretnym z pamięci podręcznej przed podjęciem próby uzyskania tokenu w inny sposób.

Możesz również wyczyścić pamięć podręczną tokenów, usuwając z niej konta. Nie powoduje to jednak usunięcia pliku cookie sesji, który znajduje się w przeglądarce.

Zakresy podczas pozyskiwania tokenów

Zakresy to uprawnienia uwidaczniane przez internetowy interfejs API, do których aplikacje klienckie mogą żądać dostępu. Aplikacje klienckie żądają zgody użytkownika na te zakresy podczas wprowadzania żądań uwierzytelniania w celu uzyskania tokenów w celu uzyskania dostępu do internetowych interfejsów API. Biblioteka MSAL umożliwia uzyskiwanie tokenów dostępu do interfejsów API platformy tożsamości Microsoft. Protokół w wersji 2.0 używa zakresów zamiast zasobów w żądaniach. Na podstawie konfiguracji internetowego interfejsu API dotyczącej akceptowanej wersji tokenu, punkt końcowy w wersji 2.0 zwraca token dostępu do biblioteki MSAL.

Kilka metod pozyskiwania tokenu biblioteki MSAL wymaga parametru scopes . Parametr scopes jest listą ciągów, które deklarują żądane uprawnienia i żądane zasoby. Dobrze znane zakresy to uprawnienia programu Microsoft Graph.

Zakresy żądań dla internetowego interfejsu API

Gdy aplikacja musi zażądać tokenu dostępu z określonymi uprawnieniami dla interfejsu API zasobów, przekaż zakresy zawierające identyfikator URI aplikacji interfejsu API, w formacie <app ID URI>/<scope>.

Niektóre przykładowe wartości zakresu dla różnych zasobów:

  • Interfejs API programu Microsoft Graph: https://graph.microsoft.com/User.Read
  • Niestandardowy internetowy interfejs API: api://00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Format wartości zakresu różni się w zależności od zasobu (interfejsu API) odbierającego token dostępu i wartości roszczeń, które akceptuje.

Tylko w przypadku Microsoft Graph user.read zakres jest mapowany na https://graph.microsoft.com/User.Read, a oba formaty mogą być używane zamiennie.

Niektóre internetowe interfejsy API, takie jak interfejs API usługi Azure Resource Manager (https://management.core.windows.net/) oczekują końcowego ukośnika () w oświadczeniu odbiorców (/aud) tokenu dostępu. W takim przypadku przekaż zakres jako https://management.core.windows.net//user_impersonation, w tym podwójny ukośnik (//).

Inne interfejsy API mogą wymagać, aby żaden schemat lub host nie był uwzględniony w wartości zakresu i oczekiwać tylko identyfikatora aplikacji (identyfikatora GUID) i nazwy zakresu, na przykład:

00001111-aaaa-2222-bbbb-3333cccc4444/api.read

Napiwek

Jeśli zasób docelowy nie jest pod twoją kontrolą, może być konieczne wypróbowanie różnych formatów wartości zakresu, na przykład z/bez schematu i hosta (nazwa hosta), jeśli wystąpią błędy 401 lub inne błędy podczas przekazywania tokenu dostępu do zasobu.

W miarę zmiany funkcji udostępnianych przez aplikację lub jej wymagania można zażądać dodatkowych uprawnień zgodnie z potrzebami przy użyciu parametru zakresu. Takie zakresy dynamiczne umożliwiają użytkownikom zapewnienie przyrostowej zgody na zakresy.

Możesz na przykład zalogować się do użytkownika, ale początkowo odmówić im dostępu do dowolnych zasobów. Później możesz nadać im możliwość wyświetlania kalendarza, żądając zakresu kalendarza w metodzie uzyskiwania tokenu i uzyskując zgodę użytkownika na to. Na przykład przez żądanie zakresów https://graph.microsoft.com/User.Read i https://graph.microsoft.com/Calendar.Read.

Uzyskiwanie tokenów w trybie dyskretnym (z pamięci podręcznej)

Biblioteka MSAL utrzymuje cache tokenów (lub dwa cache dla poufnych aplikacji klienckich) i przechowuje token po jego uzyskaniu. W wielu przypadkach próba uzyskania tokenu w trybie dyskretnym spowoduje uzyskanie innego tokenu z większą liczbą zakresów na podstawie tokenu w pamięci podręcznej. Jest również w stanie odświeżyć token, gdy zbliża się do wygaśnięcia (ponieważ pamięć podręczna tokenu zawiera również token odświeżania).

Kod źródłowy aplikacji powinien najpierw spróbować uzyskać token w trybie dyskretnym z pamięci podręcznej. Jeśli wywołanie metody zwraca błąd lub wyjątek "Wymagany interfejs użytkownika", spróbuj uzyskać token w inny sposób.

Istnieją dwa przepływy, w których nie należy podejmować próby uzyskania tokenu w trybie dyskretnym:

  • Przepływ poświadczeń klienta, który nie korzysta z pamięci podręcznej tokenów użytkownika, ale z pamięci podręcznej tokenów dla aplikacji. Ta metoda sprawdza pamięć podręczną tokenu aplikacji przed wysłaniem żądania do usługi tokenu zabezpieczającego (STS).
  • Przepływ kodu autoryzacji w aplikacjach internetowych polega na wymianie kodu uzyskanego przez aplikację dzięki zalogowaniu się użytkownika i wyrażeniu zgody na uzyskanie dodatkowych uprawnień. Ponieważ kod, a nie konto jest przekazywane jako parametr, metoda nie może szukać w pamięci podręcznej przed zrealizowaniem kodu, który wywołuje wywołanie usługi.

W przypadku aplikacji internetowych korzystających z przepływu kodu autoryzacji OpenID Connect zalecany wzorzec w kontrolerach to:

  • Utwórz instancję poufnej aplikacji klienckiej z pamięcią podręczną tokenu, która ma dostosowaną serializację.
  • Uzyskiwanie tokenu przy użyciu przepływu kodu autoryzacji

Uzyskiwanie tokenów

Metoda uzyskiwania tokenu zależy od tego, czy jest to klient publiczny, czy poufne aplikacje klienckie.

Publiczne aplikacje klienckie

W publicznych aplikacjach klienckich (klasycznych i mobilnych) można wykonywać następujące czynności:

  • Interakcyjne uzyskiwanie tokenów poprzez zalogowanie się przez interfejs użytkownika lub okno podręczne.
  • Uzyskaj token dyskretnie dla zalogowanego użytkownika przy użyciu zintegrowanego uwierzytelniania systemu Windows (IWA/Kerberos), jeśli aplikacja klasyczna jest uruchomiona na komputerze z systemem Windows przyłączonym do domeny lub na platformie Azure.
  • Pobierz token z nazwą użytkownika i hasłem w aplikacjach klienckich desktopowych programu .NET Framework, co nie jest zalecane. Nie używaj nazwy użytkownika/hasła w poufnych aplikacjach klienckich.
  • Pobierz token za pomocą przepływu kodu urządzenia w aplikacjach działających na urządzeniach, które nie mają dostępu do przeglądarki internetowej. Użytkownik jest dostarczany z adresem URL i kodem, który następnie przechodzi do przeglądarki internetowej na innym urządzeniu i wprowadza kod i loguje się. Identyfikator Entra firmy Microsoft następnie wysyła token z powrotem do urządzenia bez przeglądarki.

Poufne aplikacje klienckie

W przypadku poufnych aplikacji klienckich (aplikacji internetowej, internetowego interfejsu API lub aplikacji demona, takiej jak usługa systemu Windows), możesz;

  • Uzyskiwanie tokenów dla aplikacji jako takiej, a nie dla użytkownika, wykorzystując przepływ poświadczeń klienta. Ta technika może służyć do synchronizowania narzędzi lub narzędzi, które przetwarzają użytkowników ogólnie, a nie określonego użytkownika.
  • Użyj mechanizmu on-behalf-of (OBO) dla internetowego API, aby wywołać API w imieniu użytkownika. Aplikacja jest rozpoznawana za pomocą poświadczeń klienta w celu uzyskania tokenu na podstawie asercji użytkownika (na przykład SAML lub tokenu JWT). Ten mechanizm jest używany przez aplikacje, które muszą uzyskiwać dostęp do zasobów określonego użytkownika w wywołaniach między usługami. Tokeny powinny być buforowane na podstawie sesji, a nie na podstawie użytkownika.
  • Uzyskuj tokeny przy użyciu przepływu kodu autoryzacyjnego w aplikacjach internetowych po zalogowaniu się użytkownika za pośrednictwem adresu URL żądania autoryzacji. Aplikacja OpenID Connect zazwyczaj używa tego mechanizmu, który umożliwia użytkownikowi logowanie się przy użyciu programu OpenID Connect, a następnie uzyskiwanie dostępu do internetowych interfejsów API w imieniu użytkownika. Tokeny mogą być buforowane przez użytkownika lub na podstawie sesji. Jeśli buforowane są tokeny dla poszczególnych użytkowników, zalecamy ograniczenie czasu trwania sesji, aby Microsoft Entra ID mógł często sprawdzać stan zasad dostępu warunkowego.

Wyniki uwierzytelniania

Gdy klient żąda tokenu dostępu, identyfikator Entra firmy Microsoft zwraca również wynik uwierzytelniania zawierający metadane dotyczące tokenu dostępu. Te informacje obejmują czas wygaśnięcia tokenu dostępu oraz zakresy, dla których jest on ważny. Te dane umożliwiają aplikacji inteligentne buforowanie tokenów dostępu bez konieczności analizowania samego tokenu dostępu. Wynik uwierzytelniania uwidacznia:

  • Token dostępu do zasobów poprzez web API. Ten ciąg jest zwykle zakodowany w formacie Base64 JWT, ale klient nigdy nie powinien szukać wewnątrz tokenu dostępu. Format nie jest gwarantowane, że pozostanie stabilny i może być szyfrowany w kontekście zasobu. Osoby piszące kod w zależności od zawartości tokenu dostępu na kliencie są jednym z najczęstszych źródeł błędów i przerwania logiki klienta.
  • Token ID dla użytkownika (JWT).
  • Wygaśnięcie tokenu, które informuje o dacie/godzinie wygaśnięcia tokenu.
  • Identyfikator dzierżawy zawiera dzierżawę, w której został znaleziony użytkownik. W przypadku użytkowników gościnnych (scenariusze Microsoft Entra B2B) identyfikator dzierżawy to identyfikator dzierżawy gościnnej, a nie dzierżawy domyślnej. Po dostarczeniu tokenu w nazwie użytkownika wynik uwierzytelniania zawiera również informacje o tym użytkowniku. W przypadku poufnych przepływów klienta, w których tokeny są żądane bez użytkownika (dla aplikacji), te informacje o użytkowniku mają wartość null.
  • Zakresy, dla których wystawiono token.
  • Unikatowy identyfikator użytkownika.

(Zaawansowane) Uzyskiwanie dostępu do buforowanych tokenów użytkownika w aplikacjach i usługach w tle

Możesz użyć implementacji pamięci podręcznej tokenów MSAL, aby umożliwić aplikacjom w tle, interfejsom API i usługom korzystanie z pamięci podręcznej tokenu dostępu, co pozwala im nadal działać w imieniu użytkowników podczas ich nieobecności. Jest to szczególnie przydatne, jeśli aplikacje i usługi działające w tle muszą nadal działać w imieniu użytkownika po wyjściu z aplikacji webowej front-end.

Obecnie większość procesów w tle używa uprawnień aplikacji, gdy muszą pracować z danymi użytkownika bez konieczności ich uwierzytelniania lub ponownego uwierzytelniania. Ponieważ uprawnienia aplikacji często wymagają zgody administratora, co wymaga podniesienia uprawnień, napotkano niepotrzebne tarcie, ponieważ deweloper nie zamierzał uzyskać uprawnień wykraczających poza to, na które użytkownik pierwotnie wyraził zgodę dla swojej aplikacji.

Ten przykład kodu w witrynie GitHub pokazuje, jak uniknąć tego niepotrzebnego tarcia, korzystając z pamięci podręcznej tokenów biblioteki MSAL poprzez aplikacje w tle.

Uzyskiwanie dostępu do pamięci podręcznej tokenów użytkownika zalogowanego z aplikacji działających w tle, interfejsów API i usług

Notatka

Podczas interaktywnego uzyskiwania tokenów za pomocą brokera uwierzytelniania pośrednik ten najpierw sprawdzi pamięć podręczną i, jeśli to możliwe, zwróci token z pamięci podręcznej (problem z GitHub — acquireToken korzysta z buforowania).

Zobacz też

Kilka platform obsługiwanych przez bibliotekę MSAL zawiera dodatkowe informacje dotyczące pamięci podręcznej tokenów w dokumentacji biblioteki tej platformy. Na przykład: