Microsoft Identity Platform-Zertifikatanmeldeinformationen für die Anwendungsauthentifizierung

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 Base64-codierter SHA-1-Fingerabdruck des X.509-Zertifikats. Beim X.509-Zertifikathash 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hexadezimaldarstellung) würde der x5t-Anspruch beispielsweise hOBcHZi846VCHSJbFAs26Go9VTQ= (Base64) 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 Azure AD). 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 NICHT für die Bearbeitung 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 Azure AD sind derzeit keine Einschränkungen für den exp-Zeitpunkt vorgesehen.
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ässig ist, dass derselbe Wert versehentlich einem anderen Datenobjekt zugewiesen wird. Wenn die Anwendung mehrere Aussteller verwendet, MÜSSEN auch Konflikte zwischen von mehreren Ausstellern erstellten Werten 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": "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"

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 Azure-Portal können Sie die Zertifikatanmeldeinformationen mit der Clientanwendung in der Microsoft Identity Platform verknüpfen. Dazu haben Sie folgende Möglichkeiten:

Hochladen der Zertifikatdatei

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

  1. Wählen Sie Zertifikate & Geheimnisse>Zertifikate aus.
  2. Klicken Sie auf Zertifikat hochladen, und wählen Sie die Zertifikatdatei zum Hochladen aus.
  3. Klicken Sie auf Hinzufügen. 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:

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

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

    "keyCredentials": [
        {
            "customKeyIdentifier": "$base64Thumbprint",
            "keyId": "$keyid",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "value":  "$base64Value"
        }
    ]
    
  3. 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 den Parameter 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 Core-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.