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

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 Připojení 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ělo by to být RS256
typ Mělo by to být JWT.
x5t Kryptografický otisk SHA-1 kódování SHA-1 certifikátu X.509 s kódováním DER base64url. Například vzhledem k hodnotě hash 84E05C1D98BCE3A5421D225B140B36E86A3D5534 certifikátu X.509 (Hex), x5t bude hOBcHZi846VCHSJbFAs26Go9VTQ deklarace identity (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.

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

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05",
  "jti": "22b3bb26-e046-42df-9c96-65dbd72c1c81",
  "nbf": 1484592741,
  "sub": "97e0a5b7-d745-40b6-94fe-5f77d35c6e05"
}
.
"Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

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:

  1. Vyberte Certifikáty a tajné>certifikáty.
  2. Klikněte na Nahrát certifikát a vyberte soubor certifikátu, který chcete nahrát.
  3. Klikněte na tlačítko 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:

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

  2. 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"
        }
    ]
    
  3. 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.