Tokeny dostępu w Platforma tożsamości Microsoft

Tokeny dostępu umożliwiają klientom bezpieczne wywoływanie chronionych internetowych interfejsów API. Internetowe interfejsy API używają tokenów dostępu do przeprowadzania uwierzytelniania i autoryzacji.

Zgodnie ze specyfikacją protokołu OAuth tokeny dostępu są nieprzezroczystymi ciągami bez ustawionego formatu. Niektórzy dostawcy tożsamości używają identyfikatorów GUID, a inni używają zaszyfrowanych obiektów blob. Format tokenu dostępu może zależeć od konfiguracji interfejsu API, który go akceptuje.

Niestandardowe interfejsy API zarejestrowane przez deweloperów w Platforma tożsamości Microsoft mogą wybierać spośród dwóch różnych formatów tokenów sieci Web JSON (JWTs) o nazwie v1.0 i v2.0. Interfejsy API opracowane przez firmę Microsoft, takie jak Program Microsoft Graph lub interfejsy API na platformie Azure, mają inne zastrzeżone formaty tokenów. Te zastrzeżone formaty, których nie można zweryfikować, mogą być szyfrowane tokeny, JWTs lub specjalne JWT podobne do tych.

Zawartość tokenu jest przeznaczona tylko dla interfejsu API, co oznacza, że tokeny dostępu muszą być traktowane jako nieprzezroczyste ciągi. Tylko do celów walidacji i debugowania deweloperzy mogą dekodować JWTs przy użyciu witryny, takiej jak jwt.ms. Tokeny odbierane przez interfejs API firmy Microsoft mogą nie zawsze być zestawem JWT, które można dekodować.

Klienci powinni używać danych odpowiedzi tokenu, które są zwracane z tokenem dostępu, aby uzyskać szczegółowe informacje na temat tego, co znajduje się w nim. Gdy klient żąda tokenu dostępu, Platforma tożsamości Microsoft również zwraca pewne metadane dotyczące tokenu dostępu do użycia aplikacji. 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.

Zapoznaj się z poniższymi sekcjami, aby dowiedzieć się, jak interfejs API może weryfikować oświadczenia i używać ich wewnątrz tokenu dostępu.

Uwaga

Cała dokumentacja na tej stronie, z wyjątkiem przypadków zanotowanych, dotyczy tylko tokenów wystawionych dla zarejestrowanych interfejsów API. Nie ma zastosowania do tokenów wystawionych dla interfejsów API należących do firmy Microsoft ani nie można ich używać do sprawdzania, w jaki sposób Platforma tożsamości Microsoft wystawia tokeny dla zarejestrowanego interfejsu API.

Formaty tokenów

W Platforma tożsamości Microsoft są dostępne dwie wersje tokenów dostępu: v1.0 i v2.0. Te wersje określają oświadczenia, które znajdują się w tokenie i upewnij się, że internetowy interfejs API może kontrolować zawartość tokenu.

Interfejsy API sieci Web mają jedną z następujących wersji wybranych jako domyślna podczas rejestracji:

• Wersja 1.0 dla aplikacji tylko firmy Microsoft. W poniższym przykładzie pokazano token w wersji 1.0 (klucze są zmieniane, a informacje osobiste są usuwane, co uniemożliwia walidację tokenu):

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
  

• Wersja 2.0 dla aplikacji obsługujących konta konsumentów. W poniższym przykładzie pokazano token w wersji 2.0 (klucze są zmieniane, a informacje osobiste są usuwane, co uniemożliwia walidację tokenu):

  eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
  

Ustaw wersję aplikacji, podając odpowiednią wartość dla accessTokenAcceptedVersion ustawienia w manifeście aplikacji. Wartości null i 1 wynikowe tokeny w wersji 1.0 oraz wartość 2 wyników w tokenach w wersji 2.0.

Własność tokenu

Żądanie tokenu dostępu obejmuje dwie strony: klienta, który żąda tokenu, oraz zasobu (internetowego interfejsu API), który akceptuje token. Zasób przeznaczony dla tokenu (jego odbiorcy) jest zdefiniowany w oświadczeniu aud w tokenie. Klienci używają tokenu, ale nie powinni rozumieć ani próbować go przeanalizować. Zasoby akceptują token.

Platforma tożsamości Microsoft obsługuje wystawianie dowolnej wersji tokenu z dowolnego punktu końcowego wersji. Na przykład gdy wartość parametru accessTokenAcceptedVersion to 2, klient wywołujący punkt końcowy w wersji 1.0, aby uzyskać token dla tego zasobu, otrzymuje token dostępu w wersji 2.0.

Zasoby zawsze posiadają swoje tokeny przy użyciu aud oświadczenia i są jedynymi aplikacjami, które mogą zmienić szczegóły tokenu.

Okres istnienia tokenu

Domyślny okres istnienia tokenu dostępu to zmienna. Po wystawieniu Platforma tożsamości Microsoft przypisuje losową wartość z zakresu od 60 do 90 minut (średnio 75 minut) jako domyślny okres istnienia tokenu dostępu. Odmiana zwiększa odporność usługi przez rozłożenie zapotrzebowania na token dostępu w czasie, co zapobiega wzrostowi liczby godzin ruchu do identyfikatora Entra firmy Microsoft.

Dzierżawy, które nie korzystają z dostępu warunkowego, mają domyślny okres istnienia tokenu dostępu na dwie godziny dla klientów, takich jak Microsoft Teams i Microsoft 365.

Dostosuj okres istnienia tokenu dostępu, aby kontrolować, jak często aplikacja kliencka wygasa sesji aplikacji i jak często wymaga ponownego uwierzytelnienia użytkownika (w trybie dyskretnym lub interakcyjnym). Aby zastąpić domyślną odmianę okresu istnienia tokenu dostępu, użyj opcji Konfigurowalny okres istnienia tokenu (CTL).

Zastosuj domyślną odmianę okresu istnienia tokenu do organizacji z włączoną ciągłą oceną dostępu (CAE). Zastosuj domyślną odmianę okresu istnienia tokenu, nawet jeśli organizacje używają zasad CTL. Domyślny okres istnienia tokenu dla długożytnego okresu istnienia tokenu waha się od 20 do 28 godzin. Po wygaśnięciu tokenu dostępu klient musi użyć tokenu odświeżania, aby dyskretnie uzyskać nowy token odświeżania i token dostępu.

Organizacje korzystające z częstotliwości logowania dostępu warunkowego (SIF), aby wymusić, jak często występują logowania, nie mogą zastąpić domyślnej odmiany okresu istnienia tokenu dostępu. Gdy organizacje używają SIF, czas między monitami poświadczeń dla klienta jest okres istnienia tokenu, który waha się od 60 do 90 minut oraz interwał częstotliwości logowania.

Oto przykład działania domyślnej odmiany okresu istnienia tokenu z częstotliwością logowania. Załóżmy, że organizacja ustawia częstotliwość logowania, która ma wystąpić co godzinę. Jeśli token ma okres istnienia od 60 do 90 minut ze względu na odmianę okresu istnienia tokenu, rzeczywisty interwał logowania występuje w dowolnym miejscu od 1 godziny do 2,5 godziny.

Jeśli użytkownik z tokenem z okresem istnienia jednej godziny wykonuje logowanie interakcyjne przy 59 minutach, nie ma monitu o podanie poświadczeń, ponieważ logowanie jest poniżej progu SIF. Jeśli nowy token ma okres istnienia 90 minut, użytkownik nie zobaczy monitu o podanie poświadczeń przez kolejną godzinę i pół roku. Podczas próby odnowienia dyskretnego identyfikator Entra firmy Microsoft wymaga monitu o podanie poświadczeń, ponieważ łączna długość sesji przekroczyła ustawienie częstotliwości logowania wynoszącym 1 godzinę. W tym przykładzie różnica czasu między monitami poświadczeń ze względu na interwał SIF i odmianę okresu istnienia tokenu wynosi 2,5 godziny.

Weryfikowanie tokenów

Nie wszystkie aplikacje powinny weryfikować tokeny. Tylko w określonych scenariuszach aplikacje powinny zweryfikować token:

• Internetowe interfejsy API muszą weryfikować tokeny dostępu wysyłane do nich przez klienta. Muszą akceptować tylko tokeny zawierające jeden z identyfikatorów URI identyfikatorów AppId jako aud oświadczenia.
• Aplikacje internetowe muszą weryfikować tokeny identyfikatorów wysyłane do nich przy użyciu przeglądarki użytkownika w przepływie hybrydowym, zanim umożliwią dostęp do danych użytkownika lub ustanowienia sesji.

Jeśli żaden z opisanych wcześniej scenariuszy nie ma zastosowania, nie ma potrzeby weryfikowania tokenu. Klienci publiczni, tacy jak aplikacje natywne, klasyczne lub jednostronicowe, nie korzystają z weryfikacji tokenów identyfikatorów, ponieważ aplikacja komunikuje się bezpośrednio z dostawcą tożsamości, gdzie ochrona SSL gwarantuje, że tokeny identyfikatorów są prawidłowe. Nie powinny weryfikować tokenów dostępu, ponieważ są one przeznaczone dla internetowego interfejsu API do weryfikacji, a nie klienta.

Interfejsy API i aplikacje internetowe muszą weryfikować tylko tokeny, które mają oświadczenie zgodne z aplikacją aud . Inne zasoby mogą mieć niestandardowe reguły sprawdzania poprawności tokenu. Na przykład nie można zweryfikować tokenów dla programu Microsoft Graph zgodnie z tymi regułami ze względu na ich zastrzeżony format. Weryfikowanie i akceptowanie tokenów przeznaczonych dla innego zasobu jest przykładem zdezorientowanego problemu zastępcy .

Jeśli aplikacja musi zweryfikować token identyfikatora lub token dostępu, najpierw należy zweryfikować podpis tokenu i wystawcę względem wartości w dokumencie odnajdywania OpenID.

Oprogramowanie pośredniczące Microsoft Entra ma wbudowane funkcje sprawdzania poprawności tokenów dostępu, zobacz przykłady , aby znaleźć je w odpowiednim języku. Istnieje również kilka bibliotek open source innych firm dostępnych do weryfikacji JWT. Aby uzyskać więcej informacji na temat bibliotek uwierzytelniania i przykładów kodu, zobacz biblioteki uwierzytelniania. Jeśli aplikacja internetowa lub internetowy interfejs API jest w ASP.NET lub ASP.NET Core, użyj microsoft.Identity.Web, która obsługuje walidację.

Tokeny w wersji 1.0 i 2.0

• Gdy aplikacja internetowa/interfejs API waliduje token w wersji 1.0 (ver oświadczenie ="1.0"), musi odczytać dokument metadanych openID Połączenie z punktu końcowego w wersji 1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), nawet jeśli urząd skonfigurowany dla internetowego interfejsu API jest urzędem w wersji 2.0.
• Gdy aplikacja internetowa/interfejs API waliduje token w wersji 2.0 (ver oświadczenie ="2.0"), musi odczytać dokument metadanych openID Połączenie z punktu końcowego w wersji 2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), nawet jeśli urząd skonfigurowany dla internetowego interfejsu API jest urzędem w wersji 1.0.

W poniższych przykładach przyjęto założenie, że aplikacja waliduje token dostępu w wersji 2.0 (a zatem odwołuje się do wersji 2.0 dokumentów i kluczy metadanych OIDC). Po prostu usuń ciąg "/v2.0" w adresie URL, jeśli zweryfikujesz tokeny w wersji 1.0.

Weryfikowanie wystawcy

OpenID Połączenie Core mówi "Identyfikator wystawcy [...] MUSI dokładnie odpowiadać wartości oświadczenia iss (wystawcy). W przypadku aplikacji, które używają punktu końcowego metadanych specyficznych dla dzierżawy (na przykład https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration lub https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), jest to wszystko, co jest potrzebne.

Identyfikator Entra firmy Microsoft ma niezależną od dzierżawy wersję dokumentu dostępną pod adresem https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Ten punkt końcowy zwraca wartość https://login.microsoftonline.com/{tenantid}/v2.0wystawcy . Aplikacje mogą używać tego niezależnego od dzierżawy punktu końcowego do sprawdzania poprawności tokenów z każdej dzierżawy z następującymi modyfikacjami:

1. Zamiast oczekiwać, że oświadczenie wystawcy w tokenie będzie dokładnie zgodne z wartością wystawcy z metadanych, aplikacja powinna zastąpić {tenantid} wartość w metadanych wystawcy identyfikatorem dzierżawy, który jest elementem docelowym bieżącego żądania, a następnie sprawdzić dokładne dopasowanie.

2. Aplikacja powinna używać issuer właściwości zwróconej z punktu końcowego kluczy, aby ograniczyć zakres kluczy.

   • Klucze, które mają wartość wystawcy, na przykład https://login.microsoftonline.com/{tenantid}/v2.0 mogą być używane z dowolnym zgodnym wystawcą tokenu.
   • Klucze, które mają wartość wystawcy, na przykład https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 powinny być używane tylko z dokładnym dopasowaniem.

   Punkt końcowy klucza niezależnego od dzierżawy firmy Microsoft (https://login.microsoftonline.com/common/discovery/v2.0/keys) zwraca dokument, taki jak:

   {
     "keys":[
       {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
       {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
     ]
   }
   

3. Aplikacje korzystające z oświadczenia entra tenantid (tid) firmy Microsoft jako granicy zaufania zamiast standardowego oświadczenia wystawcy powinny upewnić się, że oświadczenie identyfikatora dzierżawy jest identyfikatorem GUID i że wystawca i identyfikator dzierżawy są zgodne.

Korzystanie z metadanych niezależnych od dzierżawy jest bardziej wydajne w przypadku aplikacji, które akceptują tokeny z wielu dzierżaw.

Uwaga

W przypadku metadanych niezależnych od dzierżawy firmy Microsoft oświadczenia powinny być interpretowane w ramach dzierżawy, podobnie jak w przypadku standardowych Połączenie OpenID oświadczenia są interpretowane w ramach wystawcy. Oznacza to, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} że i {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} opisują różnych użytkowników, mimo że sub są takie same, ponieważ oświadczenia takie jak sub są interpretowane w kontekście wystawcy/dzierżawy.

Weryfikowanie podpisu

Zestaw JWT zawiera trzy segmenty oddzielone znakiem . . Pierwszy segment to nagłówek, drugi to treść, a trzeci to podpis. Użyj segmentu podpisu, aby ocenić autentyczność tokenu.

Identyfikator entra firmy Microsoft wystawia tokeny podpisane przy użyciu standardowych algorytmów szyfrowania asymetrycznego, takich jak RS256. Nagłówek JWT zawiera informacje o kluczu i metodzie szyfrowania używanej do podpisywania tokenu:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

Oświadczenie alg wskazuje algorytm używany do podpisywania tokenu, podczas gdy kid oświadczenie wskazuje określony klucz publiczny, który został użyty do zweryfikowania tokenu.

W dowolnym momencie identyfikator Entra firmy Microsoft może podpisać token identyfikatora przy użyciu jednego z określonych zestawów par kluczy publicznych-prywatnych. Identyfikator entra firmy Microsoft okresowo obraca możliwy zestaw kluczy, dlatego napisz aplikację, aby automatycznie obsłużyć te kluczowe zmiany. Rozsądna częstotliwość sprawdzania dostępności aktualizacji kluczy publicznych używanych przez identyfikator Entra firmy Microsoft jest co 24 godziny.

Uzyskaj dane klucza podpisywania niezbędne do zweryfikowania podpisu przy użyciu dokumentu metadanych Połączenie OpenID znajdującego się w:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Napiwek

Wypróbuj to w przeglądarce: adres URL

Poniższe informacje opisują dokument metadanych:

• Jest obiektem JSON zawierającym kilka przydatnych informacji, takich jak lokalizacja różnych punktów końcowych wymaganych do przeprowadzenia uwierzytelniania Połączenie OpenID.
• Zawiera element jwks_uri, który zapewnia lokalizację zestawu kluczy publicznych odpowiadających kluczom prywatnym używanym do podpisywania tokenów. Klucz internetowy JSON (JWK) znajdujący się w obiekcie jwks_uri zawiera wszystkie informacje o kluczu publicznym używane w danym momencie w danym momencie. RFC 7517 opisuje format JWK. Aplikacja może użyć kid oświadczenia w nagłówku JWT, aby wybrać klucz publiczny z tego dokumentu, który odpowiada kluczowi prywatnemu, który został użyty do podpisania określonego tokenu. Następnie może przeprowadzić walidację podpisu przy użyciu poprawnego klucza publicznego i wskazanego algorytmu.

Uwaga

kid Użyj oświadczenia, aby zweryfikować token. Chociaż tokeny w wersji 1.0 zawierają zarówno oświadczenia, jak x5t i kid , tokeny w wersji 2.0 zawierają tylko kid oświadczenie.

Sprawdzanie poprawności podpisu wykracza poza zakres tego dokumentu. Istnieje wiele bibliotek typu open source, które ułatwiają weryfikację podpisu w razie potrzeby. Jednak Platforma tożsamości Microsoft ma jedno rozszerzenie podpisywania tokenu do standardów, które są niestandardowymi kluczami podpisywania.

Jeśli aplikacja ma niestandardowe klucze podpisywania w wyniku używania funkcji mapowania oświadczeń, dołącz appid parametr zapytania zawierający identyfikator aplikacji. W celu weryfikacji należy użyć tej funkcji jwks_uri do informacji o kluczu podpisywania aplikacji. Na przykład: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 zawiera znak jwks_uri z .https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444

Weryfikowanie wystawcy

Aplikacje internetowe weryfikujące tokeny identyfikatorów i internetowe interfejsy API weryfikujące tokeny dostępu muszą zweryfikować wystawcę tokenu (iss oświadczenia) względem:

1. wystawca dostępny w dokumencie metadanych połączenia OpenID skojarzonym z konfiguracją aplikacji (urząd). Dokument metadanych do zweryfikowania w zależności od:
   • wersja tokenu
   • konta obsługiwane przez aplikację.
2. identyfikator dzierżawy (tid oświadczenie) tokenu,
3. wystawca klucza podpisywania.

Aplikacje z jedną dzierżawą

OpenID Połączenie Core mówi "Identyfikator wystawcy [...] MUSI dokładnie odpowiadać wartości iss oświadczenia (wystawcy). W przypadku aplikacji korzystających z punktu końcowego metadanych specyficznych dla dzierżawy, takiego jak https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration lub https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Aplikacje z jedną dzierżawą to aplikacje, które obsługują:

• Konta w jednym katalogu organizacyjnym (tylko identyfikator dzierżawy ): https://login.microsoftonline.com/{example-tenant-id}
• Tylko osobiste konta Microsoft: https://login.microsoftonline.com/consumers (konsumenci są pseudonimem dzierżawy 9188040d-6c67-4c5b-b112-36a304b66dad)

Aplikacje wielodostępne

Identyfikator Entra firmy Microsoft obsługuje również aplikacje wielodostępne. Te aplikacje obsługują:

• Konta w dowolnym katalogu organizacyjnym (dowolny katalog firmy Microsoft Entra): https://login.microsoftonline.com/organizations
• Konta w dowolnym katalogu organizacyjnym (dowolny katalog Microsoft Entra) i osobiste konta Microsoft (na przykład Skype, XBox): https://login.microsoftonline.com/common

W przypadku tych aplikacji identyfikator Entra firmy Microsoft uwidacznia odpowiednio niezależne od dzierżawy wersje dokumentu https://login.microsoftonline.com/common/v2.0/.well-known/openid-configurationhttps://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration OIDC. Te punkty końcowe zwracają wartość wystawcy, która jest szablonem sparametryzowanym przez element tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Aplikacje mogą używać tych niezależnych od dzierżawy punktów końcowych do sprawdzania poprawności tokenów z każdej dzierżawy przy użyciu następujących instrukcji:

• Weryfikowanie wystawcy klucza podpisywania
• Zamiast oczekiwać, że oświadczenie wystawcy w tokenie będzie dokładnie zgodne z wartością wystawcy z metadanych, aplikacja powinna zastąpić {tenantid} wartość w metadanych wystawcy identyfikatorem dzierżawy, który jest celem bieżącego żądania, a następnie sprawdzić dokładne dopasowanie (tid oświadczenie tokenu).
• Sprawdź, czy tid oświadczenie jest identyfikatorem GUID, a iss oświadczenie ma postać https://login.microsoftonline.com/{tid}/v2.0 , w której {tid} znajduje się dokładne tid oświadczenie. Ta walidacja wiąże dzierżawę z powrotem z wystawcą i z powrotem do zakresu klucza podpisywania tworzącego łańcuch zaufania.
• Użyj tid oświadczenia podczas lokalizowania danych skojarzonych z podmiotem roszczenia. Innymi słowy, tid oświadczenie musi być częścią klucza używanego do uzyskiwania dostępu do danych użytkownika.

Weryfikowanie wystawcy klucza podpisywania

Aplikacje korzystające z metadanych niezależnych od dzierżawy w wersji 2.0 muszą zweryfikować wystawcę klucza podpisywania.

Dokument kluczy i wystawca klucza podpisywania

Zgodnie z opisem w dokumencie OpenID Połączenie aplikacja uzyskuje dostęp do kluczy używanych do podpisywania tokenów. Pobiera odpowiedni dokument kluczy przez uzyskanie dostępu do adresu URL uwidocznionego we właściwości jwks_uri dokumentu OpenId Połączenie.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Wartość {example-tenant-id} można zastąpić identyfikatorem GUID, nazwą domeny lub typowymi organizacjami i użytkownikami

Dokumenty keys udostępniane przez usługę Azure AD w wersji 2.0 zawierają dla każdego klucza wystawcę, który używa tego klucza podpisywania. Na przykład niezależny od dzierżawy "wspólny" punkt końcowy https://login.microsoftonline.com/common/discovery/v2.0/keys klucza zwraca dokument, taki jak:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Walidacja wystawcy klucza podpisywania

Aplikacja powinna używać issuer właściwości dokumentu klucze skojarzonej z kluczem używanym do podpisywania tokenu, aby ograniczyć zakres kluczy:

• Klucze, które mają wartość wystawcy z identyfikatorem GUID, powinny https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 być używane tylko wtedy, gdy iss oświadczenie w tokenie pasuje dokładnie do wartości.
• Klucze, które mają wartość wystawcy szablonu, https://login.microsoftonline.com/{tenantid}/v2.0 powinny być używane tylko wtedy, gdy iss oświadczenie w tokenie pasuje do tej wartości po podstawieniu tid oświadczenia w tokenie dla symbolu zastępczego {tenantid} .

Korzystanie z metadanych niezależnych od dzierżawy jest bardziej wydajne w przypadku aplikacji, które akceptują tokeny z wielu dzierżaw.

Uwaga

W przypadku metadanych niezależnych od dzierżawy firmy Microsoft oświadczenia powinny być interpretowane w ramach dzierżawy, podobnie jak w przypadku standardowych Połączenie OpenID oświadczenia są interpretowane w ramach wystawcy. Oznacza to, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} że i {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} opisują różnych użytkowników, mimo że sub są takie same, ponieważ oświadczenia takie jak sub są interpretowane w kontekście wystawcy/dzierżawy.

Podsumowanie

Oto przykładowy kod, który reapituje sposób weryfikowania wystawcy i wystawcy klucza podpisywania:

1. Pobieranie kluczy ze skonfigurowanego adresu URL metadanych
2. Sprawdź token, jeśli został podpisany przy użyciu jednego z opublikowanych kluczy, nie powiedzie się, jeśli nie
3. Zidentyfikuj klucz w metadanych na podstawie nagłówka dziecka. Sprawdź właściwość "wystawca" dołączoną do klucza w dokumencie metadanych:

   var issuer = metadata["kid"].issuer;
   if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
   if (issuer != token["iss"]) throw validationException;
   if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
   var issUri = new Uri(token["iss"]);
   if (issUri.Segments.Count < 1) throw validationException;
   if (issUri.Segments[1] != token["tid"]) throw validationException;
   

Zobacz też

• Dokumentacja oświadczeń tokenu dostępu
• Zabezpieczanie aplikacji i interfejsów API przez weryfikowanie oświadczeń

Następne kroki

• Dowiedz się więcej o tokenach zabezpieczających używanych w identyfikatorze Entra firmy Microsoft.