Přihlašovací údaje ověřovacího certifikátu aplikace Microsoft Identity Platform

Článek
10/25/2024

Platforma Microsoft Identity Platform umožňuje aplikaci používat vlastní přihlašovací údaje pro ověřování všude, kde se dá použít tajný klíč klienta, například v toku udělení přihlašovacích údajů klienta OAuth 2.0 a toku on-behalf-of (OBO).

Jednou z forem přihlašovacích údajů, které může aplikace použít k ověřování, je kontrolní výraz JSON Web Token (JWT) podepsaný certifikátem, který aplikace vlastní. Toto je popsáno ve specifikaci OpenID Connect pro private_key_jwt možnost ověřování klienta.

Pokud vás zajímá použití JWT vydaného jiným zprostředkovatelem identity jako přihlašovacích údajů pro vaši aplikaci, přečtěte si prosím federaci identit úloh, kde zjistíte, jak nastavit zásady federace.

Formát kontrolního výrazu

K výpočtu kontrolního výrazu můžete použít jednu z mnoha knihoven JWT v jazyce podle vašeho výběru – MSAL to podporuje ..WithCertificate() Informace se přenášejí tokenem v hlavičce, deklarací identity a podpisu.

Parametr	Poznámka
`alg`	Měl by být PS256
`typ`	Mělo by to být JWT.
`x5t#s256`	Kryptografický otisk SHA-256 s kódováním DER certifikátu X.509 s kódováním BASE64url.

Deklarace identity (datová část)

Typ deklarace identity	Hodnota	Popis
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	Deklarace identity "aud" (cílová skupina) identifikuje příjemce, pro které je JWT určen (zde Microsoft Entra ID) viz RFC 7519, oddíl 4.1.3. V tomto případě je příjemcem přihlašovací server (`login.microsoftonline.com`).
`exp`	1601519414	Deklarace "exp" (čas vypršení platnosti) identifikuje dobu vypršení platnosti, po které nesmí být JWT přijata ke zpracování. Viz RFC 7519 oddíl 4.1.4. To umožňuje použití kontrolního výrazu do té doby, takže ponechte krátký - 5-10 minut po `nbf` maximálně. Microsoft Entra ID neuvádí omezení `exp` času v současné době.
`iss`	{ClientID}	Deklarace identity iss (issuer) identifikuje objekt zabezpečení, který vydal JWT, v tomto případě vaši klientskou aplikaci. Použijte ID aplikace GUID.
`jti`	(a Guid)	Deklarace identity jti (JWT ID) poskytuje jedinečný identifikátor JWT. Hodnota identifikátoru musí být přiřazena způsobem, který zajistí, že existuje zanedbatelná pravděpodobnost, že stejná hodnota bude omylem přiřazena jinému datovému objektu. Pokud aplikace používá více vystavitelů, je nutné zabránit kolizím mezi hodnotami vytvořenými různými vystaviteli. Hodnota "jti" je řetězec rozlišující velká a malá písmena. RFC 7519, oddíl 4.1.7
`nbf`	1601519114	Žádost "nbf" (nikoli dříve) identifikuje dobu, před kterou nesmí být JWT přijat ke zpracování. RFC 7519, oddíl 4.1.5. Použití aktuálního času je vhodné.
`sub`	{ClientID}	Žádost "sub" (subject) identifikuje předmět JWT, v tomto případě také vaši aplikaci. Použijte stejnou hodnotu jako `iss`.
`iat`	1601519114	Deklarace identity "iat" (vystavená na) identifikuje čas vydání JWT. Tuto deklaraci identity lze použít k určení věku JWT. RFC 7519, oddíl 4.1.5.

Podpis

Podpis se vypočítá použitím certifikátu, jak je popsáno ve specifikaci webového tokenu JSON RFC7519. Používejte odsazení PSS.

Příklad dekódovaného kontrolního výrazu JWT

{
  "alg": "PS256",
  "typ": "JWT",
  "x5t#sha256": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
}
.
{
  "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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Příklad zakódovaného kontrolního výrazu JWT

Následující řetězec je příkladem zakódovaného kontrolního výrazu. Pokud budete pečlivě vypadat, všimněte si tří oddílů oddělených tečkami (.):

První oddíl zakóduje hlavičku .
Druhá část kóduje deklarace identity (datovou část).
Poslední oddíl je podpis vypočítaný certifikáty z obsahu prvních dvou částí.

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

Registrace certifikátu na platformě Microsoft Identity Platform

Přihlašovací údaje certifikátu můžete přidružit ke klientské aplikaci na platformě Microsoft Identity Platform prostřednictvím Centra pro správu Microsoft Entra pomocí některé z následujících metod:

Nahrání souboru certifikátu

Na kartě Registrace aplikací klientské aplikace:

Vyberte Certifikáty a tajné>certifikáty.
Vyberte nahrání certifikátu a vyberte soubor certifikátu, který chcete nahrát.
Vyberte Přidat. Po nahrání certifikátu se zobrazí kryptografický otisk, počáteční datum a hodnoty vypršení platnosti.

Aktualizace manifestu aplikace

Po získání certifikátu vypočítáte tyto hodnoty:

$base64Thumbprint – Hodnota hash certifikátu s kódováním Base64
$base64Value – Hodnota zakódovaná podle base64 nezpracovaných dat certifikátu

Zadejte identifikátor GUID pro identifikaci klíče v manifestu aplikace ($keyId).

V registraci aplikace Azure pro klientskou aplikaci:

Výběrem možnosti Manifest otevřete manifest aplikace.

Nahraďte vlastnost keyCredentials informacemi o novém certifikátu pomocí následujícího schématu.

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

Uložte úpravy do manifestu aplikace a pak nahrajte manifest do platformy Microsoft Identity Platform.

Vlastnost keyCredentials je vícehodnotová, takže můžete nahrát více certifikátů pro bohatší správu klíčů.

Použití klientského kontrolního výrazu

Klientské kontrolní výrazy lze použít všude, kde by se použil tajný klíč klienta. Například v toku autorizačního kódu můžete předat client_secret důkaz, že požadavek pochází z vaší aplikace. Můžete ho client_assertion nahradit parametry.client_assertion_type

Parametr	Hodnota	Popis
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Jedná se o pevnou hodnotu, která označuje, že používáte přihlašovací údaje certifikátu.
`client_assertion`	`JWT`	Toto je JWT vytvořené výše.

Další kroky

Knihovna MSAL.NET tento scénář zpracovává v jednom řádku kódu.

Konzolová aplikace démona .NET využívající vzorový kód platformy Microsoft Identity Platform na GitHubu ukazuje, jak aplikace používá k ověřování své vlastní přihlašovací údaje. Ukazuje také, jak můžete vytvořit certifikát podepsaný svým držitelem pomocí rutiny PowerShellu New-SelfSignedCertificate . Pomocí skriptů pro vytváření aplikací v ukázkovém úložišti můžete také vytvářet certifikáty , vypočítat kryptografický otisk atd.

Sdílet prostřednictvím