Postup zabezpečení rozhraní API s využitím ověřování pomocí klientských certifikátů ve službě API Management

PLATÍ PRO: Všechny úrovně služby API Management

API Management nabízí možnost zabezpečit přístup k rozhraním API (tj. z klienta ke službě API Management) s využitím klientských certifikátů a vzájemného ověřování TLS. S využitím výrazů zásad můžete ověřovat certifikáty předložené připojujícím se klientem a porovnávat vlastnosti certifikátů s požadovanými hodnotami.

Informace o zabezpečení přístupu k back-endové službě rozhraní API pomocí klientských certifikátů (tj. API Management k back-endu) najdete v tématu Postup zabezpečení back-endových služeb pomocí ověřování klientských certifikátů.

Koncepční přehled autorizace rozhraní API najdete v tématu Ověřování a autorizace pro rozhraní API ve službě API Management.

Možnosti certifikátu

Při ověřování certifikátů může služba API Management kontrolovat certifikáty spravované ve vaší instanci služby API Management. Pokud se rozhodnete ke správě klientských certifikátů využít službu API Management, máte následující možnosti:

• Odkaz na certifikát spravovaný ve službě Azure Key Vault
• Přidání souboru certifikátu přímo do služby API Management

Poznámka:

V současné době není integrace s trezorem klíčů pro tento scénář dostupná v pracovních prostorech.

Použití certifikátů trezoru klíčů se doporučuje, protože pomáhá zlepšit zabezpečení služby API Management:

• Certifikáty uložené v trezorech klíčů je možné opakovaně používat napříč službami.
• Podrobné zásady přístupu se dají použít na certifikáty uložené v trezorech klíčů.
• Certifikáty aktualizované v trezoru klíčů se ve službě API Management automaticky obměňují. Po aktualizaci v trezoru klíčů se certifikát ve službě API Management aktualizuje do 4 hodin. Certifikát můžete aktualizovat také ručně pomocí webu Azure Portal nebo přes rozhraní REST API pro správu.

Požadavky

• Pokud jste ještě nevytvořili instanci služby API Management, přečtěte si téma Vytvoření instance služby API Management.

• Potřebujete přístup k certifikátu a heslu pro správu v trezoru klíčů Azure nebo nahrát do služby API Management. Certifikát musí být ve formátu CER nebo PFX. Certifikáty podepsané svým držitelem jsou povolené.

  Pokud používáte samopodepsaný certifikát, nainstalujte v instanci vaší služby API Management také certifikáty důvěryhodné kořenové a zprostředkující certifikační autority.

  Poznámka:

  Certifikáty certifikační autority pro ověřování certifikátů nejsou podporovány v úrovni Consumption.

Požadavky na integraci trezoru klíčů

1. Pokud ještě trezor klíčů nemáte, vytvořte ho. Informace o vytvoření trezoru klíčů najdete v tématu Rychlý start: Vytvoření trezoru klíčů pomocí webu Azure Portal.

2. Povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem ve službě API Management.

Konfigurace přístupu k trezoru klíčů

1. Na portálu přejděte do trezoru klíčů.
2. V nabídce vlevo vyberte Nastavení>konfigurace přístupu. Všimněte si nakonfigurovaného modelu oprávnění .
3. V závislosti na modelu oprávnění nakonfigurujte zásady přístupu trezoru klíčů nebo přístup Azure RBAC pro spravovanou identitu služby API Management.

Chcete-li přidat zásadu přístupu k trezoru klíčů:

1. V nabídce vlevo vyberte Zásady přístupu.
2. Na stránce Zásady přístupu vyberte + Vytvořit.
3. Na kartě Oprávnění v sekci Oprávnění pro tajné vyberte Získat a Vypsat a pak vyberte Další.
4. Na kartě Hlavní vyhledejte název prostředku vaší spravované identity a poté vyberte Další. Pokud používáte identitu přiřazenou systémem, identita je název vaší instance služby API Management.
5. Znovu vyberte Další . Na kartě Revize + vytvoření vyberte Vytvořit.

Pokud chcete vytvořit certifikát v trezoru klíčů nebo importovat certifikát do trezoru klíčů, přečtěte si článek Rychlý start: Nastavení a načtení certifikátu ze služby Azure Key Vault pomocí webu Azure Portal.

Požadavky na bránu firewall služby Key Vault

Pokud je ve vašem klíčovém trezoru povolená brána firewall služby Key Vault, je potřeba splňovat následující požadavky:

• Pro přístup k trezoru klíčů musíte použít spravovanou identitu přiřazenou systémem instance služby API Management.

• Ujistěte se, že vaše instance služby API Management má přímé síťové spojení s trezorem klíčů. V závislosti na vašich scénářích nakonfigurujte v trezoru klíčů jednu z následujících možností síťového přístupu:

  • Povolit veřejný přístup ze všech sítí.

  • Nastavte pravidlo zabezpečení sítě, které povolí provoz služby API Management na základě IP adresy nebo připojení k virtuální síti.

  • Zabezpečení provozu ze služby API Management s využitím připojení služby Private Link

  • K zabezpečení trezoru klíčů a povolení provozu ze služby API Management použijte hraniční síť zabezpečení sítě .

• Ujistěte se, že vaše IP adresa místního klienta má povolený přístup k trezoru klíčů dočasně, když vyberete certifikát nebo tajný klíč pro přidání do služby Azure API Management. Další informace najdete v tématu Konfigurace nastavení sítě služby Azure Key Vault.

  Po dokončení konfigurace můžete zablokovat adresu klienta v bráně firewall trezoru klíčů.

Důležité

Od března 2026 již nebude podporováno navázání důvěryhodného připojení ke službě Azure Key Vault ze služby API Management pomocí povolení nastavení brány firewall trezoru klíčů, které umožňuje důvěryhodným službám Microsoftu toto nastavení obejít. Pokud chcete dál používat službu Key Vault se službou API Management po této změně, ujistěte se, že jste zvolili podporovanou možnost síťového přístupu, jak je popsáno výše. Další informace.

Požadavky na virtuální síť

Pokud je instance služby API Management nasazená ve virtuální síti, nakonfigurujte také následující nastavení sítě:

• Povolte koncový bod služby Key Vault na podsíti API Management.
• Nakonfigurujte pravidlo skupiny zabezpečení sítě (NSG), které povolí odchozí provoz do značek služeb AzureKeyVault a AzureActiveDirectory.

Podrobnosti najdete v tématu Konfigurace sítě při nastavování služby API Management ve virtuální síti.

Přidání certifikátu trezoru klíčů

Viz Požadavky pro integraci úložiště klíčů.

Důležité

Pokud chcete do instance služby API Management přidat certifikát trezoru klíčů, musíte mít oprávnění k výpisu tajných kódů z trezoru klíčů.

Upozornění

Při použití certifikátu trezoru klíčů ve službě API Management dávejte pozor, abyste certifikát, trezor klíčů nebo spravovanou identitu, která se používá pro přístup k trezoru klíčů, neodstraňujte.

Přidání certifikátu trezoru klíčů do služby API Management:

1. Na webu Azure Portal přejděte do vaší instance služby API Management.

2. V části Zabezpečení vyberte Certifikáty.

3. Vyberte Certifikáty>+ Přidat.

4. Do pole ID zadejte název.

5. V certifikátu vyberte Trezor klíčů.

6. Zadejte identifikátor certifikátu trezoru klíčů nebo zvolte Vybrat a vyberte certifikát z trezoru klíčů.

   Důležité

   Pokud zadáte identifikátor certifikátu trezoru klíčů sami, ujistěte se, že neobsahuje informace o verzi. V opačném případě se certifikát nebude automaticky otáčet ve službě API Management po aktualizaci v trezoru klíčů.

7. V části Identita klienta vyberte identitu přiřazenou systémem nebo existující spravovanou identitu přiřazenou uživatelem. Další informace najdete v tématu Použití spravovaných identit ve službě Azure API Management.

   Poznámka:

   Identita musí mít oprávnění k získání a zobrazení certifikátů z úložiště klíčů. Pokud jste ještě nenakonfigurovali přístup k trezoru klíčů, služba API Management vás vyzve, aby automaticky nakonfigurovala identitu s potřebnými oprávněními.

8. Vyberte Přidat.

   

9. Zvolte Uložit.

Nahrát certifikát

Nahrání klientského certifikátu do služby API Management:

1. Na webu Azure Portal přejděte do vaší instance služby API Management.

2. V části Zabezpečení vyberte Certifikáty.

3. Vyberte Certifikáty>+ Přidat.

4. Do pole ID zadejte název.

5. V Certifikátu vyberte Vlastní.

6. Vyhledejte soubor .pfx certifikátu a zadejte jeho heslo.

7. Vyberte Přidat.

   

8. Zvolte Uložit.

Poznámka:

Pokud chcete certifikát použít jenom k ověření klienta pomocí služby API Management, můžete nahrát soubor CER.

Povolení instance služby API Management pro příjem a ověření klientských certifikátů

Úroveň Developer, Basic, Standard nebo Premium

Pokud chcete přijímat a ověřovat klientské certifikáty přes protokol HTTP/2 na úrovních Developer, Basic, Standard nebo Premium, musíte v okně Vlastní doména povolit nastavení klientského certifikátu Negotiate, jak je znázorněno níže.

Consumption, Basic v2, Standard v2 nebo úroveň Premium v2

Pokud chcete přijímat a ověřovat klientské certifikáty v úrovni Consumption, Basic v2, Standard v2 nebo Premium v2, musíte v okně Vlastní domény povolit nastavení vyžádat klientský certifikát, jak je znázorněno níže.

Zásady ověřování klientských certifikátů

Pomocí zásad validate-client-certificate ověřte jeden nebo více atributů klientského certifikátu používaného pro přístup k rozhraním API hostovaným v instanci služby API Management.

Nakonfigurujte zásadu tak, aby ověřila jeden nebo více atributů, včetně vystavitele certifikátu, předmětu, kryptografického otisku, jestli se certifikát ověřuje v seznamu odvolaných certifikátů online a dalších.

Ověření certifikátu s kontextovými proměnnými

Můžete také vytvořit výrazy zásad s proměnnou context pro kontrolu klientských certifikátů. Příklady v následujících částech ukazují výrazy používající context.Request.Certificate vlastnost a další context vlastnosti.

Poznámka:

Při zveřejnění koncového bodu brány služby API Management prostřednictvím služby Application Gateway nemusí správně fungovat vzájemné ověřování certifikátů. Důvodem je to, že Služba Application Gateway funguje jako nástroj pro vyrovnávání zatížení vrstvy 7 a vytváří jedinečné připojení SSL se službou API Management back-endu. V důsledku toho se certifikát připojený klientem v počátečním požadavku HTTP nepředá do služby APIM. Jako alternativní řešení ale můžete certifikát přenést pomocí možnosti proměnných serveru. Podrobné pokyny najdete v Mutual Authentication Server Variables.

Důležité

• Od května 2021 vlastnost context.Request.Certificate požaduje certifikát pouze tehdy, když instance služby API Management nastaví vlastnost hostnameConfiguration na True. Ve výchozím nastavení negotiateClientCertificate je nastavená hodnota False.
• Pokud je v klientovi zakázané nové vyjednávání protokolu TLS, může se při vyžádání certifikátu pomocí context.Request.Certificate vlastnosti zobrazit chyby TLS. Pokud k tomu dojde, povolte v klientovi nastavení opětovného vyjednávání protokolu TLS.
• Opětovné vyjednávání o certifikaci není podporováno v úrovních služby API Management v2.

Kontrola vystavitele a subjektu

Následující zásady je možné nakonfigurovat tak, aby kontrolovaly vystavitele a předmět klientského certifikátu:

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

Poznámka:

Chcete-li zakázat kontrolu seznamu odvolaných certifikátů, použijte context.Request.Certificate.VerifyNoRevocation() místo context.Request.Certificate.Verify(). Pokud je klientský certifikát podepsaný svým držitelem, musí být kořenové (nebo zprostředkující) certifikáty CA nahrány do služby API Management, aby context.Request.Certificate.Verify() a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Kontrola otisku palce

Následující zásady je možné nakonfigurovat tak, aby kontrolovaly kryptografický otisk klientského certifikátu:

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

Poznámka:

Chcete-li zakázat kontrolu seznamu odvolaných certifikátů, použijte context.Request.Certificate.VerifyNoRevocation() místo context.Request.Certificate.Verify(). Pokud je klientský certifikát podepsaný svým držitelem, musí být kořenové (nebo zprostředkující) certifikáty CA nahrány do služby API Management, aby context.Request.Certificate.Verify() a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Kontrola otisku prstu vůči certifikátům nahraným do API Management

Následující příklad ukazuje, jak zkontrolovat kryptografický otisk klientského certifikátu proti certifikátům nahraným do služby 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>

Poznámka:

Chcete-li zakázat kontrolu seznamu odvolaných certifikátů, použijte context.Request.Certificate.VerifyNoRevocation() místo context.Request.Certificate.Verify(). Pokud je klientský certifikát podepsaný svým držitelem, musí být kořenové (nebo zprostředkující) certifikáty CA nahrány do služby API Management, aby context.Request.Certificate.Verify() a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Návod

Problém zablokování klientského certifikátu, popsaný v tomto článku, se může projevit několika způsoby, například požadavky se zablokují, nebo požadavky po vypršení časového limitu způsobí 403 Forbidden stavový kód context.Request.Certificatenull. Tento problém obvykle ovlivňuje POST a PUT požadavky s délkou obsahu přibližně 60 kB nebo větší. Chcete-li zabránit tomu, aby k tomuto problému docházelo, zapněte nastavení Vyjednat klientský certifikát pro požadované názvy hostitelů v okně Vlastní domény, jak je znázorněno na prvním obrázku tohoto dokumentu. Tato funkce není k dispozici ve vrstvě Consumption.

Související obsah

• Zabezpečení back-endových služeb pomocí ověřování klientských certifikátů
• Přidání vlastního certifikátu certifikační autority ve službě Azure API Management
• Informace o zásadách ve službě API Management