Platforma tożsamości Microsoft poświadczenia certyfikatu uwierzytelniania aplikacji

Artykuł
04/10/2024

Platforma tożsamości Microsoft umożliwia aplikacji używanie własnych poświadczeń do uwierzytelniania w dowolnym miejscu, w których można użyć wpisu tajnego klienta, na przykład w przepływie udzielania poświadczeń klienta OAuth 2.0 oraz przepływie OBO (on-behalf-of).

Jedną z form poświadczeń, których aplikacja może używać do uwierzytelniania, jest asercji JSON Web Token (JWT) podpisanej przy użyciu certyfikatu, który jest właścicielem aplikacji. Opisano to w specyfikacji openID Połączenie dla private_key_jwt opcji uwierzytelniania klienta.

Jeśli interesuje Cię użycie zestawu JWT wystawionego przez innego dostawcę tożsamości jako poświadczenia dla aplikacji, zobacz federację tożsamości obciążenia, aby dowiedzieć się, jak skonfigurować zasady federacyjne.

Format asercji

Aby obliczyć asercję, możesz użyć jednej z wielu bibliotek JWT w wybranym języku — biblioteka MSAL obsługuje tę funkcję przy użyciu polecenia .WithCertificate(). Informacje są przenoszone przez token w nagłówku, oświadczeniach i podpisie.

Parametr	Uwaga
`alg`	Powinien mieć wartość RS256
`typ`	Powinna być JWT
`x5t`	Odcisk palca SHA-1 zakodowany w formacie Base64url kodowania DER certyfikatu X.509. Na przykład, biorąc pod uwagę skrót certyfikatu `AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00` X.509 (Szesnastkowy), `x5t` oświadczenie będzie miało wartość `hOBcHZi846VCHSJbFAs26Go9VTQ` (Base64url).

Oświadczenia (ładunek)

Typ oświadczenia	Wartość	Opis
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	Oświadczenie "aud" (odbiorcy) identyfikuje adresatów, dla których jest przeznaczona aplikacja JWT (tutaj identyfikator Microsoft Entra) Zobacz RFC 7519, Sekcja 4.1.3. W takim przypadku adresatem jest serwer logowania (login.microsoftonline.com).
`exp`	1601519414	Oświadczenie "exp" (czas wygaśnięcia) identyfikuje czas wygaśnięcia w dniu lub po upływie którego nie można zaakceptować JWT do przetwarzania. Zobacz RFC 7519, sekcja 4.1.4. Pozwala to na użycie potwierdzenia do tego czasu, więc zachowaj krótki - 5-10 minut po `nbf` najwyżej. Identyfikator Entra firmy Microsoft nie nakłada obecnie ograniczeń dotyczących `exp` czasu.
`iss`	{ClientID}	Oświadczenie "iss" (wystawca) identyfikuje podmiot zabezpieczeń, który wystawił JWT. W tym przypadku aplikacja kliencka. Użyj identyfikatora aplikacji GUID.
`jti`	(identyfikator GUID)	Oświadczenie "jti" (JWT ID) zawiera unikatowy identyfikator JWT. Wartość identyfikatora musi być przypisana w sposób, który gwarantuje, że istnieje niewielkie prawdopodobieństwo, że ta sama wartość zostanie przypadkowo przypisana do innego obiektu danych. Jeśli aplikacja używa wielu wystawców, kolizje muszą być blokowane między wartościami generowanymi przez różnych wystawców. Wartość "jti" jest ciągiem z uwzględnieniem wielkości liter. RFC 7519, sekcja 4.1.7
`nbf`	1601519114	Oświadczenie "nbf" (nie wcześniej) identyfikuje czas, przed którym JWT NIE MOŻE zostać zaakceptowany do przetwarzania. RFC 7519, sekcja 4.1.5. Użycie bieżącej godziny jest odpowiednie.
`sub`	{ClientID}	Oświadczenie "sub" (podmiot) identyfikuje podmiot JWT, w tym przypadku również aplikację. Użyj tej samej wartości co `iss`.
`iat`	1601519114	Oświadczenie "iat" (wydane pod adresem) identyfikuje czas wydania JWT. To oświadczenie może służyć do określenia wieku JWT. RFC 7519, sekcja 4.1.5.

Podpis

Podpis jest obliczany przez zastosowanie certyfikatu zgodnie z opisem w specyfikacji RFC7519 tokenu internetowego JSON.

Przykład zdekodowanej asercji JWT

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Przykład zakodowanej asercji JWT

Poniższy ciąg jest przykładem zakodowanej asercji. Jeśli przyjrzysz się uważnie, zauważysz trzy sekcje oddzielone kropkami (.):

Pierwsza sekcja koduje nagłówek
Druga sekcja koduje oświadczenia (ładunek)
Ostatnia sekcja to podpis obliczony przy użyciu certyfikatów z zawartości dwóch pierwszych sekcji

"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Rejestrowanie certyfikatu przy użyciu Platforma tożsamości Microsoft

Poświadczenie certyfikatu można skojarzyć z aplikacją klienczą w Platforma tożsamości Microsoft za pośrednictwem centrum administracyjnego firmy Microsoft Entra przy użyciu dowolnej z następujących metod:

Przekazywanie pliku certyfikatu

Na karcie Rejestracje aplikacji aplikacji klienckiej:

Wybierz pozycję Certyfikaty i wpisy tajne Certyfikaty>.
Wybierz pozycję Przekaż certyfikat i wybierz plik certyfikatu do przekazania.
Wybierz Dodaj. Po przekazaniu certyfikatu zostaną wyświetlone wartości odcisku palca, daty rozpoczęcia i wygaśnięcia.

Aktualizowanie manifestu aplikacji

Po uzyskaniu certyfikatu oblicz następujące wartości:

$base64Thumbprint - Wartość zakodowana w formacie Base64 skrótu certyfikatu
$base64Value - Wartość zakodowana w formacie Base64 nieprzetworzonych danych certyfikatu

Podaj identyfikator GUID, aby zidentyfikować klucz w manifeście aplikacji ($keyId).

W rejestracji aplikacji platformy Azure dla aplikacji klienckiej:

Wybierz pozycję Manifest, aby otworzyć manifest aplikacji.

Zastąp właściwość keyCredentials nowymi informacjami o certyfikacie przy użyciu następującego schematu.

"keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

Zapisz zmiany w manifeście aplikacji, a następnie przekaż manifest do Platforma tożsamości Microsoft.

Właściwość keyCredentials jest wielowartośćowa, więc można przekazać wiele certyfikatów na potrzeby bogatszego zarządzania kluczami.

Używanie asercji klienta

Asercji klientów można używać w dowolnym miejscu, w których będzie używany klucz tajny klienta. Na przykład w przepływie kodu autoryzacji możesz przekazać element , client_secret aby udowodnić, że żądanie pochodzi z aplikacji. Możesz zastąpić to parametrami client_assertion i .client_assertion_type

Parametr	Wartość	Opis
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Jest to stała wartość wskazująca, że używasz poświadczeń certyfikatu.
`client_assertion`	`JWT`	Jest to utworzony powyżej zestaw JWT.

Następne kroki

Biblioteka MSAL.NET obsługuje ten scenariusz w jednym wierszu kodu.

Aplikacja konsolowa demona platformy .NET korzystająca z przykładu kodu Platforma tożsamości Microsoft w witrynie GitHub pokazuje, jak aplikacja używa własnych poświadczeń do uwierzytelniania. Przedstawiono również sposób tworzenia certyfikatu z podpisem własnym przy użyciu New-SelfSignedCertificate polecenia cmdlet programu PowerShell. Możesz również użyć skryptów tworzenia aplikacji w przykładowym repozytorium, aby utworzyć certyfikaty, obliczyć odcisk palca itd.

Share via