Microsoft identity platform application authentication certificate credentials

  • Artikel

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 RS256 zijn
typ Moet JWT zijn
x5t Base64url-gecodeerde SHA-1-vingerafdruk van de DER-codering van het X.509-certificaat. Als u bijvoorbeeld een X.509-certificaat-hash van 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex) gebruikt, is hOBcHZi846VCHSJbFAs26Go9VTQ de x5t claim (Base64url).

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.

Voorbeeld van een gedecodeerde JWT-assertie

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

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:

  1. Selecteer Certificaten en geheimen>.
  2. Selecteer certificaat uploaden en selecteer het certificaatbestand dat u wilt uploaden.
  3. 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:

  1. Selecteer Manifest om het toepassingsmanifest te openen.

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

  3. 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.