Microsoft identity platform application authentication certificate credentials

Artikel
04/10/2024

Met het Microsoft-identiteitsplatform kan een toepassing overal waar een clientgeheim kan worden gebruikt de eigen referenties gebruiken voor verificatie, bijvoorbeeld in de OAuth 2.0-stroom voor toekenning van clientreferenties en de OBO-stroom (On-Behalf-Of).

Een vorm van referentie die een toepassing kan gebruiken voor verificatie is een JWT-assertie (JSON Web Token) die is ondertekend met een certificaat waarvan de toepassing eigenaar is. Dit wordt beschreven in de OpenID Connect-specificatie voor de private_key_jwt-optie voor clientverificatie.

Als u geïnteresseerd bent in het gebruik van een JWT die is uitgegeven door een andere id-provider als referentie voor uw toepassing, raadpleegt u Federatie van workloadidentiteit voor het instellen van een federatiebeleid.

Assertie-indeling

Als u de assertie wilt berekenen, kunt u een van de vele JWT-bibliotheken in de taal van uw keuze gebruiken. MSAL ondersteunt dit met behulp van .WithCertificate(). De informatie wordt door het token in de header, claims en handtekening meegenomen.

Parameter	Opmerking
`alg`	Moet PS256 zijn
`typ`	Moet JWT zijn
`x5t#s256`	Base64url-gecodeerde SHA-256-vingerafdruk van de DER-codering van het X.509-certificaat.

Claims (payload)

Claimtype	Weergegeven als	Beschrijving
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	De claim "aud" (doelgroep) identificeert de geadresseerden waarvoor de JWT is bedoeld (hier Microsoft Entra-id) Zie RFC 7519, sectie 4.1.3. In dit geval is die ontvanger de aanmeldingsserver (`login.microsoftonline.com`).
`exp`	1601519414	De claim exp (verlooptijd) geeft de verlooptijd aan of waarna de JWT niet mag worden geaccepteerd voor verwerking. Zie RFC 7519, sectie 4.1.4. Hierdoor kan de assertie tot die tijd worden gebruikt, dus houd deze kort: hooguit 5-10 minuten na `nbf`. Microsoft Entra ID plaatst momenteel geen beperkingen op de `exp` tijd.
`iss`	{ClientID}	De claim 'iss' (issuer) geeft de principal aan die de JWT heeft uitgegeven, in dit geval uw clienttoepassing. Gebruik de GUID-toepassings-id.
`jti`	(een GUID)	De "jti" (JWT ID)-claim biedt een unieke id voor de JWT. De id-waarde moet worden toegewezen op een manier die ervoor zorgt dat er een verwaarloosbare kans is dat dezelfde waarde per ongeluk wordt toegewezen aan een ander gegevensobject. Als de toepassing meerdere verleners gebruikt, moeten conflicten worden voorkomen tussen waarden die door verschillende verleners worden geproduceerd. De jti-waarde is een hoofdlettergevoelige tekenreeks. RFC 7519, sectie 4.1.7
`nbf`	1601519114	De claim 'nbf' (not before) geeft de tijd aan waarvoor de JWT NIET mag worden geaccepteerd voor verwerking. RFC 7519, sectie 4.1.5. Het gebruik van de huidige tijd is geschikt.
`sub`	{ClientID}	De claim 'sub' (subject) geeft het onderwerp van de JWT aan, in dit geval ook uw toepassing. Gebruik dezelfde waarde als `iss`.
`iat`	1601519114	The "iat" (uitgegeven op)-claim geeft de tijd aan wanneer de JWT was uitgegeven. Deze claim kan worden gebruikt om de leeftijd van de JWT te bepalen. RFC 7519, sectie 4.1.5.

Handtekening

De handtekening wordt berekend door het certificaat toe te passen zoals beschreven in de RFC7519-specificatie van het JSON Web Token. Gebruik PSS-opvulling.

Voorbeeld van een gedecodeerde JWT-assertie

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

Voorbeeld van een gecodeerde JWT-assertie

De volgende tekenreeks is een voorbeeld van een gecodeerde assertie. Als u goed kijkt, ziet u drie secties gescheiden door puntjes (.):

De eerste sectie codeert de header
De tweede sectie codeert de claims (payload)
De laatste sectie is de handtekening die wordt berekend met de certificaten van de inhoud van de eerste twee secties

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

Uw certificaat registreren bij het Microsoft-identiteitsplatform

U kunt de certificaatreferentie koppelen aan de clienttoepassing in het Microsoft Identity Platform via het Microsoft Entra-beheercentrum met behulp van een van de volgende methoden:

Het certificaatbestand uploaden

Op het tabblad App-registraties voor de clienttoepassing:

Selecteer Certificaten en geheimen>.
Selecteer certificaat uploaden en selecteer het certificaatbestand dat u wilt uploaden.
Selecteer Toevoegen. Zodra het certificaat is geüpload, worden de vingerafdruk, begindatum en vervalwaarden weergegeven.

Het toepassingsmanifest bijwerken

Nadat u een certificaat hebt verkregen, berekent u deze waarden:

$base64Thumbprint - Base64-gecodeerde waarde van de certificaat-hash
$base64Value - Base64-gecodeerde waarde van de onbewerkte gegevens van het certificaat

Geef een GUID op om de sleutel in het toepassingsmanifest ($keyId) te identificeren.

In de Azure-app-registratie voor de clienttoepassing:

Selecteer Manifest om het toepassingsmanifest te openen.

Vervang de eigenschap keyCredentials door uw nieuwe certificaatgegevens met behulp van het volgende schema.

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

Sla de bewerkingen in het toepassingsmanifest op en upload het manifest vervolgens naar het Microsoft-identiteitsplatform.

De eigenschap keyCredentials heeft meerdere waarden, dus u kunt meerdere certificaten uploaden voor uitgebreider sleutelbeheer.

Een clientassertie gebruiken

Clientasserties kunnen overal worden gebruikt waar een clientgeheim zou worden gebruikt. In de autorisatiecodestroom kunt u bijvoorbeeld een client_secret wachtwoord doorgeven om te bewijzen dat de aanvraag afkomstig is van uw app. U kunt dit vervangen door client_assertion- en client_assertion_type-parameters.

Parameter	Weergegeven als	Beschrijving
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Dit is een vaste waarde die aangeeft dat u een certificaatreferentie gebruikt.
`client_assertion`	`JWT`	Dit is de JWT die hierboven is gemaakt.

Volgende stappen

De MSAL.NET-bibliotheek verwerkt dit scenario in één regel code.

De .NET-daemon-consoletoepassing met behulp van codevoorbeeld van het Microsoft Identity Platform op GitHub laat zien hoe een toepassing eigen referenties gebruikt voor verificatie. U ziet ook hoe u een zelfondertekend certificaat kunt maken met behulp van de PowerShell-cmdlet New-SelfSignedCertificate. U kunt ook de scripts voor het maken van apps in de voorbeeldopslagplaats gebruiken om certificaten te maken, de vingerafdruk te berekenen, enzovoort.

Delen via