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

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

  Anteckning

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

Förutsättningar för nyckelvalv-integration

1. Om du inte redan har ett nyckelvalv skapar du ett. Information om hur du skapar ett nyckelvalv finns i Snabbstart: Skapa ett nyckelvalv med Hjälp av Azure-portalen.

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

Konfigurera åtkomst till nyckelvalv

1. Gå till ditt nyckelvalv i portalen.
2. I den vänstra menyn väljer du Inställningar>Åtkomstkonfiguration. Observera 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 söker du efter resursnamnet för din hanterade identitet och väljer sedan Nästa. Om du använder en systemtilldelad identitet är huvudprincipalen namnet på din API Management-instans.
5. Välj Nästa igen. På fliken Granska + skapa väljer du Skapa.

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

Krav för Key Vault-brandvägg

Om Key Vault-brandväggen är aktiverad i nyckelvalvet måste du uppfylla följande 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 din klientadress 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:

• Aktivera en tjänstslutpunkt till Key Vault i API Management-undernätet.
• Konfigurera en NSG-regel (network security group) för att tillåta utgående trafik till tjänsttaggar för AzureKeyVault och AzureActiveDirectory.

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

Lägga till ett key vault-certifikat

Se Krav för nyckelvalvintegrering.

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 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 identitet eller en befintlig användartilldelad hanterad identitet. Mer information finns i Använda hanterade identiteter i Azure API Management.

   Anteckning

   Identiteten måste ha 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.

   

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

   

8. Välj Spara.

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, Standard eller Premium måste du aktivera inställningen Förhandla klientcertifikat på bladet Anpassad domän enligt nedan.

Förbrukning, Basic v2, Standard v2 eller Premium v2-nivå

Om du vill ta emot och verifiera klientcertifikat på nivån Förbrukning, Basic v2, Standard v2 eller Premium v2 måste du aktivera inställningen Begär klientcertifikat på bladet Anpassade domäner enligt nedan.

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.

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>

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>

Jämföra ett tumavtryck med certifikat som har laddats upp till API-hantering

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>

Relaterat innehåll

• Skydda serverdelstjänster med klientcertifikatautentisering
• Se Så här lägger du till ett anpassat CA-certifikat i Azure API Management.
• Lär dig mer om principer i API Management