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

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 Key Vault-Geheimnisbenutzer 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.

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.

   

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.

   

8. Wählen Sie Speichern aus.

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

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

Um Clientzertifikate in den Tarifen „Developer“, „Basic“, „Basic v2“, „Standard“, „Standard v2“ 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.

Verbrauchsebene

Um Clientzertifikate im Tarif „Verbrauch“ empfangen und überprüfen zu können, müssen Sie wie unten gezeigt auf dem Blatt Benutzerdefinierte Domänen die Einstellung Clientzertifikat anfordern aktivieren.

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.

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>

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>

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>

Nächste Schritte

• Sichern von Back-End-Diensten über eine Clientzertifikatauthentifizierung
• Hinzufügen eines benutzerdefinierten ZS-Zertifikats in Azure API Management
• Informationen zu Richtlinien in API Management