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

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 certifikát podepsaný svým držitelem, nainstalujte do instance služby API Management také důvěryhodné certifikáty 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 na úrovni Consumption.

Požadavky na integraci trezoru klíčů

Poznámka:

V současné době tato funkce není dostupná v pracovních prostorech.

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

   Pokud chcete vytvořit 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.

2. Povolte spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem v instanci služby API Management.

Konfigurace přístupu k trezoru klíčů

1. Na portálu přejděte do trezoru klíčů.

2. V nabídce vlevo vyberte konfiguraci accessu a poznamenejte si nakonfigurovaný model 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.

   Přidání zásady přístupu 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 části Oprávnění vyberte Získat a Seznam a pak vyberte Další.
   4. Na kartě Objekt zabezpečení vyberte objekt zabezpečení, vyhledejte název prostředku vaší spravované identity a pak vyberte Další. Pokud používáte identitu přiřazenou systémem, objekt zabezpečení je název vaší instance služby API Management.
   5. Znovu vyberte Další . Na kartě Revize a vytvoření vyberte Vytvořit.

   Konfigurace přístupu Azure RBAC:
   

   1. V nabídce vlevo vyberte Řízení přístupu (IAM).
   2. Na stránce Řízení přístupu (IAM) vyberte Přidat přiřazení role.
   3. Na kartě Role vyberte uživatele certifikátu služby Key Vault.
   4. Na kartě Členové vyberte Spravovaná identita> + Vybrat členy.
   5. Na stránce Vybrat spravovanou identitu vyberte spravovanou identitu přiřazenou systémem nebo spravovanou identitu přiřazenou uživatelem přidruženou k vaší instanci služby API Management a pak vyberte Vybrat.
   6. Vyberte Zkontrolovat + přiřadit.

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

Pokud je ve vašem trezoru klíčů povolená brána firewall služby Key Vault, jsou další požadavky:

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

• V bráně firewall služby Key Vault povolte, aby tuto možnost brány firewall vynechala důvěryhodná služba Microsoftu.

• 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íčů.

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 do služby Azure Key Vault v podsíti služby 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 Azure API Management ve virtuální síti.

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

Viz Požadavky pro integraci trezoru klíčů.

Důležité

Při přidávání certifikátu trezoru klíčů do instance služby API Management 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 používanou pro přístup k trezoru klíčů neodstraňovat.

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

1. Na webu Azure Portal přejděte k vaší instanci 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 podle vašeho výběru.

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 spravovanou identitu přiřazenou systémem nebo existující spravovanou identitu přiřazenou uživatelem. Naučte se přidávat nebo upravovat spravované identity ve službě API Management.

   Poznámka:

   Identita potřebuje oprávnění k získání a výpisu certifikátu z trezoru 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 k vaší instanci 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 podle vašeho výběru.

5. V části Certifikát 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 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 tématu Proměnné serveru vzájemného ověřování.

Důležité

• Od května 2021 vlastnost context.Request.Certificate požaduje pouze certifikát, když instance hostnameConfiguration SLUŽBY API Management nastaví negotiateClientCertificate vlastnost 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 předmětu

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 certifikáty kořenové (nebo zprostředkující) certifikační autority nahrané do služby API Management, aby context.Request.Certificate.Verify() fungovaly a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Kontrola kryptografického otisku

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 certifikáty kořenové (nebo zprostředkující) certifikační autority nahrané do služby API Management, aby context.Request.Certificate.Verify() fungovaly a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Kontrola kryptografického otisku vůči certifikátům nahraným do služby 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 certifikáty kořenové (nebo zprostředkující) certifikační autority nahrané do služby API Management, aby context.Request.Certificate.Verify() fungovaly a context.Request.Certificate.VerifyNoRevocation() fungovaly.

Tip

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 zablokuje, požadavky po vypršení časového limitu context.Request.Certificate nullzpůsobí 403 Forbidden stavový kód. 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.

Další kroky

• Zabezpečení back-endových služeb pomocí ověřování klientských certifikátů
• Postup 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