Sichern von APIs über eine Clientzertifikatauthentifizierung in API Management

API Management bietet die Möglichkeit, den Zugriff auf APIs (d.h. vom Client auf API Management) mithilfe von Clientzertifikaten zu sichern. 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 (von API Management auf das Back-End) finden Sie unter Sichern von Back-End-Diensten über eine Clientzertifikatauthentifizierung in Azure API Management.

Wichtig

Um Clientzertifikate im Tarif „Entwickler“, „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.

Negotiate client certificate

Wichtig

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.

Request client certificate

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.

Weitere Informationen finden Sie unter API Management-Richtlinien für die Zugriffsbeschränkung.

Zertifikatüberprüfung mit Kontextvariablen

Sie können auch Richtlinienausdrücke mit der -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.

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.

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 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 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 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 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