Freigeben über

Sichern von APIs über eine Clientzertifikatauthentifizierung in API Management

  • Artikel

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. Schritte zum Erstellen eines Schlüsseltresors finden Sie unter Schnellstart: Erstellen eines Schlüsseltresors über das Azure-Portal.

    Informationen zum Erstellen eines Zertifikats oder Importieren eines Zertifikats in den Schlüsseltresor finden Sie unter Schnellstart: Festlegen und Abrufen eines Zertifikats aus Azure Key Vault über das Azure-Portal.

  2. Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität in der API Management-Instanz.

Konfigurieren des Zugriffs auf den Schlüsseltresor

  1. Navigieren Sie im Portal zu Ihrem Schlüsseltresor.

  2. Wählen Sie im Menü auf der linken Seite Zugriffskonfiguration aus, und 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.

    So fügen Sie eine Schlüsseltresor-Zugriffsrichtlinie hinzu

    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 Berechtigungen für Geheimnis die Optionen Abrufen und Auflisten und dann Weiter aus.
    4. Klicken Sie auf der Registerkarte Prinzipal auf Prinzipal auswählen, 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.

    So konfigurieren Sie Azure RBAC-Zugriff

    1. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus.
    2. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Option Rollenzuweisung hinzufügen aus.
    3. Wählen Sie auf der Registerkarte Rolle die Option Schlüsseltresor-Zertifikatbenutzer aus.
    4. Wählen Sie auf der Registerkarte Mitglieder die Option Verwaltete Identität>+ Mitglieder auswählen aus.
    5. Wählen Sie auf der Seite Verwaltete Identität auswählen die systemseitig zugewiesene verwaltete Identität oder eine benutzerseitig zugewiesene verwaltete Identität aus, die Ihrer API Management-Instanz zugeordnet ist, und wählen Sie dann Auswählen aus.
    6. Wählen Sie Überprüfen und zuweisen aus.

Anforderungen an Key Vault-Firewall

Wenn die Key Vault-Firewall in Ihrem Schlüsseltresor aktiviert ist, gelten die folgenden zusätzlichen Anforderungen:

  • Sie müssen die systemseitig zugewiesene verwaltete Identität der API Management-Instanz 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 im API Management-Subnetz einen Dienstendpunkt für Azure Key Vault.
  • Konfigurieren Sie eine Netzwerksicherheitsgruppen-Regel (NSG), um ausgehenden Datenverkehr an die Diensttags AzureKeyVault und AzureActiveDirectory zuzulassen.

Einzelheiten finden Sie unter Netzwerkkonfiguration beim Einrichten von Azure API Management in einem VNet.

Hinzufügen eines Schlüsseltresorzertifikats

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

Wichtig

Wenn Sie Ihrer API Management-Instanz ein Schlüsseltresorzertifikat hinzufügen, müssen Sie über die Berechtigung verfügen, Geheimnisse aus dem Schlüsseltresor aufzulisten.

Achtung

Wenn Sie in API Management ein Zertifikat aus einem Schlüsseltresor verwenden, dürfen Sie auf keinen Fall das Zertifikat, den Schlüsseltresor oder die verwaltete Identität löschen, die für den Zugriff auf den Schlüsseltresor verwendet wird.

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

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

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

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

  4. Geben Sie in Id den gewünschten 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 einen Bezeichner für ein Schlüsseltresorzertifikat eingeben, stellen Sie sicher, dass dieser keine Versionsinformationen enthält. Andernfalls wird das Zertifikat nach einer Aktualisierung im Schlüsseltresor nicht automatisch in API Management rotiert.

  7. Wählen Sie unter Clientidentität eine systemseitig zugewiesene oder eine vorhandene benutzerseitig zugewiesene verwaltete Identität aus. Erfahren Sie, wie Sie verwaltete Identitäten in Ihrem API Management-Dienst hinzufügen oder bearbeiten.

    Hinweis

    Die Identität benötigt Berechtigungen zum Abrufen und Auflisten von Zertifikaten im Schlüsseltresor. Wenn Sie den Zugriff auf den Schlüsseltresor noch nicht konfiguriert haben, werden Sie von API Management dazu aufgefordert. Der Dienst kann die Identität dann automatisch mit den erforderlichen Berechtigungen konfigurieren.

  8. Wählen Sie Hinzufügen.

    Screenshot: Hinzufügen eines Schlüsseltresorzertifikats zu API Management im Portal

  9. Wählen Sie Speichern aus.

Hochladen eines Zertifikats

So laden Sie ein Schlüsseltresorzertifikat in API Management hoch

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

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

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

  4. Geben Sie in Id den gewünschten 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

Tarif „Verbrauch“, „Basic v2“, „Standard v2“

Um Clientzertifikate im Tarif „Verbrauch“, „Basic v2“ oder „Standard 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.

Nächste Schritte