Sichern von APIs über eine Clientzertifikatauthentifizierung in API ManagementHow to secure APIs using client certificate authentication 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.API Management provides the capability to secure access to APIs (i.e., client to API Management) using client certificates. Sie können eingehende Zertifikate überprüfen und die Zertifikateigenschaften mit den gewünschten Werten vergleichen, indem Sie Richtlinienausdrücke verwenden.You can validate incoming certificate and check certificate properties against desired values using policy expressions.

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.For information about securing access to the back-end service of an API using client certificates (i.e., API Management to backend), see How to secure back-end services using client certificate authentication

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.To receive and verify client certificates over HTTP/2 in the Developer, Basic, Standard, or Premium tiers you must turn on the "Negotiate client certificate" setting on the "Custom domains" blade as shown below.

Clientzertifikat aushandeln

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.To receive and verify client certificates in the Consumption tier you must turn on the "Request client certificate" setting on the "Custom domains" blade as shown below.

Anfordern des Clientzertifikats

Prüfen des Ausstellers und des AntragstellersChecking the issuer and subject

Die unten stehenden Richtlinien konfiguriert werden, um den Aussteller und den Antragsteller eines Clientzertifikats zu prüfen:Below policies can be configured to check the issuer and subject of a client certificate:

<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.To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 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.If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

Prüfen des FingerabdrucksChecking the thumbprint

Die folgenden Richtlinien können zum Prüfen des Fingerabdrucks eines Clientzertifikats konfiguriert werden:Below policies can be configured to check the thumbprint of a client certificate:

<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.To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 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.If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

Prüfen eines Fingerabdrucks anhand von auf API Management hochgeladenen ZertifikatenChecking a thumbprint against certificates uploaded to API Management

Das folgende Beispiel zeigt, wie Sie den Fingerabdruck eines Clientzertifikats anhand von auf API Management hochgeladenen Zertifikaten prüfen können:The following example shows how to check the thumbprint of a client certificate against certificates uploaded to API Management:

<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.To disable checking certificate revocation list use context.Request.Certificate.VerifyNoRevocation() instead of context.Request.Certificate.Verify(). 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.If client certificate is self-signed, root (or intermediate) CA certificate(s) must be uploaded to API Management for context.Request.Certificate.Verify() and context.Request.Certificate.VerifyNoRevocation() to work.

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.Client certificate deadlock issue described in this article can manifest itself in several ways, e.g. requests freeze, requests result in 403 Forbidden status code after timing out, context.Request.Certificate is null. Dieses Problem wirkt sich normalerweise auf Anforderungen vom Typ POST und PUT mit einer Inhaltslänge von ca. 60 KB oder mehr aus.This problem usually affects POST and PUT requests with content length of approximately 60KB or larger. 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.To prevent this issue from occurring turn on "Negotiate client certificate" setting for desired hostnames on the "Custom domains" blade as shown in the first image of this document. Dieses Feature ist im Tarif „Verbrauch“ nicht verfügbar.This feature is not available in the Consumption tier.

Nächste SchritteNext steps