Microsoft Identity Platform-Zertifikatanmeldeinformationen für die AnwendungsauthentifizierungMicrosoft identity platform application authentication certificate credentials

Microsoft Identity Platform ermöglicht es 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).Microsoft identity platform allows an application to use its own credentials for authentication anywhere a client secret could be used, for example, in the OAuth 2.0 client credentials grant flow and the on-behalf-of (OBO) flow.

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.One form of credential that an application can use for authentication is a JSON Web Token (JWT) assertion signed with a certificate that the application owns.

AssertionformatAssertion format

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().To compute the assertion, you can use one of the many JWT libraries in the language of your choice - MSAL supports this using .WithCertificate(). Die Informationen sind im Header, den Ansprüchen und der Signatur des Tokens enthalten.The information is carried by the token in its Header, Claims, and Signature.

ParameterParameter AnmerkungRemark
alg Muss RS256 sein.Should be RS256
typ Muss JWT sein.Should be JWT
x5t Die als Base64url-Zeichenfolgenwert codierte Hexadezimaldarstellung des X.509-Zertifikathashs (auch als SHA-1-Fingerabdruck des Zertifikats bezeichnet).The X.509 certificate hash's (also known as the cert's SHA-1 thumbprint) Hex representation encoded as a Base64url string value. Beim X.509-Zertifikathash 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hexadezimaldarstellung) würde der x5t-Anspruch beispielsweise hOBcHZi846VCHSJbFAs26Go9VTQ= (Base64url) lauten.For example, given an X.509 certificate hash of 84E05C1D98BCE3A5421D225B140B36E86A3D5534 (Hex), the x5t claim would be hOBcHZi846VCHSJbFAs26Go9VTQ= (Base64url).

Ansprüche (Nutzlast)Claims (payload)

AnspruchstypClaim type WertValue BESCHREIBUNGDescription
audaud https://login.microsoftonline.com/{tenantId}/v2.0 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.The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Azure AD) See RFC 7519, Section 4.1.3. In diesem Fall ist dieser Empfänger der Anmeldeserver (login.microsoftonline.com).In this case, that recipient is the login server (login.microsoftonline.com).
expexp 16015194141601519414 Der Anspruch „exp“ (Ablaufzeit) gibt die Ablaufzeit an, ab oder nach der das JWT NICHT für die Bearbeitung akzeptiert werden darf.The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.4.See RFC 7519, Section 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.This allows the assertion to be used until then, so keep it short - 5-10 minutes after nbf at most. In Azure AD sind derzeit keine Einschränkungen für den exp-Zeitpunkt vorgesehen.Azure AD does not place restrictions on the exp time currently.
ississ {ClientID}{ClientID} Der Anspruch „iss“ (issuer, Aussteller) identifiziert den Prinzipal, der das JWT ausgestellt hat, in diesem Fall Ihre Clientanwendung.The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Verwenden Sie die GUID der Anwendungs-ID.Use the GUID application ID.
jtijti (eine GUID)(a Guid) Der Anspruch "jti" (JWT-ID) stellt einen eindeutigen Bezeichner für das JWT bereit.The "jti" (JWT ID) claim provides a unique identifier for the JWT. 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.The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. Der Wert von „JTI“ ist eine Zeichenfolge mit Beachtung der Groß-/Kleinschreibung.The "jti" value is a case-sensitive string. RFC 7519, Abschnitt 4.1.7RFC 7519, Section 4.1.7
nbfnbf 16015191141601519114 Der Anspruch „nbf“ (nicht vor) gibt die Zeit an, vor der das JWT NICHT für die Bearbeitung akzeptiert werden darf.The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. Weitere Informationen finden Sie unter RFC 7519, Abschnitt 4.1.5.RFC 7519, Section 4.1.5. Die Verwendung der aktuellen Uhrzeit ist angemessen.Using the current time is appropriate.
subsub {ClientID}{ClientID} Der Anspruch „sub“ (subject, Antragsteller) identifiziert den Antragsteller des JWT, in diesem Fall ist das ebenfalls Ihre Anwendung.The "sub" (subject) claim identifies the subject of the JWT, in this case also your application. Verwenden Sie denselben Wert wie für iss.Use the same value as iss.

SignaturSignature

Zur Berechnung der Signatur wird das Zertifikat wie in der Spezifikation RFC7519 für JSON-Webtoken beschrieben angewendet.The signature is computed by applying the certificate as described in the JSON Web Token RFC7519 specification.

Beispiel einer decodierten JWT-AssertionExample of a decoded JWT assertion

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/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-AssertionExample of an encoded JWT assertion

Die folgende Zeichenfolge ist ein Beispiel für eine codierte Assertion.The following string is an example of encoded assertion. Bei genauer Betrachtung sehen Sie drei Abschnitte, die jeweils durch einen Punkt getrennt sind (.):If you look carefully, you notice three sections separated by dots (.):

  • Im ersten Abschnitt ist der Header codiert.The first section encodes the header
  • Im zweiten Abschnitt sind die Ansprüche (Nutzlast) codiert.The second section encodes the claims (payload)
  • Der letzte Abschnitt enthält die Signatur, die mit den Zertifikaten aus dem Inhalt der ersten beiden Abschnitte berechnet wurde.The last section is the signature computed with the certificates from the content of the first two sections
"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Registrieren Ihres Zertifikats bei Microsoft Identity PlatformRegister your certificate with Microsoft identity platform

Über das Azure-Portal können Sie die Zertifikatanmeldeinformationen mit der Clientanwendung in Microsoft Identity Platform verknüpfen. Dazu haben Sie folgende Möglichkeiten:You can associate the certificate credential with the client application in Microsoft identity platform through the Azure portal using any of the following methods:

Hochladen der ZertifikatdateiUploading the certificate file

In der Azure-App-Registrierung für die Clientanwendung:In the Azure app registration for the client application:

  1. Wählen Sie Zertifikate & Geheimnisse aus.Select Certificates & secrets.
  2. Klicken Sie auf Zertifikat hochladen, und wählen Sie die Zertifikatdatei zum Hochladen aus.Click on Upload certificate and select the certificate file to upload.
  3. Klicken Sie auf Hinzufügen.Click Add. Nachdem das Zertifikat hochgeladen wurde, werden der Fingerabdruck, das Startdatum und der Ablaufzeitpunkt angezeigt.Once the certificate is uploaded, the thumbprint, start date, and expiration values are displayed.

Aktualisieren des AnwendungsmanifestsUpdating the application manifest

Wenn Sie über ein Zertifikat verfügen, berechnen Sie Folgendes:Having hold of a certificate, you need to compute:

  • $base64Thumbprint: Base64-codierter Wert des Zertifikathashs$base64Thumbprint - Base64-encoded value of the certificate hash
  • $base64Value: Base64-codierter Wert der Zertifikatrohdaten$base64Value - Base64-encoded value of the certificate raw data

Geben Sie außerdem eine GUID an, um den Schlüssel im Anwendungsmanifest ($keyId) zu identifizieren.You also need to provide a GUID to identify the key in the application manifest ($keyId).

In der Azure-App-Registrierung für die Clientanwendung:In the Azure app registration for the client application:

  1. Wählen Sie Manifest aus, um das Anwendungsmanifest zu öffnen.Select Manifest to open the application manifest.

  2. Ersetzen Sie die Eigenschaft keyCredentials gemäß dem folgenden Schema durch Ihre neuen Zertifikatinformationen.Replace the keyCredentials property with your new certificate information using the following schema.

    "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.Save the edits to the application manifest and then upload the manifest to Microsoft identity platform.

    Da die keyCredentials-Eigenschaft mehrere Werte besitzen kann, können Sie mehrere Zertifikate hochladen, um eine vielfältigere Schlüsselverwaltung zu erreichen.The keyCredentials property is multi-valued, so you may upload multiple certificates for richer key management.

Verwenden einer ClientassertionUsing a client assertion

Clientassertionen können überall dort verwendet werden, wo ein geheimer Clientschlüssel verwendet werden würde.Client assertions can be used anywhere a client secret would be used. Beispielsweise können Sie im Autorisierungscodeflow den Parameter client_secret übergeben, um nachzuweisen, dass die Anforderung von Ihrer App stammt.So for example, in the authorization code flow, you can pass in a client_secret to prove that the request is coming from your app. Sie können dies durch client_assertion- und client_assertion_type-Parameter ersetzen.You can replace this with client_assertion and client_assertion_type parameters.

ParameterParameter WertValue BeschreibungDescription
client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer Dies ist ein fester Wert, der darauf hinweist, dass Sie Zertifikatanmeldeinformationen verwenden.This is a fixed value, indicating that you are using a certificate credential.
client_assertion JWTJWT Dies ist das oben erstellte JWT.This is the JWT created above.

Nächste SchritteNext steps

Die Bibliothek „MSAL.NET“ löst dieses Szenario mit einer einzigen Codezeile.The MSAL.NET library handles this scenario in a single line of code.

Das Codebeispiel .NET Core-Daemon-Konsolenanwendung mit Microsoft Identity Platform auf GitHub zeigt, wie eine Anwendung ihre eigenen Anmeldeinformationen für die Authentifizierung verwendet.The .NET Core daemon console application using Microsoft identity platform code sample on GitHub shows how an application uses its own credentials for authentication. Zudem erfahren Sie darin, wie Sie mit dem PowerShell-Cmdlet New-SelfSignedCertificate ein selbstsigniertes Zertifikat erstellen können.It also shows how you can create a self-signed certificate using the New-SelfSignedCertificate PowerShell cmdlet. Sie können auch die App-Erstellungsskripts im Beispielrepository verwenden, um Zertifikate zu erstellen, den Fingerabdruck zu berechnen und so weiter.You can also use the app creation scripts in the sample repo to create certificates, compute the thumbprint, and so on.