Freigeben über


Hinzufügen eines Zertifikats zu einer App mithilfe von Microsoft Graph

Die Microsoft Identity Platform unterstützt drei Arten von Anmeldeinformationen zum Authentifizieren von Apps und Dienstprinzipalen: Kennwörter (App-Geheimnisse), Zertifikate und Anmeldeinformationen für Verbundidentitäten. Wenn Sie keine Anmeldeinformationen für Verbundidentitäten für Ihre App verwenden können, wird dringend empfohlen, Zertifikate anstelle von Geheimnissen zu verwenden.

Sie können Zertifikate mithilfe der Microsoft Entra Admin Center hinzufügen oder entfernen. Möglicherweise müssen Sie jedoch das Hinzufügen der Zertifikatanmeldeinformationen für Ihre App oder Ihren Dienstprinzipal automatisieren.

Dieser Artikel enthält Anleitungen zur Verwendung von Microsoft Graph- und PowerShell-Skripts zum programmgesteuerten Aktualisieren von Zertifikatanmeldeinformationen für eine App-Registrierung.

Voraussetzungen

Für dieses Tutorial benötigen Sie die folgenden Ressourcen und Berechtigungen:

  • Ein aktiver Microsoft Entra Mandant.
  • Ein API-Client wie Graph Explorer. Melden Sie sich als Benutzer an, der Anwendungen im Mandanten erstellen und verwalten darf. Die Rollen Anwendungsentwickler (einer App, die er besitzt) und Anwendungsadministrator sind die Rollen mit den geringsten Berechtigungen, die diesen Vorgang ausführen können.
  • Ein signiertes Zertifikat, das zum Authentifizieren der App verwendet werden soll. In diesem Artikel wird ein selbstsigniertes Zertifikat zu Demonstrationszwecken verwendet. Informationen zum Generieren eines Zertifikats finden Sie unter Erstellen eines selbstsignierten öffentlichen Zertifikats zum Authentifizieren Ihrer Anwendung.

Achtung

Die Verwendung von Zertifikaten wird dringend gegenüber Geheimnissen empfohlen; Es wird jedoch nicht empfohlen, selbstsignierte Zertifikate zu verwenden. Sie können die Sicherheitsleiste Ihrer Anwendung aufgrund verschiedener Faktoren wie der Verwendung veralteter Hash- und Verschlüsselungssammlungen oder fehlender Validierung verringern. Es wird empfohlen, Zertifikate von einer bekannten vertrauenswürdigen Zertifizierungsstelle zu beschaffen.

Schritt 1: Lesen der Zertifikatdetails

Zum programmgesteuerten Hinzufügen eines Zertifikats mit Microsoft Graph benötigen Sie den Schlüssel des Zertifikats. Optional können Sie den Fingerabdruck des Zertifikats hinzufügen.

[Optional] Abrufen des Zertifikatfingerabdrucks

Es ist optional, den Zertifikatfingerabdruck der Anforderungsnutzlast hinzuzufügen. Wenn Sie den Fingerabdruck hinzufügen möchten, können Sie die folgende PowerShell-Anforderung ausführen, um den Fingerabdruck des Zertifikats zu lesen. Bei dieser Anforderung wird davon ausgegangen, dass Sie das Zertifikat generiert und auf Ihr lokales Laufwerk exportiert haben.

Anforderung

## Replace the file path with the source of your certificate and output path with the location where you want to save the thumprint details

Get-PfxCertificate -Filepath "C:\Users\admin\Desktop\20230112.cer" | Out-File -FilePath "C:\Users\admin\Desktop\20230112.cer.thumbprint.txt"

Antwort

Die Ausgabe in der .txt-Datei kann in etwa wie folgt aussehen.

Thumbprint                                Subject
----------                                -------
5A126608ED1A1366F714A4A62B7015F3262840F1  CN=20230112

Abrufen des Zertifikatschlüssels

Führen Sie die folgende Anforderung aus, um den Schlüssel des Zertifikats zu lesen und ihn mithilfe von PowerShell in einer .txt-Datei zu speichern.

Anforderung

PowerShell < 6:

## Replace the file path with the location of your certificate

[convert]::ToBase64String((Get-Content C:\Users\admin\Desktop\20230112.cer -Encoding byte)) | Out-File -FilePath "C:\Users\admin\Desktop\20230112.key.txt"

PowerShell >= 6:

## Replace the file path with the location of your certificate

[convert]::ToBase64String((Get-Content C:\Users\admin\Desktop\20230112.cer -AsByteStream))  | Out-File -FilePath "C:\Users\admin\Desktop\20230112.key.txt"

Antwort

Die Ausgabe in der .txt-Datei kann in etwa wie folgt aussehen.

Anmerkung: Der hier gezeigte Schlüssel wurde aus Gründen der Lesbarkeit gekürzt.

MIIDADCCAeigAwIBAgIQP6HEGDdZ65xJTcK4dCBvZzANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMjAeFw0yMzAxMTIwODExNTZaFw0yNDAxMTIwODMxNTZaMBMxETAPBgNVBAMMCDIwMjMwMTEyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAseKf1weEacJ67D6/...dG+7WMIBsIUy0xz6MmyvfSohz3oNP4jHt7pJ9TyxnvDlaxQPUbuIL+DaXVkKRm1V3GgIpKTBqMzTf4tCpy7rpUZbhcwAFw6h9A==

Schritt 2: Hinzufügen der Zertifikatdetails mithilfe von Microsoft Graph

Anforderung

Die folgende Anforderung fügt die Zertifikatdetails zu einer App hinzu. Die Einstellungen sind wie folgt:

  • StartDateTime ist das Datum, an dem oder nachdem das Zertifikat erstellt wurde.
  • EndDateTime kann maximal 1 Jahr ab startDateTime sein. Wenn keine Angabe erfolgt, weist das System automatisch ein Datum 1 Jahr nach startDateTime zu.
  • Der Typ und die Verwendung müssen bzwVerify. seinAsymmetricX509Cert.
  • Weisen Sie den Zertifikatantragstellernamen der displayName-Eigenschaft zu.
  • Der Schlüssel ist der Base64-codierte Wert, den Sie im vorherigen Schritt generiert haben. Der Fingerabdruck ist im codierten Schlüssel enthalten, und durch hinzufügen des Schlüssels wird auch der Fingerabdruck hinzugefügt.

Hinweis

Wenn Ihre App über ein vorhandenes gültiges Zertifikat verfügt, das Sie weiterhin für die Authentifizierung verwenden möchten, fügen Sie sowohl die aktuellen als auch die neuen Zertifikatdetails in das keyCredentials-Objekt der App ein. Da dies ein PATCH-Aufruf ist, der den Inhalt der Eigenschaft durch die neuen Werte ersetzt, wobei nur das neue Zertifikat die vorhandenen Zertifikate durch das neue ersetzt.

Im folgenden Beispiel wird ein neues Zertifikat hinzugefügt und alle vorhandenen Zertifikate ersetzt.

Anmerkung: Der hier gezeigte Schlüssel wurde aus Gründen der Lesbarkeit gekürzt.

PATCH https://graph.microsoft.com/v1.0/applications/bb77f42f-dacb-4ece-b3e6-285e63c24d52
Content-type: application/json

{
    "keyCredentials": [
        {
            "endDateTime": "2024-01-11T15:31:26Z",
            "startDateTime": "2023-01-12T15:31:26Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQP6HEGDdZ65xJTcK4dCBvZzANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMjAeFw0yMzAxMTIwODExNTZaFw0yNDAxMTIwODMxNTZaMBMxETAPBgNVBAMMCDIwMjMwMTEyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAseKf1weEacJ67D6/...laxQPUbuIL+DaXVkKRm1V3GgIpKTBqMzTf4tCpy7rpUZbhcwAFw6h9A==",
            "displayName": "CN=20230112"
        }
    ]
}

Im folgenden Beispiel wird ein neues Zertifikat hinzugefügt, ohne das vorhandene Zertifikat durch den Fingerabdruck 52ED9B5038A47B9E2E2190715CC238359D4F8F73zu ersetzen.

Anmerkung: Der hier gezeigte Schlüssel wurde aus Gründen der Lesbarkeit gekürzt.

PATCH https://graph.microsoft.com/v1.0/applications/bb77f42f-dacb-4ece-b3e6-285e63c24d52
Content-type: application/json

{
    "keyCredentials": [
        {
            "endDateTime": "2024-01-11T15:31:26Z",
            "startDateTime": "2023-01-12T09:31:26Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQejfrj3S974xI//npv7hFHTANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExNDAeFw0yMzAxMTIwOTA4NThaFw0yNDAxMTIwOTI4NThaMBMxETAPBgNVBAMMCDIwMjMwMTE0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt5vEj6j1l5wOVHR4eDGe77HWslaIVJ1NqxrXPm/...+R+U7sboj+kUvmFzXI+Ge73Liu8egL2NzOHHpO43calWgq36a9YW1yhBQR1ioEchu6jmudW3rF6ktmVqQ==",
            "displayName": "CN=20230114"
        },
        {
            "customKeyIdentifier": "52ED9B5038A47B9E2E2190715CC238359D4F8F73",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "base64MIIDADCCAeigAwIBAgIQfoIvchhpToxKEPI4iMrU1TANBgkqhkiG9w0BAQsFADATMREwDwYDVQQDDAgyMDIzMDExMzAeFw0yMzAxMTIwODI3NTJaFw0yNDAxMTIwODQ3NTJaMBMxETAPBgNVBAMMCDIwMjMwMTEzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+iqg1nMjYmFcFJh/.../S5X6qoEOyJBgtfpSBANWAdA==",
            "displayName": "CN=20230113"
        }
    ]
}

Antwort

HTTP/1.1 204 No Content

Schritt 3: Testen der reinen App-Authentifizierung

Sie können die reine App-Authentifizierung mithilfe von Microsoft Graph PowerShell testen, wie im folgenden Beispiel gezeigt.

Anforderung

## Authenticate using the certificate thumbprint
Connect-MgGraph -ClientID cf34b10f-50fd-4167-acf6-4f08ddd4561b -TenantId 38d49456-54d4-455d-a8d6-c383c71e0a6d -CertificateThumbprint 52ED9B5038A47B9E2E2190715CC238359D4F8F73

## Authenticate using the certificate subject name
Connect-MgGraph -ClientID 588028ea-22c2-490e-8c6b-80cd06985e8c -TenantId 38d49456-54d4-455d-a8d6-c383c71e0a6d -CertificateName CN=20230113

Antwort

Welcome To Microsoft Graph!

Führen Sie die folgende Anforderung aus, um zu bestätigen, dass Sie die Microsoft Graph PowerShell-Sitzung ohne angemeldeten Benutzer ausführen.

Get-MgContext

Die Antwort sieht in etwa wie folgt aus.



ClientId              : cf34b10f-50fd-4167-acf6-4f08ddd4561b
TenantId              : 38d49456-54d4-455d-a8d6-c383c71e0a6d
CertificateThumbprint :
Scopes                :
AuthType              : AppOnly
AuthProviderType      : ClientCredentialProvider
CertificateName       : CN=20230113
Account               :
AppName               : testApp
ContextScope          : Process
Certificate           :
PSHostVersion         : 5.1.22621.963
ClientTimeout         : 00:05:00


Zusammenfassung

Sie haben Microsoft Graph verwendet, um Zertifikatanmeldeinformationen für ein App-Objekt zu aktualisieren. Dieser Prozess ist eine programmgesteuerte Alternative zur Verwendung des Microsoft Entra Admin Center. Sie können auch Zertifikatanmeldeinformationen für einen Dienstprinzipal aktualisieren, indem Sie einen ähnlichen Prozess ausführen und den https://graph.microsoft.com/v1.0/servicePrincipals/ Endpunkt aufrufen.