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 konta z pamięci podręcznej. Nie powoduje to jednak usunięcia pliku cookie sesji, który znajduje się w przeglądarce.

Zakresy podczas uzyskiwania 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 Platforma tożsamości Microsoft. Protokół w wersji 2.0 używa zakresów zamiast zasobów w żądaniach. Na podstawie konfiguracji internetowego interfejsu API 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 identyfikatora 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 aud akceptowanych wartości oświadczeń.

Tylko w przypadku programu Microsoft Graph user.read zakres jest mapowy na https://graph.microsoft.com/User.Read, a oba formaty zakresu 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 podrzędny nie jest pod kontrolą, może być konieczne wypróbowanie różnych formatów wartości zakresu (na przykład ze schematem i hostem), jeśli wystąpią 401 błędy 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 https://graph.microsoft.com/User.Read zakresów i https://graph.microsoft.com/Calendar.Read .

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

Biblioteka MSAL przechowuje pamięć podręczną tokenu (lub dwie pamięci podręczne dla poufnych aplikacji klienckich) i buforuje 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 zdobyć 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 używa pamięci podręcznej tokenu użytkownika, ale pamięci podręcznej tokenu 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 w miarę realizacji kodu uzyskanego przez aplikację przez zalogowanie użytkownika i wyrażania zgody na więcej zakresów. 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:

  • Utworzenie wystąpienia poufnej aplikacji klienckiej z pamięcią podręczną tokenu z dostosowaną serializacji.
  • 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 przez zalogowanie się użytkownika za pośrednictwem interfejsu użytkownika lub okna podręcznego.
  • 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 klasycznych programu .NET Framework (niezalecane). Nie używaj nazwy użytkownika/hasła w poufnych aplikacjach klienckich.
  • Pobierz token za pośrednictwem przepływu kodu urządzenia w aplikacjach uruchomionych na urządzeniach, które nie mają 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 samej aplikacji, a nie dla użytkownika przy użyciu przepływu 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.
  • Przepływ on-behalf-of (OBO) dla internetowego interfejsu API umożliwia wywołanie interfejsu API w imieniu użytkownika. Aplikacja jest identyfikowana z poświadczeniami klienta w celu uzyskania tokenu na podstawie asercji użytkownika (na przykład SAML lub tokenu JWT). Ten przepływ jest używany przez aplikacje, które muszą uzyskiwać dostęp do zasobów określonego użytkownika w wywołaniach typu service-to-service. Tokeny powinny być buforowane na podstawie sesji, a nie na podstawie użytkownika.
  • Uzyskiwanie tokenów przy użyciu przepływu kodu autoryzacji 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 buforowanie tokenów na podstawie użytkownika, zalecamy ograniczenie okresu istnienia sesji, aby identyfikator Entra firmy Microsoft 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 i zakresy, dla których są prawidłowe. 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 dla internetowego interfejsu API w celu uzyskania dostępu do zasobów. Ten ciąg jest zwykle zakodowany w formacie Base64 JWT, ale klient nigdy nie powinien szukać wewnątrz tokenu dostępu. Format nie jest gwarantowany, aby zachować stabilność i można go zaszyfrować dla 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 identyfikatora 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ści (scenariusze firmy Microsoft Entra B2B) identyfikator dzierżawy jest dzierżawą gościa, a nie unikatową dzierżawą. 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 biblioteki MSAL, aby umożliwić aplikacjom w tle, interfejsom API i usługom korzystanie z pamięci podręcznej tokenu dostępu, aby nadal działać w imieniu użytkowników w ich braku. Jest to szczególnie przydatne, jeśli aplikacje i usługi w tle muszą nadal działać w imieniu użytkownika po wyjściu z aplikacji internetowej frontonu.

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ładowy kod w witrynie GitHub pokazuje, jak uniknąć tego niepotrzebnego tarć, korzystając z pamięci podręcznej tokenów biblioteki MSAL z aplikacji w tle:

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

Notatka

Podczas uzyskiwania tokenów interaktywnie przy użyciu brokera uwierzytelniania broker uwierzytelniania najpierw wykona wyszukiwanie w pamięci podręcznej i zwróci buforowany token (problem z usługą GitHub — acquireToken używa 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: