Freigeben über

Sichern von APIs über eine Clientzertifikatauthentifizierung in API Management

GILT FÜR: Alle API Management-Ebenen

API Management bietet die Möglichkeit, den Zugriff auf APIs (d. h. vom Client auf API Management) mithilfe von Clientzertifikaten gegenseitiger TLS-Authentifizierung zu schützen. Mithilfe von Richtlinienausdrücken können Sie die von dem Client, der eine Verbindung herstellen möchte, angegebenen Zertifikate überprüfen, und Sie können Zertifikateigenschaften anhand von gewünschten Werten überprüfen.

Informationen zum Schützen des Zugriffs auf den Back-End-Dienst einer API mithilfe von Clientzertifikaten (d. h. von API Management auf das Back-End) finden Sie unter Sichern von Back-End-Diensten über eine Clientzertifikatauthentifizierung in Azure API Management.

Eine Konzept-Übersicht über die API-Autorisierung finden Sie unter Authentifizierung und Autorisierung an APIs im API-Management.

Zertifikatoptionen

Für die Zertifikatüberprüfung kann API Management Zertifikate überprüfen, die in Ihrer API Management-Instanz verwaltet werden. Wenn Sie Clientzertifikate mithilfe von API Management verwalten möchten, stehen Ihnen die folgenden Optionen zur Verfügung:

  • Verweisen auf ein in Azure Key Vault verwaltetes Zertifikat
  • Direktes Hinzufügen einer Zertifikatsdatei in API Management

Die Verwendung von Schlüsseltresorgeheimnissen wird empfohlen, weil dadurch die Sicherheit von API Management verbessert wird:

  • In Schlüsseltresoren gespeicherte Geheimnisse können für mehrere Dienste wiederverwendet werden.
  • Auf in Schlüsseltresoren gespeicherte Zertifikate können präzise Zugriffsrichtlinien angewendet werden.
  • Im Schlüsseltresor aktualisierte Zertifikate werden in API Management automatisch rotiert. Nach der Aktualisierung im Schlüsseltresor wird ein Zertifikat innerhalb von 4 Stunden in API Management aktualisiert. Sie können das Zertifikat auch manuell im Azure-Portal oder über die Verwaltungs-REST-API aktualisieren.

Voraussetzungen

  • Falls Sie noch keine API Management-Dienstinstanz erstellt haben, finden Sie weitere Informationen unter Erstellen einer API Management-Dienstinstanz.

  • Sie benötigen Zugriff auf das Zertifikat und die Kennwörter für die Verwaltung in einem Azure Key Vault oder zum Hochladen in den API Management-Dienst. Das Zertifikat muss entweder im CER- oder PFX-Format vorliegen. Selbstsignierte Zertifikate sind zulässig.

    Wenn Sie ein selbstsigniertes Zertifikat verwenden, installieren Sie auch vertrauenswürdige Zertifikate der Stamm- und Zwischenzertifizierungsstelle in Ihrer API Management-Instanz.

    Hinweis

    Zertifizierungsstellenzertifikate für die Zertifikatüberprüfung werden auf der Verbrauchsebene nicht unterstützt.

Voraussetzungen für die Key Vault-Integration

Hinweis

Diese Funktion ist derzeit in Arbeitsbereichen nicht verfügbar.

  1. Wenn Sie noch nicht über einen Schlüsseltresor verfügen, erstellen Sie einen. Informationen zum Erstellen eines Schlüsseltresors finden Sie in der Schnellstartanleitung: Erstellen eines Schlüsseltresors mithilfe des Azure-Portals.

  2. Aktivieren Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität in der API-Verwaltung.

Konfigurieren des Zugriffs auf den Schlüsseltresor

  1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.
  2. Wählen Sie im linken Menü die Access-Konfiguration aus. Beachten Sie das konfigurierte Berechtigungsmodell .
  3. Konfigurieren Sie je nach Berechtigungsmodell entweder eine Schlüsseltresor-Zugriffsrichtlinie oder den Azure RBAC-Zugriff für eine verwaltete API Management-Identität.

Um eine Zugriffsrichtlinie für den Key Vault hinzuzufügen:

  1. Wählen Sie im Menü auf der linken Seite Zugriffsrichtlinien aus.
  2. Wählen Sie auf der Seite Zugriffsrichtlinien die Option + Erstellen aus.
  3. Wählen Sie auf der Registerkarte "Berechtigungen " unter "Geheime Berechtigungen" die Option " Abrufen und Liste" und dann " Weiter" aus.
  4. Wählen Sie auf der Registerkarte "Prinzipal " die Option "Prinzipal" aus, suchen Sie nach dem Ressourcennamen Ihrer verwalteten Identität, und wählen Sie dann "Weiter" aus. Wenn Sie eine systemseitig zugewiesene Identität verwenden, ist der Prinzipal der Name der API Management-Instanz.
  5. Wählen Sie erneut Weiter aus. Wählen Sie auf der Registerkarte Überprüfen + erstellen die Option Erstellen aus.

Informationen zum Erstellen eines Zertifikats im Schlüsseltresor oder zum Importieren eines Zertifikats in den Schlüsseltresor finden Sie in der Schnellstartanleitung: Festlegen und Abrufen eines Zertifikats aus Azure Key Vault mithilfe des Azure-Portals.

Anforderungen an Key Vault-Firewall

Wenn die Key Vault-Firewall auf Ihrem Schlüsseltresor aktiviert ist, müssen Sie die folgenden Anforderungen erfüllen:

  • Sie müssen die vom System zugewiesene verwaltete Identität der API-Verwaltungsinstanz verwenden, um auf den Schlüsseltresor zuzugreifen.

  • Aktivieren Sie in der Key Vault-Firewall die Option Vertrauenswürdigen Microsoft-Diensten die Umgehung dieser Firewall erlauben? .

  • Stellen Sie sicher, dass Ihre lokale Client-IP-Adresse vorübergehend auf den Schlüsseltresor zugreifen darf, während Sie ein Zertifikat oder Geheimnis auswählen, das Sie der Azure API Management-Instanz hinzufügen möchten. Weitere Informationen finden Sie unter Konfigurieren von Azure Key Vault-Netzwerkeinstellungen.

    Nach Abschluss der Konfiguration können Sie Ihre Clientadresse in der Firewall des Schlüsseltresors blockieren.

Anforderungen für virtuelle Netzwerke

Wenn die API Management-Instanz in einem virtuellen Netzwerk bereitgestellt wird, müssen Sie darüber hinaus die folgenden Netzwerkeinstellungen konfigurieren:

  • Aktivieren Sie einen Dienstendpunkt für Key Vault im API-Verwaltungssubnetz.
  • Konfigurieren Sie eine Netzwerksicherheitsgruppen-Regel (NSG), um ausgehenden Datenverkehr an die Diensttags AzureKeyVault und AzureActiveDirectory zuzulassen.

Ausführliche Informationen finden Sie unter Netzwerkkonfiguration beim Einrichten der API-Verwaltung in einem virtuellen Netzwerk.

Hinzufügen eines Schlüsseltresorzertifikats

Weitere Informationen finden Sie unter Voraussetzungen für die Key Vault-Integration.

Wichtig

Um Ihrer API-Verwaltungsinstanz ein Schlüsseltresorzertifikat hinzuzufügen, müssen Sie über berechtigungen zum Auflisten geheimer Schlüssel aus dem Schlüsseltresor verfügen.

Achtung

Achten Sie beim Verwenden eines Schlüsseltresorzertifikats in der API-Verwaltung darauf, das Zertifikat, den Schlüsseltresor oder die verwaltete Identität, die für den Zugriff auf den Schlüsseltresor verwendet wird, nicht zu löschen.

So fügen Sie ein Schlüsseltresorzertifikat zu API Management hinzu

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.

  2. Wählen Sie unter Sicherheit die Option Zertifikate aus.

  3. Wählen Sie Zertifikate>+ Hinzufügen aus.

  4. Geben Sie in der ID einen Namen ein.

  5. Wählen Sie in Zertifikat die Option Schlüsseltresor aus.

  6. Geben Sie den Bezeichner eines Schlüsseltresorzertifikats ein, oder wählen Sie Auswählen aus, um ein Zertifikat aus einem Schlüsseltresor auszuwählen.

    Wichtig

    Wenn Sie selbst eine Key Vault-Zertifikat-ID eingeben, vergewissern Sie sich, dass sie keine Versionsinformationen enthält. Andernfalls wird das Zertifikat nach einer Aktualisierung im Schlüsseltresor nicht automatisch in API Management rotiert.

  7. Wählen Sie in der Clientidentität eine vom System zugewiesene Identität oder eine vorhandene vom Benutzer zugewiesene verwaltete Identität aus. Weitere Informationen finden Sie unter Verwenden von verwalteten Identitäten in Azure API Management.

    Hinweis

    Die Identität muss Berechtigungen zum Abrufen und Auflisten von Zertifikaten im Schlüsseltresor aufweisen. Wenn Sie noch keinen Zugriff auf den Schlüsseltresor konfiguriert haben, werden Sie von der API-Verwaltung aufgefordert, damit sie die Identität automatisch mit den erforderlichen Berechtigungen konfigurieren kann.

  8. Wählen Sie Hinzufügen.

    Screenshot, der zeigt, wie Sie dem API-Management im Portal ein Schlüsseltresorzertifikat hinzufügen.

  9. Wählen Sie Speichern aus.

Hochladen eines Zertifikats

So laden Sie ein Schlüsseltresorzertifikat in API Management hoch

  1. Wechseln Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.

  2. Wählen Sie unter Sicherheit die Option Zertifikate aus.

  3. Wählen Sie Zertifikate>+ Hinzufügen aus.

  4. Geben Sie in der ID einen Namen ein.

  5. Wählen Sie in Zertifikat die Option Benutzerdefinierte aus.

  6. Durchsuchen Sie das Dateisystem, um die PFX-Zertifikatdatei auszuwählen, und geben Sie das zugehörige Kennwort ein.

  7. Wählen Sie Hinzufügen.

    Screenshot: Hochladen eines Clientzertifikats in API Management im Portal

  8. Wählen Sie Speichern aus.

Hinweis

Wenn Sie das Zertifikat nur zum Authentifizieren des Clients mit API Management verwenden möchten, können Sie eine CER-Datei hochladen.

Aktivieren der API Management-Instanz zum Empfangen und Überprüfen von Clientzertifikaten

Developer-, Basic-, Standard- oder Premium-Ebene

Um Clientzertifikate im Tarif „Developer“, „Basic“, „Standard“ oder „Premium“ über HTTP/2 empfangen und überprüfen zu können, müssen Sie wie unten gezeigt auf dem Blatt Benutzerdefinierte Domänen die Einstellung Clientzertifikat aushandeln aktivieren.

Clientzertifikat aushandeln

Consumption, Basic v2, Standard v2 oder Premium v2-Tarif

Um Clientzertifikate im Tarif Consumption, Basic v2, Standard v2 oder Premium v2 empfangen und überprüfen zu können, müssen Sie wie unten gezeigt auf dem Blatt Benutzerdefinierte Domänen die Einstellung Clientzertifikat anfordern aktivieren.

Anfordern des Clientzertifikats

Richtlinie zum Überprüfen von Clientzertifikaten

Verwenden Sie die Richtlinie validate-client-certificate, um ein oder mehrere Attribute eines Clientzertifikats zu überprüfen, das für den Zugriff auf in Ihrer API Management-Instanz gehostete APIs verwendet wird.

Konfigurieren Sie die Richtlinie zum Überprüfen eines oder mehrerer Attribute, wie z. B.: Zertifikataussteller, Antragsteller, Fingerabdruck, Informationen dazu, ob das Zertifikat anhand einer Onlinesperrliste überprüft wird, sowie weitere Attribute.

Zertifikatüberprüfung mit Kontextvariablen

Sie können auch Richtlinienausdrücke mit der context-Variable erstellen, um Clientzertifikate zu überprüfen. Die Beispiele in den folgenden Abschnitten zeigen Ausdrücke, die die Eigenschaft context.Request.Certificate sowie weitere context-Eigenschaften verwenden.

Hinweis

Die gegenseitige Zertifikatauthentifizierung funktioniert möglicherweise nicht ordnungsgemäß, wenn der API Management-Gatewayendpunkt über das Application Gateway verfügbar gemacht wird. Dies liegt daran, dass Application Gateway als Layer 7-Lastenausgleich fungiert und eine eindeutige SSL-Verbindung mit dem Back-End API Management-Dienst herstellt. Folglich wird das vom Client in der ersten HTTP-Anfrage angehängte Zertifikat nicht an APIM weitergeleitet. Als Problemumgehung können Sie das Zertifikat jedoch mithilfe der Option „Servervariablen“ übertragen. Ausführliche Anweisungen finden Sie unter Servervariablen für die gegenseitige Authentifizierung.

Wichtig

  • Ab Mai 2021 fordert die context.Request.Certificate-Eigenschaft nur dann das Zertifikat an, wenn die hostnameConfiguration der API Management-Instanz die negotiateClientCertificate-Eigenschaft auf TRUE festlegt. Standardmäßig ist negotiateClientCertificate auf FALSE festgelegt.
  • Wenn die TLS-Neuverhandlung in Ihrem Client deaktiviert ist, werden beim Anfordern des Zertifikats mithilfe der context.Request.Certificate-Eigenschaft möglicherweise TLS-Fehler angezeigt. Wenn dies passiert, aktivieren Sie die TLS-Neuverhandlungseinstellungen im Client.
  • Die Neuverhandlung der Zertifizierung wird in den API Management-Tarifen v2 nicht unterstützt.

Prüfen des Ausstellers und des Antragstellers

Die unten stehenden Richtlinien konfiguriert werden, um den Aussteller und den Antragsteller eines Clientzertifikats zu prüfen:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Hinweis

Verwenden Sie context.Request.Certificate.VerifyNoRevocation() anstelle von context.Request.Certificate.Verify(), um die Überprüfung der Zertifikatssperrliste zu deaktivieren. Wenn das Clientzertifikat selbstsigniert ist, müssen Stamm- oder Zwischen-Zertifizierungsstellenzertifikate in API Management hochgeladen werden, damit context.Request.Certificate.Verify() und context.Request.Certificate.VerifyNoRevocation() funktionieren.

Prüfen des Fingerabdrucks

Die folgenden Richtlinien können zum Prüfen des Fingerabdrucks eines Clientzertifikats konfiguriert werden:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Hinweis

Verwenden Sie context.Request.Certificate.VerifyNoRevocation() anstelle von context.Request.Certificate.Verify(), um die Überprüfung der Zertifikatssperrliste zu deaktivieren. Wenn das Clientzertifikat selbstsigniert ist, müssen Stamm- oder Zwischen-Zertifizierungsstellenzertifikate in API Management hochgeladen werden, damit context.Request.Certificate.Verify() und context.Request.Certificate.VerifyNoRevocation() funktionieren.

Prüfen eines Fingerabdrucks anhand von auf API Management hochgeladenen Zertifikaten

Das folgende Beispiel zeigt, wie Sie den Fingerabdruck eines Clientzertifikats anhand von auf API Management hochgeladenen Zertifikaten prüfen können:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Hinweis

Verwenden Sie context.Request.Certificate.VerifyNoRevocation() anstelle von context.Request.Certificate.Verify(), um die Überprüfung der Zertifikatssperrliste zu deaktivieren. Wenn das Clientzertifikat selbstsigniert ist, müssen Stamm- oder Zwischen-Zertifizierungsstellenzertifikate in API Management hochgeladen werden, damit context.Request.Certificate.Verify() und context.Request.Certificate.VerifyNoRevocation() funktionieren.

Tipp

Das Problem aufgrund eines Clientzertifikat-Deadlocks, das in diesem Artikel beschrieben ist, kann auf unterschiedliche Art und Weise auftreten, z. B. Einfrieren von Anforderungen, Anforderungen führen nach dem Timeout zum Status 403 Forbidden oder context.Request.Certificate ist null. Dieses Problem wirkt sich normalerweise auf Anforderungen vom Typ POST und PUT mit einer Inhaltslänge von ca. 60 KB oder mehr aus. Um dieses Problem zu verhindern, aktivieren Sie auf dem Blatt „Benutzerdefinierte Domänen“ die Einstellung „Clientzertifikat aushandeln“ für gewünschte Hostnamen, wie auf der ersten Abbildung dieses Dokuments gezeigt. Dieses Feature ist im Tarif „Verbrauch“ nicht verfügbar.

Verwandte Inhalte