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

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 clientcertificaatverificatie voor informatie over het beveiligen van toegang tot de back-endservice van een API met behulp van clientcertificaten (API Management naar back-endservices).

Zie Verificatie en autorisatie 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 sleutelkluiscertificaten wordt aanbevolen omdat dit de beveiliging van API Management helpt verbeteren:

• Certificaten die zijn opgeslagen in sleutelkluizen, kunnen opnieuw worden gebruikt in verschillende services
• Gedetailleerd toegangsbeleid kan worden toegepast op certificaten die zijn opgeslagen in sleutelkluizen
• Certificaten die in de sleutelkluis worden bijgewerkt, worden automatisch geroteerd in API Management. Na het bijwerken in de sleutelkluis wordt een certificaat in API Management binnen 4 uur bijgewerkt. U kunt het certificaat ook handmatig vernieuwen met behulp van de 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 moet toegang hebben tot het certificaat en het wachtwoord voor beheer in een Azure-sleutelkluis of uploaden naar de API Management-service. Het certificaat moet de 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

1. Als u nog geen sleutelkluis hebt, maakt u er een. Zie Quickstart: Een sleutelkluis maken met behulp van de Azure Portal voor stappen voor het maken van een sleutelkluis.

   Als u een certificaat wilt maken of importeren in de sleutelkluis, raadpleegt u 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 sleutelkluis configureren

1. Navigeer in de portal naar uw sleutelkluis.

2. Selecteer in het linkermenu Toegangsconfiguratie en noteer het machtigingsmodel dat is geconfigureerd.

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

   Ga als volgende te werk om toegangsbeleid voor een sleutelkluis toe te voegen:
   

   1. Selecteer toegangsbeleid in het linkermenu.
   2. Selecteer + Maken op de pagina Toegangsbeleid.
   3. Selecteer op het tabblad Machtigingen onder Geheime machtigingende optie Ophalen en Weergeven en selecteer vervolgens Volgende.
   4. Zoek op het tabblad Principal , Selecteer principal, naar de resourcenaam van uw beheerde identiteit en selecteer volgende. Als u een door het systeem toegewezen identiteit gebruikt, is de principal de naam van uw API Management exemplaar.
   5. Selecteer opnieuw Volgende . 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 Rolde optie Key Vault Gebruiker van geheimen.
   4. Selecteer op het tabblad Ledende optie 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 Beoordelen en 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 om deze firewall te omzeilen in.

• Zorg ervoor dat het IP-adres van uw lokale client 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 uw clientadres blokkeren in de firewall van de sleutelkluis.

Vereisten voor het virtuele netwerk

Als het API Management-exemplaar is 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 NSG-regel (netwerkbeveiligingsgroep) om uitgaand verkeer naar de AzureKeyVault- en AzureActiveDirectory-servicetags toe te staan.

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

Een sleutelkluiscertificaat toevoegen

Zie Vereisten voor sleutelkluisintegratie.

Belangrijk

Wanneer u een sleutelkluiscertificaat toevoegt aan uw API Management-exemplaar, moet u machtigingen hebben om geheimen uit de sleutelkluis weer te geven.

Waarschuwing

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

Een sleutelkluiscertificaat toevoegen aan API Management:

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

2. Selecteer onder Beveiligingde optie Certificaten.

3. Selecteer Certificaten>+ Toevoegen.

4. Voer bij 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 uit een sleutelkluis te selecteren.

   Belangrijk

   Als u zelf een certificaat-id voor de sleutelkluis invoert, moet u ervoor zorgen dat deze geen versiegegevens bevat. Anders wordt het certificaat niet automatisch geroteerd 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 het certificaat uit de sleutelkluis op te halen en weer te geven. Als u de toegang tot de sleutelkluis nog niet hebt geconfigureerd, wordt u 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 Beveiligingde optie Certificaten.

3. Selecteer Certificaten>+ Toevoegen.

4. Voer bij Id een naam van uw keuze in.

5. Selecteer in Certificaatde optie Aangepast.

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

7. Selecteer Toevoegen.

   

8. Selecteer Opslaan.

API Management-exemplaar inschakelen om clientcertificaten te ontvangen en te verifiëren

Developer-, Basic-, Standard- of Premium-laag

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

Verbruikslaag

Als u clientcertificaten in de laag Verbruik wilt ontvangen en verifiëren, 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 validate-client-certificate 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 om een of meer kenmerken te valideren, waaronder certificaatverlener, onderwerp, vingerafdruk, of het certificaat is gevalideerd op basis van een online intrekkingslijst en andere.

Certificaatvalidatie met contextvariabelen

U kunt ook beleidsexpressies maken met de context variabele om clientcertificaten te controleren. Voorbeelden in de volgende secties tonen expressies die gebruikmaken van de context.Request.Certificate eigenschap en andere context eigenschappen.

Belangrijk

• Vanaf mei 2021 vraagt de context.Request.Certificate eigenschap het certificaat alleen aan wanneer de eigenschap van hostnameConfiguration het API Management-exemplaar is negotiateClientCertificate ingesteld op True. Is standaard negotiateClientCertificate ingesteld op False.
• 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.

De verlener en het onderwerp controleren

De onderstaande beleidsregels kunnen worden geconfigureerd om de verlener 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 het clientcertificaat zelfondertekend is, moeten basiscertificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() om te 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 het clientcertificaat zelfondertekend is, moeten basiscertificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() om te 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 het clientcertificaat zelfondertekend is, moeten basiscertificaten (of tussenliggende) CA-certificaten worden geüpload naar API Management voor context.Request.Certificate.Verify() en context.Request.Certificate.VerifyNoRevocation() om te werken.

Tip

Het impasseprobleem met clientcertificaten dat in dit artikel wordt beschreven, kan zich op verschillende manieren manifesteren, bijvoorbeeld aanvragen blokkeren, aanvragen resulteren in 403 Forbidden statuscode na een time-out, 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 dit probleem wilt voorkomen, schakelt u de instelling 'Onderhandelen over clientcertificaat' 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