Udostępnij za pośrednictwem

Dokumentacja oświadczeń tokenu dostępu

  • Artykuł

Tokeny dostępu to tokeny internetowe JSON (JWT). JWTs zawierają następujące elementy:

  • Nagłówek — zawiera informacje o sprawdzaniu poprawności tokenu, w tym informacje o typie tokenu i jego metodzie podpisywania.
  • Payload — zawiera wszystkie ważne dane dotyczące użytkownika lub aplikacji próbującej wywołać usługę.
  • Signature — czy surowiec używany do weryfikacji tokenu.

Każdy element jest oddzielony kropką (.) i oddzielnie zakodowaną w formacie Base 64.

Oświadczenia są obecne tylko wtedy, gdy istnieje wartość, aby ją wypełnić. Aplikacja nie powinna mieć zależności od obecnego oświadczenia. Przykłady obejmują pwd_exp (nie każda dzierżawa wymaga wygaśnięcia haseł) i family_name (przepływy poświadczeń klienta są w imieniu aplikacji, które nie mają nazw). Token dostępu zawsze będzie zawierać wystarczające oświadczenia do oceny dostępu.

Platforma tożsamości Microsoft używa niektórych oświadczeń, aby ułatwić zabezpieczanie tokenów do ponownego użycia. Opis oznacza Opaque te oświadczenia jako niewymagane do użytku publicznego. Te oświadczenia mogą lub nie są wyświetlane w tokenie, a nowe mogą zostać dodane bez powiadomienia.

Oświadczenia nagłówka

Oświadczenie Format opis
typ Ciąg — zawsze JWT Wskazuje, że token jest JWT.
alg String Wskazuje algorytm używany do podpisywania tokenu, na przykład RS256.
kid String Określa odcisk palca klucza publicznego używanego do sprawdzania poprawności podpisu tokenu. Emitowane w tokenach dostępu w wersji 1.0 i 2.0.
x5t String Funkcje takie same (w użyciu i wartości) co kid. x5t i jest starszym oświadczeniem emitowane tylko w tokenach dostępu w wersji 1.0 na potrzeby zgodności.

Oświadczenia ładunku

Oświadczenie Format opis Zagadnienia dotyczące autoryzacji
acrs Tablica ciągów w formacie JSON Wskazuje identyfikatory kontekstu uwierzytelniania operacji, które obiekt nośny kwalifikuje się do wykonania. Identyfikatory kontekstu uwierzytelniania mogą służyć do wyzwalania zapotrzebowania na uwierzytelnianie krokowe z poziomu aplikacji i usług. Często używane wraz z oświadczeniem xms_cc .
aud Ciąg, identyfikator URI identyfikatora aplikacji lub identyfikator GUID Identyfikuje zamierzonych odbiorców tokenu. W tokenach w wersji 2.0 ta wartość jest zawsze identyfikatorem klienta interfejsu API. W tokenach w wersji 1.0 może to być identyfikator klienta lub identyfikator URI zasobu używany w żądaniu. Wartość może zależeć od tego, jak klient zażądał tokenu. Ta wartość musi zostać zweryfikowana, odrzucić token, jeśli wartość nie jest zgodna z zamierzonymi odbiorcami.
iss Ciąg, identyfikator URI usługi tokenu zabezpieczającego (STS) Identyfikuje usługę STS, która konstruuje i zwraca token, oraz dzierżawę firmy Microsoft uwierzytelnionego użytkownika. Jeśli wystawiony token jest tokenem w wersji 2.0 (zobacz ver oświadczenie), identyfikator URI kończy się na ./v2.0 Identyfikator GUID wskazujący, że użytkownik jest użytkownikiem konsumenckim z konta Microsoft, to 9188040d-6c67-4c5b-b112-36a304b66dad. Aplikacja może używać części identyfikatora GUID oświadczenia, aby ograniczyć zestaw dzierżaw, które mogą logować się do aplikacji, jeśli ma to zastosowanie.
idp Ciąg, zazwyczaj identyfikator URI usługi STS Rejestruje dostawcę tożsamości, który uwierzytelnił podmiot tokenu. Ta wartość jest identyczna z wartością oświadczenia wystawcy, chyba że konto użytkownika nie znajduje się w tej samej dzierżawie co wystawca, takich jak goście. Użyj wartości iss , jeśli oświadczenie nie jest obecne. W przypadku kont osobistych używanych w kontekście organizacji (na przykład konta osobistego zaproszonego do dzierżawy firmy Microsoft Entra) idp oświadczenie może mieć wartość "live.com" lub identyfikator URI usługi STS zawierający dzierżawę 9188040d-6c67-4c5b-b112-36a304b66dadkonta Microsoft.
iat int, sygnatura czasowa systemu Unix Określa, kiedy wystąpiło uwierzytelnianie dla tego tokenu.
nbf int, sygnatura czasowa systemu Unix Określa czas, po którym można przetworzyć JWT.
exp int, sygnatura czasowa systemu Unix Określa czas wygaśnięcia, przed którym można zaakceptować JWT do przetwarzania. Zasób może również odrzucić token przed tym razem. Odrzucenie może wystąpić w przypadku wymaganej zmiany uwierzytelniania lub odwołania tokenu.
aio Nieprzezroczystym ciągiem Wewnętrzne oświadczenie używane przez identyfikator Entra firmy Microsoft do rejestrowania danych na potrzeby ponownego użycia tokenu. Zasoby nie powinny używać tego oświadczenia.
acr Ciąg, a 0 lub 1, obecny tylko w tokenach w wersji 1.0 Wartość 0 oświadczenia "Klasa kontekstu uwierzytelniania" wskazuje, że uwierzytelnianie użytkownika końcowego nie spełnia wymagań ISO/IEC 29115.
amr Tablica ciągów JSON, obecna tylko w tokenach w wersji 1.0 Identyfikuje metodę uwierzytelniania podmiotu tokenu.
appid Ciąg, identyfikator GUID, obecny tylko w tokenach w wersji 1.0 Identyfikator aplikacji klienta przy użyciu tokenu. Aplikacja może działać jako sama lub w imieniu użytkownika. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt jednostki usługi w identyfikatorze Entra firmy Microsoft. appid może być używany w decyzjach dotyczących autoryzacji.
azp Ciąg, identyfikator GUID, obecny tylko w tokenach w wersji 2.0 Zamiana elementu .appid Identyfikator aplikacji klienta przy użyciu tokenu. Aplikacja może działać jako sama lub w imieniu użytkownika. Identyfikator aplikacji zazwyczaj reprezentuje obiekt aplikacji, ale może również reprezentować obiekt jednostki usługi w identyfikatorze Entra firmy Microsoft. azp może być używany w decyzjach dotyczących autoryzacji.
appidacr Ciąg, , 01lub 2, obecny tylko w tokenach w wersji 1.0 Wskazuje metodę uwierzytelniania klienta. W przypadku klienta publicznego wartość to 0. Jeśli używasz identyfikatora klienta i klucza tajnego klienta, wartość to 1. Jeśli używasz certyfikatu klienta do uwierzytelniania, wartość to 2.
azpacr Ciąg, , 01lub 2, obecny tylko w tokenach w wersji 2.0 Zamiana elementu .appidacr Wskazuje metodę uwierzytelniania klienta. W przypadku klienta publicznego wartość to 0. Jeśli używasz identyfikatora klienta i klucza tajnego klienta, wartość to 1. Jeśli używasz certyfikatu klienta do uwierzytelniania, wartość to 2.
preferred_username Ciąg, obecny tylko w tokenach w wersji 2.0. Podstawowa nazwa użytkownika reprezentująca użytkownika. Wartość może być adresem e-mail, numerem telefonu lub ogólną nazwą użytkownika bez określonego formatu. Użyj wartości wskazówek dotyczących nazwy użytkownika i interfejsu użytkownika czytelnego dla człowieka jako nazwy użytkownika. Aby otrzymać to oświadczenie, użyj profile zakresu. Ponieważ ta wartość jest modyfikowalna, nie używaj jej do podejmowania decyzji dotyczących autoryzacji.
name String Udostępnia czytelną dla człowieka wartość, która identyfikuje temat tokenu. Wartość może się różnić, jest modyfikowalna i służy tylko do wyświetlania. Aby otrzymać to oświadczenie, użyj profile zakresu. Nie używaj tej wartości do podejmowania decyzji dotyczących autoryzacji.
scp Ciąg, spacja rozdzielona listą zakresów Zestaw zakresów uwidocznionych przez aplikację, dla której aplikacja kliencka zażądała (i odebrała) zgody. Uwzględniane tylko w przypadku tokenów użytkowników. Aplikacja powinna sprawdzić, czy te zakresy są prawidłowe, które są uwidocznione przez aplikację, i podejmować decyzje dotyczące autoryzacji na podstawie wartości tych zakresów.
roles Tablica ciągów, lista uprawnień Zestaw uprawnień uwidocznionych przez aplikację, do którego udzielono żądającej aplikacji lub użytkownika uprawnienia do wywołania. Przepływ poświadczeń klienta używa tego zestawu uprawnień zamiast zakresów użytkownika dla tokenów aplikacji. W przypadku tokenów użytkownika ten zestaw wartości zawiera przypisane role użytkownika w aplikacji docelowej. Te wartości mogą służyć do zarządzania dostępem, na przykład wymuszania autoryzacji w celu uzyskania dostępu do zasobu.
wids Tablica identyfikatorów GUID roleTemplateID Określa role całej dzierżawy przypisane do tego użytkownika z sekcji ról znajdujących się we wbudowanych rolach firmy Microsoft Entra. Właściwość groupMembershipClaims manifestu aplikacji konfiguruje to oświadczenie dla poszczególnych aplikacji. Ustaw oświadczenie na All lub DirectoryRole. Te wartości mogą służyć do zarządzania dostępem, na przykład wymuszania autoryzacji w celu uzyskania dostępu do zasobu.
groups Tablica JSON identyfikatorów GUID Udostępnia identyfikatory obiektów reprezentujące członkostwo w grupie podmiotu. Właściwość groupMembershipClaims manifestu aplikacji konfiguruje oświadczenia grup dla poszczególnych aplikacji. Wartość null wyklucza wszystkie grupy, wartość SecurityGroup obejmuje role katalogu i członkostwa w grupach zabezpieczeń usługi Active Directory, a wartość All obejmuje zarówno grupy zabezpieczeń, jak i listy dystrybucyjne platformy Microsoft 365. W przypadku innych przepływów, jeśli liczba grup, w których znajduje się użytkownik, przekroczy 150 dla protokołu SAML i 200 dla JWT, identyfikator Entra firmy Microsoft dodaje oświadczenie nadwyżkowe do źródeł oświadczeń. Źródła oświadczeń wskazują punkt końcowy usługi Microsoft Graph, który zawiera listę grup dla użytkownika. Te wartości mogą służyć do zarządzania dostępem, na przykład wymuszania autoryzacji w celu uzyskania dostępu do zasobu.
hasgroups Wartość logiczna Jeśli istnieje, zawsze true, wskazuje, czy użytkownik znajduje się w co najmniej jednej grupie. Wskazuje, że klient powinien używać interfejsu API programu Microsoft Graph do określania grup (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) użytkownika.
groups:src1 Obiekt JSON Zawiera link do pełnej listy grup dla użytkownika, gdy żądania tokenu są zbyt duże dla tokenu. W przypadku zestawów JWTs jako oświadczenia rozproszonego w przypadku protokołu SAML jako nowego oświadczenia zamiast groups oświadczenia.

Przykładowa wartość JWT:
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub String Podmiot zabezpieczeń skojarzony z tokenem. Na przykład użytkownik aplikacji. Ta wartość jest niezmienna, nie przypisz ponownie ani nie używaj jej ponownie. Temat jest identyfikatorem parowania unikatowym dla określonego identyfikatora aplikacji. Jeśli jeden użytkownik zaloguje się do dwóch różnych aplikacji przy użyciu dwóch różnych identyfikatorów klientów, te aplikacje otrzymają dwie różne wartości oświadczenia podmiotu. Użycie dwóch różnych wartości zależy od wymagań dotyczących architektury i prywatności. Zobacz również oid oświadczenie, które pozostaje takie same w aplikacjach w ramach dzierżawy. Ta wartość może służyć do przeprowadzania kontroli autoryzacji, takich jak użycie tokenu w celu uzyskania dostępu do zasobu i może służyć jako klucz w tabelach bazy danych.
oid Ciąg, identyfikator GUID Niezmienny identyfikator osoby żądającej, która jest zweryfikowaną tożsamością użytkownika lub jednostki usługi. Ten identyfikator jednoznacznie identyfikuje osoby żądającej w aplikacjach. Dwie różne aplikacje logując się w tym samym użytkowniku otrzymują tę samą wartość w oświadczeniu oid . Można oid ich używać podczas wykonywania zapytań do Usługi online firmy Microsoft, takich jak Microsoft Graph. Program Microsoft Graph zwraca ten identyfikator jako id właściwość dla danego konta użytkownika. Ze względu na to oid , że aplikacja zezwala wielu aplikacjom na korelowanie podmiotów zabezpieczeń, odbieranie tego oświadczenia dla użytkowników używa profile zakresu. Jeśli jeden użytkownik istnieje w wielu dzierżawach, użytkownik zawiera inny identyfikator obiektu w każdej dzierżawie. Mimo że użytkownik loguje się do każdego konta przy użyciu tych samych poświadczeń, konta są różne. Ta wartość może służyć do przeprowadzania kontroli autoryzacji, takich jak użycie tokenu w celu uzyskania dostępu do zasobu i może służyć jako klucz w tabelach bazy danych.
tid Ciąg, identyfikator GUID Reprezentuje dzierżawę, do której loguje się użytkownik. W przypadku kont służbowych identyfikator GUID jest niezmiennym identyfikatorem dzierżawy organizacji, do której loguje się użytkownik. W przypadku logowania się do osobistej dzierżawy konta Microsoft (usług takich jak Xbox, Teams for Life lub Outlook) wartość to 9188040d-6c67-4c5b-b112-36a304b66dad. Aby otrzymać to oświadczenie, aplikacja musi zażądać profile zakresu. Ta wartość powinna być brana pod uwagę w połączeniu z innymi oświadczeniami w decyzjach dotyczących autoryzacji.
unique_name Ciąg, obecny tylko w tokenach w wersji 1.0 Udostępnia zrozumiałą wartość identyfikującą podmiot tokenu. Ta wartość może być inna w ramach dzierżawy i używać jej tylko do celów wyświetlania.
uti String Oświadczenie identyfikatora tokenu, równoważne jti w specyfikacji JWT. Unikatowy identyfikator dla tokenu, który jest uwzględniany w wielkości liter.
rh Nieprzezroczystym ciągiem Wewnętrzne oświadczenie używane przez platformę Azure do ponownego stosowania tokenów. Zasoby nie powinny używać tego oświadczenia.
ver Ciąg, albo 1.0 lub 2.0 Wskazuje wersję tokenu dostępu.
xms_cc Tablica ciągów w formacie JSON Wskazuje, czy aplikacja kliencka, która uzyskała token, jest w stanie sprostać wyzwaniom związanym z oświadczeniami. Jest on często używany wraz z oświadczeniem acrs. To oświadczenie jest często używane w scenariuszach dostępu warunkowego i oceny dostępu ciągłego. Serwer zasobów lub aplikacja usługi wystawiona dla tokenu kontroluje obecność tego oświadczenia w tokenie. Wartość cp1 w tokenie dostępu to autorytatywny sposób identyfikowania, że aplikacja kliencka może obsługiwać wyzwanie dotyczące oświadczeń. Aby uzyskać więcej informacji, zobacz Wyzwania dotyczące oświadczeń, żądania oświadczeń i możliwości klienta.

Uwaga

Oświadczenia roles, groups, scpi wids nie są wyczerpującą listą tego, jak zasób może autoryzować użytkownika lub aplikację, ani nie są wyczerpującą listą uprawnień przyznanych wywołującym. Zasób docelowy może użyć innej metody, aby autoryzować dostęp do chronionych zasobów.

Oświadczenie dotyczące nadwyżki grup

Identyfikator Entra firmy Microsoft ogranicza liczbę identyfikatorów obiektów uwzględnionych w oświadczeniach grup, aby pozostać w limicie rozmiaru nagłówka HTTP. Jeśli użytkownik jest członkiem większej liczby grup niż limit nadwyżkowy (150 dla tokenów SAML, 200 dla tokenów JWT), identyfikator Microsoft Entra nie emituje oświadczenia grup w tokenie. Zamiast tego zawiera oświadczenie nadwyżkowe w tokenie, które wskazuje aplikacji na wykonywanie zapytań względem interfejsu API programu Microsoft Graph w celu pobrania członkostwa w grupie użytkownika.

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

Użyj udostępnionego BulkCreateGroups.ps1 w folderze Skrypty tworzenia aplikacji, aby ułatwić testowanie scenariuszy nadwyżkowych.

Uwaga

Zwrócony adres URL będzie adresem URL programu Azure AD Graph (czyli graph.windows.net). Zamiast polegać na tym adresie URL, usługi powinny zamiast tego używać opcjonalnego idtyp oświadczenia (który określa, czy token jest aplikacją, czy aplikacją i tokenem użytkownika) w celu utworzenia adresu URL programu Microsoft Graph na potrzeby wykonywania zapytań dotyczących pełnej listy grup.

Podstawowe oświadczenia w wersji 1.0

Tokeny w wersji 1.0 obejmują następujące oświadczenia, jeśli ma to zastosowanie, ale nie tokeny w wersji 2.0 domyślnie. Aby użyć tych oświadczeń dla wersji 2.0, aplikacja żąda ich przy użyciu opcjonalnych oświadczeń.

Oświadczenie Format opis
ipaddr String Adres IP uwierzytelniony przez użytkownika.
onprem_sid Ciąg w formacie SID W przypadkach, gdy użytkownik ma uwierzytelnianie lokalne, to oświadczenie zapewnia identyfikator SID. Użyj tego oświadczenia do autoryzacji w starszych aplikacjach.
pwd_exp int, sygnatura czasowa systemu Unix Wskazuje, kiedy hasło użytkownika wygasa.
pwd_url String Adres URL, pod którym użytkownicy mogą zresetować swoje hasło.
in_corp boolean Sygnały, czy klient loguje się z sieci firmowej.
nickname String Inna nazwa użytkownika, oddzielona od imienia lub nazwiska.
family_name String Podaje nazwisko, nazwisko lub nazwę rodziny użytkownika zgodnie z definicją w obiekcie użytkownika.
given_name String Zawiera pierwszą lub podaną nazwę użytkownika ustawioną na obiekcie użytkownika.
upn String Nazwa użytkownika. Może to być numer telefonu, adres e-mail lub niesformatowany ciąg. Służy tylko do celów wyświetlania i podawania wskazówek dotyczących nazwy użytkownika w scenariuszach ponownego uwierzytelniania.

amr claim

Tożsamości mogą być uwierzytelniane na różne sposoby, co może być istotne dla aplikacji. Oświadczenie amr jest tablicą, która może zawierać wiele elementów, takich jak , na potrzeby uwierzytelniania, które używało zarówno hasła, jak ["mfa", "rsa", "pwd"]i aplikacji Authenticator.

Wartość Opis
pwd Uwierzytelnianie hasłem — hasłem firmy Microsoft użytkownika lub wpisem tajnym klienta aplikacji.
rsa Uwierzytelnianie zostało oparte na weryfikacji klucza RSA, na przykład w aplikacji Microsoft Authenticator. Ta wartość wskazuje również użycie certyfikatu JWT z podpisem własnym z certyfikatem X509 należącym do usługi w uwierzytelnianiu.
otp Jednorazowy kod dostępu przy użyciu wiadomości e-mail lub wiadomości SMS.
fed Wskazuje użycie asercji uwierzytelniania federacyjnego (na przykład JWT lub SAML).
wia Zintegrowane uwierzytelnianie systemu Windows
mfa Wskazuje użycie uwierzytelniania wieloskładnikowego. Zawiera inne metody uwierzytelniania, gdy to oświadczenie jest obecne.
ngcmfa mfaOdpowiednik elementu , używany do aprowizacji niektórych zaawansowanych typów poświadczeń.
wiaormfa Użytkownik użył systemu Windows lub poświadczeń uwierzytelniania wieloskładnikowego.
none Wskazuje brak ukończonego uwierzytelniania.

Następne kroki