Delen via

API's beveiligen met behulp van verificatie via clientcertificaten in API Management

VAN TOEPASSING OP: Alle niveaus van API-beheer

API Management biedt de mogelijkheid om de toegang tot API's (dat wil gezegd, client naar API Management) te beveiligen met behulp van clientcertificaten en wederzijdse TLS-verificatie. U kunt certificaten valideren die worden gepresenteerd door de verbindingsclient en certificaateigenschappen controleren op basis van gewenste waarden met behulp van beleidsexpressies.

Zie Back-endservices beveiligen met behulp van clientcertificaatverificatie voor informatie over het beveiligen van de toegang tot de back-endservice van een API met behulp van clientcertificaten (dat wil gezegd API Management naar back-end).

Zie Verificatie en autorisatie voor API's in API Management voor een conceptueel overzicht van API-autorisatie.

Certificaatopties

Voor certificaatvalidatie kunt API Management controleren op certificaten die worden beheerd in uw API Management-exemplaar. Als u ervoor kiest om API Management te gebruiken om clientcertificaten te beheren, hebt u de volgende opties:

  • Verwijzen naar een certificaat dat wordt beheerd in Azure Key Vault
  • Een certificaatbestand rechtstreeks toevoegen in API Management

Het gebruik van key vault-certificaten wordt aanbevolen omdat hiermee de beveiliging van API Management wordt verbeterd:

  • Certificaten die zijn opgeslagen in sleutelkluizen kunnen opnieuw worden gebruikt in services
  • Gedetailleerde toegangsbeleidsregels kunnen worden toegepast op certificaten die zijn opgeslagen in sleutelkluizen
  • Certificaten die worden bijgewerkt in de sleutelkluis, worden automatisch geroteerd in API Management. Na de update in de sleutelkluis wordt een certificaat in API Management binnen 4 uur bijgewerkt. U kunt het certificaat ook handmatig vernieuwen met behulp van Azure Portal of via de REST API voor beheer.

Vereisten

  • Zie Een API Management-service-exemplaar maken als u nog geen API Management-service-exemplaar hebt gemaakt.

  • U hebt toegang nodig tot het certificaat en het wachtwoord voor beheer in een Azure-sleutelkluis of uploaden naar de API Management-service. Het certificaat moet de CER- of PFX-indeling hebben. Zelfondertekende certificaten zijn toegestaan.

    Als u een zelfondertekend certificaat gebruikt, installeert u ook vertrouwde basis- en tussenliggende CA-certificaten in uw API Management-exemplaar.

    Notitie

    CA-certificaten voor certificaatvalidatie worden niet ondersteund in de verbruikslaag.

Vereisten voor key vault-integratie

Notitie

Deze functie is momenteel niet beschikbaar in werkruimten.

  1. Als u nog geen sleutelkluis hebt, maakt u er een. Zie quickstart: Een sleutelkluis maken met behulp van Azure Portal voor meer informatie over het maken van een sleutelkluis.

  2. Schakel een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit in API Management in.

Toegang tot key vault configureren

  1. Ga in de portal naar uw Key Vault.
  2. Selecteer in het linkermenu De configuratie van Access. Let op het machtigingsmodel dat is geconfigureerd.
  3. Afhankelijk van het machtigingsmodel configureert u een key vault-toegangsbeleid of Azure RBAC-toegang voor een beheerde identiteit binnen API Management.

Om een toegangsbeleid voor een key vault toe te voegen:

  1. Selecteer toegangsbeleid in het linkermenu.
  2. Selecteer + Maken op de pagina Toegangsbeleid.
  3. Selecteer Op het tabblad Machtigingen onder Geheime machtigingen de optie Ophalen en weergeven en selecteer vervolgens Volgende.
  4. Klik op het tabblad Principal, selecteer Principal, zoek naar de resourcenaam van uw beheerde identiteit en selecteer Vervolgens Volgende. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management-exemplaar.
  5. Selecteer Volgende opnieuw. Selecteer op het tabblad Beoordelen en maken de optie Maken.

Als u een certificaat in de sleutelkluis wilt maken of een certificaat wilt importeren in de sleutelkluis, raadpleegt u quickstart: Een certificaat instellen en ophalen uit Azure Key Vault met behulp van de Azure-portal.

Vereisten voor Key Vault-firewall

Als Key Vault-firewall is ingeschakeld voor uw sleutelkluis, moet u aan deze vereisten voldoen:

  • U moet de door het systeem toegewezen beheerde identiteit van het API Management-exemplaar gebruiken om toegang te krijgen tot de sleutelkluis.

  • Schakel in de Key Vault-firewall de optie Vertrouwde Microsoft-services toestaan om deze firewall te omzeilen in.

  • Zorg ervoor dat uw lokale client-IP-adres tijdelijk toegang heeft tot de sleutelkluis terwijl u een certificaat of geheim selecteert om toe te voegen aan Azure API Management. Zie Azure Key Vault-netwerkinstellingen configureren voor meer informatie.

    Nadat u de configuratie hebt voltooid, kunt u het clientadres blokkeren in de firewall van de sleutelkluis.

Vereisten voor het virtuele netwerk

Als het API Management-exemplaar wordt geïmplementeerd in een virtueel netwerk, configureert u ook de volgende netwerkinstellingen:

  • Schakel een service-eindpunt in voor Key Vault in het API Management-subnet.
  • Configureer een netwerkbeveiligingsgroepregel (NSG) om uitgaand verkeer naar de servicetags AzureKeyVault en AzureActiveDirectory toe te staan.

Zie De netwerkconfiguratie bij het instellen van API Management in een virtueel netwerk voor meer informatie.

Een Key Vault-certificaat toevoegen

Zie Vereisten voor key vault-integratie.

Belangrijk

Als u een sleutelkluiscertificaat wilt toevoegen aan uw API Management-exemplaar, moet u gemachtigd zijn om geheimen uit de sleutelkluis weer te geven.

Let op

Wanneer u een sleutelkluiscertificaat in API Management gebruikt, moet u ervoor zorgen dat u het certificaat, de sleutelkluis of de beheerde identiteit die wordt gebruikt voor toegang tot de sleutelkluis niet verwijdert.

Een sleutelkluiscertificaat toevoegen aan API Management:

  1. Ga in Azure Portal naar uw API Management-exemplaar.

  2. Onder Beveiliging, selecteer Certificaten.

  3. Selecteer Certificaten>+ Toevoegen.

  4. Voer in Id een naam in.

  5. Selecteer sleutelkluis in Certificaat.

  6. Voer de id van een sleutelkluiscertificaat in of kies Selecteren om een certificaat in een sleutelkluis te selecteren.

    Belangrijk

    Als u zelf een sleutelkluiscertificaat-id invoert, moet u ervoor zorgen dat deze geen versiegegevens bevat. Anders wordt het certificaat niet automatisch vernieuwd binnen API Management na een update in de sleutelkluis.

  7. Selecteer in clientidentiteit een door het systeem toegewezen identiteit of een bestaande door de gebruiker toegewezen beheerde identiteit. Zie Beheerde identiteiten gebruiken in Azure API Management voor meer informatie.

    Notitie

    De identiteit moet machtigingen hebben om certificaten op te halen en te bekijken uit de sleutelkluis. Als u nog geen toegang tot de sleutelkluis hebt geconfigureerd, wordt u door API Management gevraagd om de identiteit automatisch te configureren met de benodigde machtigingen.

  8. Selecteer Toevoegen.

    Schermopname van het toevoegen van een sleutelkluiscertificaat aan API Management in de portal.

  9. Selecteer Opslaan.

Een certificaat uploaden

Een clientcertificaat uploaden naar API Management:

  1. Ga in Azure Portal naar uw API Management-exemplaar.

  2. Onder Beveiliging, selecteer Certificaten.

  3. Selecteer Certificaten>+ Toevoegen.

  4. Voer in Id een naam in.

  5. Selecteer Aangepast in Certificaat.

  6. Blader om het PFX-bestand van het certificaat te selecteren en voer het bijbehorende wachtwoord in.

  7. Selecteer Toevoegen.

    Schermopname van het uploaden van een clientcertificaat naar API Management in de portal.

  8. Selecteer Opslaan.

Notitie

Als u alleen het certificaat wilt gebruiken om de client te verifiëren met API Management, kunt u een CER-bestand uploaden.

API Management-exemplaar inschakelen voor het ontvangen en verifiëren van clientcertificaten

Developer, Basic, Standard of Premium abonnementsniveau

Als u clientcertificaten wilt ontvangen en controleren via HTTP/2 in de lagen Developer, Basic, Standard of Premium, moet u de instelling Negotiate-clientcertificaat inschakelen op de blade Aangepast domein , zoals hieronder wordt weergegeven.

Onderhandel het client-certificaat

Verbruik, Basic v2, Standard v2 of Premium v2-laag

Als u clientcertificaten wilt ontvangen en controleren in de laag Consumption, Basic v2, Standard v2 of Premium v2, moet u de instelling Clientcertificaat aanvragen inschakelen op de blade Aangepaste domeinen , zoals hieronder wordt weergegeven.

Clientcertificaat aanvragen

Beleid voor het valideren van clientcertificaten

Gebruik het beleid voor validatieclientcertificaten om een of meer kenmerken te valideren van een clientcertificaat dat wordt gebruikt voor toegang tot API's die worden gehost in uw API Management-exemplaar.

Configureer het beleid voor het valideren van een of meer kenmerken, waaronder certificaatverlener, onderwerp, vingerafdruk, of het certificaat wordt gevalideerd op basis van de onlineintrekkingslijst en andere.

Certificaatvalidatie met contextvariabelen

U kunt ook beleidsexpressies maken met de context variabele om clientcertificaten te controleren. In de volgende secties ziet u expressies met behulp van de context.Request.Certificate eigenschap en andere context eigenschappen.

Notitie

Wederzijdse certificaatverificatie werkt mogelijk niet correct wanneer het eindpunt van de API-beheer gateway beschikbaar wordt gemaakt via de Application Gateway. Dit komt doordat Application Gateway fungeert als een load balancer van Laag 7, waarbij een afzonderlijke SSL-verbinding tot stand wordt gebracht met de back-end-API Management-service. Daarom wordt het certificaat dat door de client in de eerste HTTP-aanvraag is gekoppeld, niet doorgestuurd naar APIM. Als tijdelijke oplossing kunt u het certificaat echter verzenden met behulp van de optie servervariabelen. Raadpleeg wederzijdse verificatieservervariabelen voor gedetailleerde instructies.

Belangrijk

  • Vanaf mei 2021 vraagt de context.Request.Certificate-eigenschap het certificaat alleen aan wanneer de hostnameConfiguration-eigenschap van het API Management-exemplaar van negotiateClientCertificate op True is ingesteld. negotiateClientCertificate Standaard is dit ingesteld op Onwaar.
  • Als TLS-heronderhandeling is uitgeschakeld in uw client, ziet u mogelijk TLS-fouten bij het aanvragen van het certificaat met behulp van de context.Request.Certificate eigenschap. Als dit gebeurt, schakelt u TLS-heronderhandelingsinstellingen in de client in.
  • Heronderhandeling van certificering wordt niet ondersteund in de API Management v2-lagen.

De uitgever en het onderwerp controleren

Onderstaande beleidsregels kunnen worden geconfigureerd om de uitgever en het onderwerp van een clientcertificaat te controleren:

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

Notitie

Als u het controleren van de certificaatintrekkingslijst wilt uitschakelen, gebruik context.Request.Certificate.VerifyNoRevocation() in plaats van context.Request.Certificate.Verify(). Als het clientcertificaat zelfondertekend is, moeten root-CA-certificaten (of tussenliggende CA-certificaten) naar API Management worden geüpload om context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() te laten werken.

De vingerafdruk controleren

Onderstaand beleid kan worden geconfigureerd om de vingerafdruk van een clientcertificaat te controleren:

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

Notitie

Als u het controleren van de certificaatintrekkingslijst wilt uitschakelen, gebruik context.Request.Certificate.VerifyNoRevocation() in plaats van context.Request.Certificate.Verify(). Als het clientcertificaat zelfondertekend is, moeten root-CA-certificaten (of tussenliggende CA-certificaten) naar API Management worden geüpload om context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() te laten werken.

Een vingerafdruk controleren op certificaten die zijn geüpload naar API Management

In het volgende voorbeeld ziet u hoe u de vingerafdruk van een clientcertificaat controleert op certificaten die zijn geüpload naar 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>

Notitie

Als u het controleren van de certificaatintrekkingslijst wilt uitschakelen, gebruik context.Request.Certificate.VerifyNoRevocation() in plaats van context.Request.Certificate.Verify(). Als het clientcertificaat zelfondertekend is, moeten root-CA-certificaten (of tussenliggende CA-certificaten) naar API Management worden geüpload om context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() te laten werken.

Aanbeveling

Probleem met impasses van clientcertificaten dat in dit artikel wordt beschreven, kan zich op verschillende manieren manifesteren, bijvoorbeeld wanneer verzoeken vastlopen, verzoeken na een time-out resulteren in 403 Forbidden-statuscode, en context.Request.Certificate is null. Dit probleem is meestal van invloed op POST en PUT aanvragen met een inhoudslengte van ongeveer 60 kB of groter. Als u wilt voorkomen dat dit probleem optreedt, schakelt u de instelling 'Clientcertificaat onderhandelen' in voor de gewenste hostnamen op de blade Aangepaste domeinen, zoals wordt weergegeven in de eerste afbeelding van dit document. Deze functie is niet beschikbaar in de verbruikslaag.

Verwante inhoud