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. Ogólnie rzecz biorąc, metoda używana do uzyskiwania tokenu zależy od tego, czy aplikacja jest publiczną aplikacją kliencką, np. aplikacją klasyczną, aplikacją mobilną, czy poufnymi aplikacjami klienckimi, takimi jak aplikacja internetowa, internetowy interfejs API lub aplikacja 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, która jest osiągana przez usunięcie kont 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 usługi Azure AD dla deweloperów (wersja 1.0) i 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.

Istnieje również możliwość uzyskania dostępu do zasobów w wersji 1.0 w usłudze MSAL. Aby uzyskać więcej informacji, zobacz Zakresy aplikacji w wersji 1.0.

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://11111111-1111-1111-1111-111111111111/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:

11111111-1111-1111-1111-111111111111/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ą jednak 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 Połączenie zalecanym wzorcem w kontrolerach jest:

  • 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

Ogólnie rzecz biorąc, metoda uzyskiwania tokenu zależy od tego, czy jest to klient publiczny, czy poufne aplikacje klienckie.

Publiczne aplikacje klienckie

W publicznych aplikacjach klienckich, takich jak aplikacje klasyczne i mobilne, 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ę. Następnie usługa Azure AD 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.
  • 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. Interfejs OpenID Połączenie aplikacji zazwyczaj używa tego mechanizmu, który umożliwia użytkownikowi logowanie się przy użyciu funkcji Open ID Connect, a następnie uzyskiwanie dostępu do internetowych interfejsów API w imieniu użytkownika.

Wyniki uwierzytelniania

Gdy klient żąda tokenu dostępu, usługa Azure AD 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 pisanie kodu w zależności od zawartości tokenu dostępu na kliencie jest 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 usługi Azure AD 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.