Så skyddar du API:er genom att autentisera klientcertifikat i API Management

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

API Management ger möjlighet att skydda åtkomsten till API:er (d.v.s. klient-till-API Management) med hjälp av klientcertifikat och ömsesidig TLS-autentisering. Du kan verifiera certifikat som presenteras av klienten som ansluter och kontrollera certifikategenskaperna mot önskade värden med hjälp av principuttryck.

Information om hur du skyddar åtkomsten till serverdelstjänsten för ett API med klientcertifikat (dvs. API Management till serverdel) finns i Skydda serverdelstjänster med klientcertifikatautentisering.

En konceptuell översikt över API-auktorisering finns i Autentisering och auktorisering till API:er i API Management.

Certifikatalternativ

Vid certifikatverifiering kan API Management kontrollera mot certifikat som hanteras i din API Management-instans. Om du väljer att använda API Management för att hantera klientcertifikat har du följande alternativ:

  • Referera till ett certifikat som hanteras i Azure Key Vault
  • Lägga till en certifikatfil direkt i API Management

Du rekommenderas att använda Key Vault-certifikat eftersom det hjälper till att förbättra API Management-säkerheten:

  • Certifikat som lagras i nyckelvalv kan återanvändas mellan tjänster
  • Detaljerade åtkomstprinciper kan tillämpas på certifikat som lagras i nyckelvalv
  • Certifikat som uppdateras i nyckelvalvet roteras automatiskt i API Management. Efter uppdateringen i nyckelvalvet uppdateras ett certifikat i API Management inom 4 timmar. Du kan också uppdatera certifikatet manuellt med hjälp av Azure-portalen eller via rest-API:et för hantering.

Förutsättningar

  • Om du inte har skapat en API Management-tjänstinstans ännu kan du läsa Skapa en API Management-tjänstinstans.

  • Du behöver åtkomst till certifikatet och lösenordet för hantering i ett Azure-nyckelvalv eller ladda upp till API Management-tjänsten. Certifikatet måste vara i CER- eller PFX-format. Självsignerade certifikat tillåts.

    Om du använder ett självsignerat certifikat installerar du även betrodda rotcertifikat och mellanliggande CA-certifikat i DIN API Management-instans.

    Kommentar

    CA-certifikat för certifikatverifiering stöds inte på förbrukningsnivån.

Förutsättningar för key vault-integrering

  1. Om du inte redan har ett nyckelvalv skapar du ett. Anvisningar för hur du skapar ett nyckelvalv finns i Snabbstart: Skapa ett nyckelvalv med azure-portalen.

    Information om hur du skapar eller importerar ett certifikat till nyckelvalvet finns i Snabbstart: Ange och hämta ett certifikat från Azure Key Vault med hjälp av Azure-portalen.

  2. Aktivera en systemtilldelad eller användartilldelad hanterad identitet i API Management-instansen.

Konfigurera åtkomst till nyckelvalv

  1. I portalen navigerar du till ditt nyckelvalv.

  2. I den vänstra menyn väljer du Åtkomstkonfiguration och noterar den behörighetsmodell som har konfigurerats.

  3. Beroende på behörighetsmodellen konfigurerar du antingen en åtkomstprincip för nyckelvalvet eller Azure RBAC-åtkomst för en hanterad API Management-identitet.

    Så här lägger du till en åtkomstprincip för key vault:

    1. I den vänstra menyn väljer du Åtkomstprinciper.
    2. På sidan Åtkomstprinciper väljer du + Skapa.
    3. På fliken Behörigheter går du till Hemliga behörigheter, väljer Hämta och Lista och väljer sedan Nästa.
    4. På fliken Huvudnamn väljer du huvudnamn, söker efter resursnamnet för din hanterade identitet och väljer sedan Nästa. Om du använder en systemtilldelad identitet är huvudnamnet för din API Management-instans.
    5. Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.

    Så här konfigurerar du Azure RBAC-åtkomst:

    1. Välj Åtkomstkontroll (IAM) i den vänstra menyn.
    2. På sidan Åtkomstkontroll (IAM) väljer du Lägg till rolltilldelning.
    3. På fliken Roll väljer du Nyckelvalvshemlighetsanvändare.
    4. På fliken Medlemmar väljer du Hanterad identitet>+ Välj medlemmar.
    5. På sidan Välj hanterad identitet väljer du den systemtilldelade hanterade identiteten eller en användartilldelad hanterad identitet som är associerad med din API Management-instans och väljer sedan Välj.
    6. Välj Granska + tilldela.

Krav för Key Vault-brandvägg

Om Key Vault-brandväggen är aktiverad i nyckelvalvet är följande ytterligare krav:

  • Du måste använda API Management-instansens systemtilldelade hanterade identitet för att få åtkomst till nyckelvalvet.

  • I Key Vault-brandväggen aktiverar du alternativet Tillåt betrodda Microsoft-tjänster att kringgå den här brandväggen .

  • Se till att din lokala klient-IP-adress tillåts komma åt nyckelvalvet tillfälligt medan du väljer ett certifikat eller en hemlighet som ska läggas till i Azure API Management. Mer information finns i Konfigurera nätverksinställningar för Azure Key Vault.

    När du har slutfört konfigurationen kan du blockera klientadressen i nyckelvalvsbrandväggen.

Krav för virtuella nätverk

Om API Management-instansen distribueras i ett virtuellt nätverk konfigurerar du även följande nätverksinställningar:

Mer information finns i Nätverkskonfiguration när du konfigurerar Azure API Management i ett virtuellt nätverk.

Lägga till ett key vault-certifikat

Se Krav för key vault-integrering.

Viktigt!

När du lägger till ett key vault-certifikat i DIN API Management-instans måste du ha behörighet att lista hemligheter från nyckelvalvet.

Varning

När du använder ett nyckelvalvscertifikat i API Management bör du vara försiktig så att du inte tar bort certifikatet, nyckelvalvet eller den hanterade identitet som används för att komma åt nyckelvalvet.

Så här lägger du till ett key vault-certifikat i API Management:

  1. I Azure-portalen går du till din API Management-instans.

  2. Under Säkerhet väljer du Certifikat.

  3. Välj Certifikat>+ Lägg till.

  4. I ID anger du ett valfritt namn.

  5. I Certifikat väljer du Nyckelvalv.

  6. Ange identifieraren för ett nyckelvalvcertifikat eller välj Välj för att välja ett certifikat från ett nyckelvalv.

    Viktigt!

    Om du anger en nyckelvalvscertifikatidentifierare själv kontrollerar du att den inte har versionsinformation. Annars roteras inte certifikatet automatiskt i API Management efter en uppdatering i nyckelvalvet.

  7. I Klientidentitet väljer du en systemtilldelad eller en befintlig användartilldelad hanterad identitet. Lär dig hur du lägger till eller ändrar hanterade identiteter i API Management-tjänsten.

    Kommentar

    Identiteten behöver behörighet för att hämta och lista certifikat från nyckelvalvet. Om du inte redan har konfigurerat åtkomst till nyckelvalvet uppmanar API Management dig så att den automatiskt kan konfigurera identiteten med nödvändiga behörigheter.

  8. Markera Lägga till.

    Skärmbild av att lägga till ett key vault-certifikat i API Management i portalen.

  9. Välj Spara.

Ladda upp ett certifikat

Så här laddar du upp ett klientcertifikat till API Management:

  1. I Azure-portalen går du till din API Management-instans.

  2. Under Säkerhet väljer du Certifikat.

  3. Välj Certifikat>+ Lägg till.

  4. I ID anger du ett valfritt namn.

  5. I Certifikat väljer du Anpassad.

  6. Bläddra för att välja .pfx-certifikatfilen och ange dess lösenord.

  7. Markera Lägga till.

    Skärmbild av uppladdning av ett klientcertifikat till API Management i portalen.

  8. Välj Spara.

Kommentar

Om du bara vill använda certifikatet för att autentisera klienten med API Management kan du ladda upp en CER-fil.

Aktivera API Management-instans för att ta emot och verifiera klientcertifikat

Nivån Developer, Basic, Standard eller Premium

Om du vill ta emot och verifiera klientcertifikat via HTTP/2 på nivåerna Developer, Basic, Basic v2, Standard, Standard v2 eller Premium måste du aktivera inställningen Förhandla klientcertifikat på bladet Anpassad domän enligt nedan.

Förhandla om klientcertifikat

Förbrukningsnivå

Om du vill ta emot och verifiera klientcertifikat på förbrukningsnivån måste du aktivera inställningen Begär klientcertifikat på bladet Anpassade domäner enligt nedan.

Begära ett klientcertifikat

Princip för att verifiera klientcertifikat

Använd principen validate-client-certificate för att verifiera ett eller flera attribut för ett klientcertifikat som används för att komma åt API:er som finns i din API Management-instans.

Konfigurera principen för att verifiera ett eller flera attribut, inklusive certifikatutfärdare, ämne, tumavtryck, om certifikatet verifieras mot listan över återkallade online och andra.

Certifikatverifiering med kontextvariabler

Du kan också skapa principuttryck med variabeln context för att kontrollera klientcertifikat. Exempel i följande avsnitt visar uttryck med hjälp av context.Request.Certificate egenskapen och andra context egenskaper.

Kommentar

Ömsesidig certifikatautentisering kanske inte fungerar korrekt när API Management-gatewayens slutpunkt exponeras via Application Gateway. Det beror på att Application Gateway fungerar som en Layer 7-lastbalanserare och upprättar en distinkt SSL-anslutning med serverdels-API Management-tjänsten. Därför vidarebefordras inte certifikatet som bifogas av klienten i den första HTTP-begäran till APIM. Men som en lösning kan du överföra certifikatet med hjälp av alternativet servervariabler. Detaljerade anvisningar finns i Servervariabler för ömsesidig autentisering.

Viktigt!

  • Från och med maj 2021 context.Request.Certificate begär egenskapen endast certifikatet när API Management-instansens hostnameConfigurationnegotiateClientCertificate anger egenskapen till True. Som standard negotiateClientCertificate är värdet Falskt.
  • Om TLS-omförhandling har inaktiverats i klienten kan TLS-fel visas när du begär certifikatet med hjälp av context.Request.Certificate egenskapen . Om detta inträffar aktiverar du TLS-omförhandlingsinställningar i klienten.
  • Certifieringsförhandling stöds inte på API Management v2-nivåerna.

Kontrollera utfärdaren och ämnet

Nedan kan principer konfigureras för att kontrollera utfärdaren och ämnet för ett klientcertifikat:

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

Kommentar

Om du vill inaktivera kontrollen av context.Request.Certificate.Verify()listan över återkallade certifikat använder du context.Request.Certificate.VerifyNoRevocation() i stället för . Om klientcertifikatet är självsignerat måste rotcertifikatutfärdarcertifikat (eller mellanliggande) CA-certifikat laddas upp till API Management för context.Request.Certificate.Verify() och context.Request.Certificate.VerifyNoRevocation() fungera.

Kontrollera tumavtrycket

Nedan kan principer konfigureras för att kontrollera tumavtrycket för ett klientcertifikat:

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

Kommentar

Om du vill inaktivera kontrollen av context.Request.Certificate.Verify()listan över återkallade certifikat använder du context.Request.Certificate.VerifyNoRevocation() i stället för . Om klientcertifikatet är självsignerat måste rotcertifikatutfärdarcertifikat (eller mellanliggande) CA-certifikat laddas upp till API Management för context.Request.Certificate.Verify() och context.Request.Certificate.VerifyNoRevocation() fungera.

Kontrollera ett tumavtryck mot certifikat som laddats upp till API Management

I följande exempel visas hur du kontrollerar tumavtrycket för ett klientcertifikat mot certifikat som laddats upp till 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>

Kommentar

Om du vill inaktivera kontrollen av context.Request.Certificate.Verify()listan över återkallade certifikat använder du context.Request.Certificate.VerifyNoRevocation() i stället för . Om klientcertifikatet är självsignerat måste rotcertifikatutfärdarcertifikat (eller mellanliggande) CA-certifikat laddas upp till API Management för context.Request.Certificate.Verify() och context.Request.Certificate.VerifyNoRevocation() fungera.

Dricks

Problem med klientcertifikatets dödläge som beskrivs i den här artikeln kan visa sig på flera sätt, t.ex. att begäranden fryser, att begäranden resulterar i 403 Forbidden statuskod efter tidsgränsen context.Request.Certificate är null. Det här problemet påverkar POST vanligtvis och PUT begäranden med en innehållslängd på cirka 60 KB eller större. För att förhindra att det här problemet uppstår aktiverar du inställningen "Förhandla om klientcertifikat" för önskade värdnamn på bladet "Anpassade domäner", som visas i den första bilden i det här dokumentet. Den här funktionen är inte tillgänglig på förbrukningsnivån.

Nästa steg