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

VAN TOEPASSING OP: Alle API Management-lagen

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 stappen voor het maken van een sleutelkluis.

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

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

Toegang tot key vault configureren

1. Navigeer in de portal naar uw sleutelkluis.

2. Selecteer in het linkermenu De configuratie van Access en noteer het machtigingsmodel dat is geconfigureerd.

3. Afhankelijk van het machtigingsmodel configureert u een toegangsbeleid voor key vault of Azure RBAC-toegang voor een beheerde API Management-identiteit.

   Ga als volgende te werk om toegangsbeleid voor 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 lijst en selecteer vervolgens Volgende.
   4. Selecteer principal op het tabblad Principal, zoek 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.

   Azure RBAC-toegang configureren:
   

   1. Selecteer toegangsbeheer (IAM) in het linkermenu.
   2. Selecteer Op de pagina Toegangsbeheer (IAM) de optie Roltoewijzing toevoegen.
   3. Selecteer op het tabblad Rol de sleutelkluiscertificaatgebruiker.
   4. Selecteer Op het tabblad Leden beheerde identiteit>+ Leden selecteren.
   5. Selecteer op de pagina Beheerde identiteit selecteren de door het systeem toegewezen beheerde identiteit of een door de gebruiker toegewezen beheerde identiteit die is gekoppeld aan uw API Management-exemplaar en selecteer vervolgens Selecteren.
   6. Selecteer Controleren + toewijzen.

Vereisten voor Key Vault-firewall

Als Key Vault-firewall is ingeschakeld voor uw sleutelkluis, zijn de volgende aanvullende vereisten:

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

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

• 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 Azure Key Vault in het API Management-subnet.
• Configureer een netwerkbeveiligingsgroepregel (NSG) om uitgaand verkeer naar de AzureKeyVault- en AzureActiveDirectory-servicetags toe te staan.

Zie De netwerkconfiguratie bij het instellen van Azure API Management in een VNet voor meer informatie.

Een sleutelkluiscertificaat toevoegen

Zie Vereisten voor key vault-integratie.

Belangrijk

Wanneer u een sleutelkluiscertificaat toevoegt 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 waken 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. Blader in Azure Portal naar uw API Management-exemplaar.

2. Selecteer Onder Beveiliging certificaten.

3. Selecteer Certificaten>+ Toevoegen.

4. Voer in Id een naam van uw keuze 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 versie-informatie bevat. Anders draait het certificaat niet automatisch in API Management na een update in de sleutelkluis.

7. Selecteer in clientidentiteit een door het systeem toegewezen of een bestaande door de gebruiker toegewezen beheerde identiteit. Meer informatie over het toevoegen of wijzigen van beheerde identiteiten in uw API Management-service.

   Notitie

   De identiteit heeft machtigingen nodig om een certificaat op te halen en weer te geven 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.

   

9. Selecteer Opslaan.

Een certificaat uploaden

Een clientcertificaat uploaden naar API Management:

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

2. Selecteer Onder Beveiliging certificaten.

3. Selecteer Certificaten>+ Toevoegen.

4. Voer in Id een naam van uw keuze 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.

   

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

De laag Developer, Basic, Standard of Premium

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.

Verbruik, Basic v2, Standard v2-laag

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

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 Management-gateway beschikbaar wordt gemaakt via 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 alleen het certificaat aan wanneer de eigenschap van hostnameConfiguration het negotiateClientCertificate API Management-exemplaar wordt ingesteld op Waar. 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, gebruikt context.Request.Certificate.VerifyNoRevocation() u in plaats van context.Request.Certificate.Verify(). Als clientcertificaat zelfondertekend is, moeten basis-CA-certificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() 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, gebruikt context.Request.Certificate.VerifyNoRevocation() u in plaats van context.Request.Certificate.Verify(). Als clientcertificaat zelfondertekend is, moeten basis-CA-certificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() 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, gebruikt context.Request.Certificate.VerifyNoRevocation() u in plaats van context.Request.Certificate.Verify(). Als clientcertificaat zelfondertekend is, moeten basis-CA-certificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() werken.

Tip

Probleem met impasses van clientcertificaten die in dit artikel worden beschreven, kan zich op verschillende manieren manifesteren, bijvoorbeeld aanvragen blokkeren, aanvragen resulteren in 403 Forbidden statuscode na time-out. context.Request.Certificate null Dit probleem is meestal van invloed op POST aanvragen met PUT 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.

Volgende stappen

• Back-endservices beveiligen met clientcertificaatverificatie
• Een aangepast CA-certificaat toevoegen in Azure API Management
• Meer informatie over beleidsregels in API Management