Microsoft Identity Platform-Zertifikatanmeldeinformationen für die Anwendungsauthentifizierung

Artikel
04/18/2024

Die Microsoft Identity Platform ermöglicht einer Anwendung, sich überall dort mit ihren eigenen Anmeldeinformationen zu authentifizieren, wo ein geheimer Clientschlüssel verwendet werden kann, also beispielsweise im OAuth 2.0-Flow zum Gewähren von Clientanmeldeinformationen und im On-Behalf-Of-Flow (OBO).

Eine Form von Anmeldeinformationen, die eine Anwendung zur Authentifizierung verwenden kann, ist eine JSON Web Token (JWT)-Assertion, die mit einem zur Anwendung gehörigen Zertifikat signiert ist. Dies wird in der OpenID Connect Spezifikation für die private_key_jwt Client-Authentifizierungsoption beschrieben.

Wenn Sie daran interessiert sind, einen JWT, der von einem anderen Identitätsanbieter ausgestellt wurde, als Berechtigungsnachweis für Ihre Anwendung zu verwenden, lesen Sie bitte unter Workload Identitätsföderation nach, wie Sie eine Föderationsrichtlinie einrichten können.

Assertionformat

Für die Berechnung der Assertion können Sie eine der zahlreichen JWT-Bibliotheken in der Sprache Ihrer Wahl nutzen. MSAL unterstützt dies mithilfe von .WithCertificate(). Die Informationen sind im Header, den Ansprüchen und der Signatur des Tokens enthalten.

Parameter	Anmerkung
`alg`	Muss RS256 sein.
`typ`	Muss JWT sein.
`x5t`	Base64url-codierter SHA-1-Fingerabdruck der DER-Codierung des X.509-Zertifikats. Beim X.509-Zertifikathash `84E05C1D98BCE3A5421D225B140B36E86A3D5534` (Hexadezimaldarstellung) würde der `x5t`-Anspruch beispielsweise `hOBcHZi846VCHSJbFAs26Go9VTQ` (Base64url) lauten.

Ansprüche (Nutzlast)

Anspruchstyp	Wert	Beschreibung
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	Der Anspruch „aud“ (audience, Zielgruppe) identifiziert die Empfänger, für die das JWT vorgesehen ist (hier Microsoft Entra ID). Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.3. In diesem Fall ist dieser Empfänger der Anmeldeserver (login.microsoftonline.com).
`exp`	1601519414	Der Anspruch „exp“ (Ablaufzeit) gibt die Ablaufzeit an, ab oder nach der das JWT zur Bearbeitung nicht akzeptiert werden darf. Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.4. So kann die Assertion bis zu diesem Zeitpunkt verwendet werden. Daher sollte der Zeitraum kurz ausfallen, d. h. höchstens 5–10 Minuten nach `nbf` liegen. In Microsoft Entra ID gelten derzeit keine Einschränkungen für den `exp`-Zeitpunkt.
`iss`	{ClientID}	Der Anspruch „iss“ (issuer, Aussteller) identifiziert den Prinzipal, der das JWT ausgestellt hat, in diesem Fall Ihre Clientanwendung. Verwenden Sie die GUID der Anwendungs-ID.
`jti`	(eine GUID)	Der Anspruch "jti" (JWT-ID) stellt einen eindeutigen Bezeichner für das JWT bereit. Es muss ein Bezeichnerwert zugewiesen werden, bei dem die Wahrscheinlichkeit vernachlässigt werden kann, dass derselbe Wert versehentlich einem anderen Datenobjekt zugewiesen wird. Wenn die Anwendung mehrere Aussteller verwendet, MÜSSEN auch Konflikte zwischen Werten unterschiedlicher Aussteller verhindert werden. Der Wert von „JTI“ ist eine Zeichenfolge mit Beachtung der Groß-/Kleinschreibung. RFC 7519, Abschnitt 4.1.7
`nbf`	1601519114	Der Anspruch „nbf“ (nicht vor) gibt die Zeit an, vor der das JWT NICHT für die Bearbeitung akzeptiert werden darf. Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.5. Die Verwendung der aktuellen Uhrzeit ist angemessen.
`sub`	{ClientID}	Der Anspruch „sub“ (subject, Antragsteller) identifiziert den Antragsteller des JWT, in diesem Fall ist das ebenfalls Ihre Anwendung. Verwenden Sie denselben Wert wie für `iss`.
`iat`	1601519114	Der Anspruch „iat“ (Ausgestellt um) gibt den Zeitpunkt an, zu dem das JWT ausgestellt wurde. Dieser Anspruch kann verwendet werden, um das Alter des JWT zu bestimmen. Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.5.

Signatur

Zur Berechnung der Signatur wird das Zertifikat wie in der Spezifikation RFC7519 für JSON-Webtoken beschrieben angewendet.

Beispiel einer decodierten JWT-Assertion

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

Beispiel einer codierten JWT-Assertion

Die folgende Zeichenfolge ist ein Beispiel für eine codierte Assertion. Bei genauer Betrachtung sehen Sie drei Abschnitte, die jeweils durch einen Punkt getrennt sind (.):

Im ersten Abschnitt ist der Header codiert.
Im zweiten Abschnitt sind die Ansprüche (Nutzlast) codiert.
Der letzte Abschnitt enthält die Signatur, die mit den Zertifikaten aus dem Inhalt der ersten beiden Abschnitte berechnet wurde.

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

Registrieren Ihres Zertifikats bei Microsoft Identity Platform

Über das Microsoft Entra Admin Center können Sie die Zertifikatanmeldeinformationen mit der Clientanwendung in Microsoft Identity Platform verknüpfen. Dazu haben Sie folgende Möglichkeiten:

Hochladen der Zertifikatdatei

Auf der Registerkarte App-Registrierungen für die Clientanwendung:

Wählen Sie Zertifikate und Geheimnisse>Zertifikate aus.
Wählen Sie Zertifikat hochladen aus, und wählen Sie die Zertifikatsdatei zum Hochladen aus.
Wählen Sie Hinzufügen aus. Nachdem das Zertifikat hochgeladen wurde, werden der Fingerabdruck, das Startdatum und der Ablaufzeitpunkt angezeigt.

Aktualisieren des Anwendungsmanifests

Berechnen Sie nach dem Erwerb eines Zertifikats die folgenden Werte:

$base64Thumbprint: Base64-codierter Wert des Zertifikathashs
$base64Value: Base64-codierter Wert der Zertifikatrohdaten

Geben Sie eine GUID an, um den Schlüssel im Anwendungsmanifest ($keyId) zu identifizieren.

In der Azure-App-Registrierung für die Clientanwendung:

Wählen Sie Manifest aus, um das Anwendungsmanifest zu öffnen.

Ersetzen Sie die Eigenschaft keyCredentials gemäß dem folgenden Schema durch Ihre neuen Zertifikatinformationen.

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

Speichern Sie die Änderungen am Anwendungsmanifest, und laden Sie dann das Manifest in Microsoft Identity Platform hoch.

Da die keyCredentials-Eigenschaft mehrere Werte besitzen kann, können Sie mehrere Zertifikate hochladen, um eine vielfältigere Schlüsselverwaltung zu erreichen.

Verwenden einer Clientassertion

Clientassertionen können überall dort verwendet werden, wo ein geheimer Clientschlüssel verwendet werden würde. Beispielsweise können Sie im Autorisierungscodeflow ein client_secret übergeben, um nachzuweisen, dass die Anforderung von Ihrer App stammt. Sie können dies durch client_assertion- und client_assertion_type-Parameter ersetzen.

Parameter	Wert	Beschreibung
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Dies ist ein fester Wert, der darauf hinweist, dass Sie Zertifikatanmeldeinformationen verwenden.
`client_assertion`	`JWT`	Dies ist das oben erstellte JWT.

Nächste Schritte

Die Bibliothek „MSAL.NET“ löst dieses Szenario mit einer einzigen Codezeile.

Das Codebeispiel .NET-Daemon-Konsolenanwendung mit Microsoft Identity Platform auf GitHub zeigt, wie eine Anwendung ihre eigenen Anmeldeinformationen für die Authentifizierung verwendet. Zudem erfahren Sie darin, wie Sie mit dem PowerShell-Cmdlet New-SelfSignedCertificate ein selbstsigniertes Zertifikat erstellen können. Sie können auch die App-Erstellungsskripts im Beispielrepository verwenden, um Zertifikate zu erstellen, den Fingerabdruck zu berechnen und so weiter.