Microsofts identitetsplattform certifikatautentiseringsuppgifter för program

Artikel
04/10/2024

Med Microsofts identitetsplattform kan ett program använda sina egna autentiseringsuppgifter för autentisering var som helst där en klienthemlighet kan användas, till exempel i beviljandeflödet för OAuth 2.0-klientautentiseringsuppgifteroch OBO-flödet (on-behalf-of).

En form av autentiseringsuppgifter som ett program kan använda för autentisering är en JSON Web Token-försäkran (JWT) signerad med ett certifikat som programmet äger. Detta beskrivs i OpenID Anslut-specifikationen för klientautentiseringsalternativetprivate_key_jwt.

Om du är intresserad av att använda en JWT som utfärdats av en annan identitetsprovider som autentiseringsuppgifter för ditt program kan du läsa arbetsbelastningsidentitetsfederationen för hur du konfigurerar en federationsprincip.

Kontrollformat

För att beräkna försäkran kan du använda ett av de många JWT-biblioteken på valfritt språk – MSAL stöder detta med hjälp av .WithCertificate(). Informationen bärs av token i dess rubrik, anspråk och signatur.

Parameter	Anmärkning
`alg`	Ska vara RS256
`typ`	Ska vara JWT
`x5t`	Base64url-kodad SHA-1 tumavtryck för X.509-certifikatets DER-kodning. Med en X.509-certifikatshash ( `84E05C1D98BCE3A5421D225B140B36E86A3D5534` Hex) skulle anspråket `x5t` till exempel vara `hOBcHZi846VCHSJbFAs26Go9VTQ` (Base64url).

Anspråk (nyttolast)

Anspråkstyp	Värde	beskrivning
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	Anspråket "aud" (målgrupp) identifierar de mottagare som JWT är avsedd för (här Microsoft Entra-ID) Se RFC 7519, avsnitt 4.1.3. I det här fallet är mottagaren inloggningsservern (login.microsoftonline.com).
`exp`	1601519414	Anspråket "exp" (förfallotid) identifierar förfallotiden på eller efter vilken JWT inte får godkännas för bearbetning. Se RFC 7519, avsnitt 4.1.4. Detta gör att försäkran kan användas tills dess, så håll den kort - 5-10 minuter efter `nbf` högst. Microsoft Entra-ID:t begränsar för närvarande inte tiden `exp` .
`iss`	{ClientID}	Anspråket "iss" (utfärdare) identifierar det huvudnamn som utfärdade JWT, i det här fallet klientprogrammet. Använd GUID-program-ID:t.
`jti`	(ett Guid)	Anspråket "jti" (JWT ID) tillhandahåller en unik identifierare för JWT. Identifierarvärdet måste tilldelas på ett sätt som säkerställer att det finns en försumbar sannolikhet att samma värde oavsiktligt tilldelas till ett annat dataobjekt. Om programmet använder flera utfärdare måste kollisioner förhindras även mellan värden som genereras av olika utfärdare. Värdet "jti" är en skiftlägeskänslig sträng. RFC 7519, avsnitt 4.1.7
`nbf`	1601519114	Anspråket "nbf" (inte före) identifierar den tid innan JWT INTE får godkännas för bearbetning. RFC 7519, avsnitt 4.1.5. Det är lämpligt att använda den aktuella tiden.
`sub`	{ClientID}	Anspråket "sub" (ämne) identifierar ämnet för JWT, i det här fallet även ditt program. Använd samma värde som `iss`.
`iat`	1601519114	Anspråket "iat" (utfärdat vid) identifierar den tidpunkt då JWT utfärdades. Det här anspråket kan användas för att fastställa JWT-åldern. RFC 7519, avsnitt 4.1.5.

Signatur

Signaturen beräknas genom att certifikatet tillämpas enligt beskrivningen i JSON Web Token RFC7519-specifikationen.

Exempel på en avkodad JWT-försäkran

{
  "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..."

Exempel på en kodad JWT-försäkran

Följande sträng är ett exempel på kodad försäkran. Om du tittar noga ser du tre avsnitt avgränsade med punkter (.):

Det första avsnittet kodar rubriken
Det andra avsnittet kodar anspråken (nyttolasten)
Det sista avsnittet är signaturen som beräknas med certifikaten från innehållet i de två första avsnitten

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

Registrera certifikatet med Microsofts identitetsplattform

Du kan associera certifikatautentiseringsuppgifterna med klientprogrammet i Microsofts identitetsplattform via administrationscentret för Microsoft Entra med någon av följande metoder:

Ladda upp certifikatfilen

På fliken Appregistreringar för klientprogrammet:

Välj Certifikat och hemligheter>Certifikat.
Välj på Ladda upp certifikat och välj den certifikatfil som ska laddas upp.
Markera Lägga till. När certifikatet har laddats upp visas tumavtrycket, startdatumet och förfallovärdet.

Uppdatera programmanifestet

När du har hämtat ett certifikat beräknar du följande värden:

$base64Thumbprint – Base64-kodat värde för certifikathashen
$base64Value – Base64-kodat värde för certifikatets rådata

Ange ett GUID för att identifiera nyckeln i programmanifestet ($keyId).

I Azure-appregistreringen för klientprogrammet:

Välj Manifest för att öppna programmanifestet.

Ersätt egenskapen keyCredentials med din nya certifikatinformation med hjälp av följande schema.

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

Spara ändringarna i programmanifestet och ladda sedan upp manifestet till Microsofts identitetsplattform.

Egenskapen keyCredentials är flera värden, så du kan ladda upp flera certifikat för mer omfattande nyckelhantering.

Använda en klientkontroll

Klientkontroller kan användas var som helst där en klienthemlighet används. I auktoriseringskodflödet kan du till exempel skicka in ett client_secret för att bevisa att begäran kommer från din app. Du kan ersätta detta med client_assertion och client_assertion_type parametrar.

Parameter	Värde	beskrivning
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Det här är ett fast värde som anger att du använder en certifikatautentiseringsuppgift.
`client_assertion`	`JWT`	Det här är JWT som skapades ovan.

Nästa steg

Biblioteket MSAL.NET hanterar det här scenariot på en enda kodrad.

.NET-daemonkonsolprogrammet med Microsofts identitetsplattform kodexempel på GitHub visar hur ett program använder sina egna autentiseringsuppgifter för autentisering. Den visar också hur du kan skapa ett självsignerat certifikat med hjälp av PowerShell-cmdleten New-SelfSignedCertificate . Du kan också använda skripten för att skapa appar i exempelrepo för att skapa certifikat, beräkna tumavtrycket och så vidare.