Como proteger APIs usando a autenticação de certificado do cliente no Gerenciamento de API

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

O Gerenciamento de API oferece a capacidade de proteger o acesso a APIs (ou seja, do cliente para o Gerenciamento de API) usando certificados de cliente e autenticação TLS mútua. Você pode validar os certificados apresentados pelo cliente que está se conectando e verificar as propriedades do certificado em relação aos valores desejados usando expressões de política.

Para obter informações de como proteger o acesso ao serviço de back-end de uma API usando certificados do cliente (isto é, do Gerenciamento de API para o back-end), veja Como proteger serviços de back-end usando autenticação de certificado do cliente.

Para obter uma visão geral conceitual da autorização da API, consulte Autenticação e autorização no Gerenciamento de API.

Opções de certificado

Para validação de certificado, o Gerenciamento de API pode verificar os certificados gerenciados na instância de Gerenciamento de API. Se você optar por usar o Gerenciamento de API para gerenciar certificados de cliente, terá as seguintes opções:

  • Referenciar um certificado gerenciado no Azure Key Vault
  • Adicionar um arquivo de certificado diretamente no Gerenciamento de API

O uso de certificados do cofre de chaves é recomendado porque ajuda a melhorar a segurança do Gerenciamento de API:

  • Os certificados armazenados em cofres de chaves podem ser reutilizados entre os serviços
  • É possível aplicar políticas de acesso granular a certificados armazenados em cofres de chaves
  • Os certificados atualizados no cofre de chaves são automaticamente girados no Gerenciamento de API. Após a atualização no cofre de chaves, um certificado no Gerenciamento de API é atualizado dentro de 4 horas. Você também pode atualizar manualmente o certificado usando o portal do Azure ou por meio da API REST de gerenciamento.

Pré-requisitos

  • Se você ainda não tiver criado uma instância de serviço do Gerenciamento de API, veja Criar uma instância de serviço do Gerenciamento de API.

  • Você precisa ter acesso ao certificado e à senha para o gerenciamento em um cofre de chaves do Azure ou fazer upload para o serviço Gerenciamento de API. O certificado deve estar no formato CER ou PFX. Os certificados autoassinados são permitidos.

    Se você usar um certificado autoassinado, instale também certificados de AC confiáveis e intermediários na instância de Gerenciamento de API.

    Observação

    Os certificados de AC para validação de certificado não são compatíveis com o nível Consumo.

Pré-requisitos para a integração do cofre de chaves

  1. Se você ainda não tiver um cofre de chaves, crie um. Para obter as etapas para criar um cofre de chaves, veja Início Rápido: Criar um cofre de chaves usando o portal do Azure.

    Para criar ou importar um certificado no cofre de chaves, confira Guia de início rápido: definir e recuperar um certificado do Azure Key Vault usando o portal do Azure.

  2. Habilite uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário na instância de Gerenciamento de API.

Configurar o acesso ao Key Vault

  1. No portal, navegue até o cofre de chaves.

  2. No menu à esquerda, selecione Configuração de acesso e anote o Modelo de permissão configurado.

  3. Dependendo do modelo de permissão, configure uma política de acesso do cofre de chaves ou o acesso do RBAC do Azure para uma identidade gerenciada do Gerenciamento de API.

    Para adicionar uma política de acesso do cofre de chaves:

    1. No menu à esquerda, selecione Políticas de acesso.
    2. Na página Políticas de acesso, selecione + Criar.
    3. Na guia Permissões, em Permissões em Permissões de segredo, escolha Obter e Listar. Clique em Avançar.
    4. Na guia Entidade de segurança, Selecionar entidade de segurança, procure o nome do recurso da identidade gerenciada e selecione Avançar. Se você estiver usando uma identidade atribuída pelo sistema, a entidade de segurança será o nome da instância de Gerenciamento de API.
    5. Selecione novamente Avançar. Na guia Revisar + criar, selecione Criar.

    Para configurar o acesso ao RBAC do Azure:

    1. No menu à esquerda, selecione Controle de acesso (IAM) .
    2. Na página Controle de acesso (IAM), selecione Adicionar atribuição de função.
    3. Na guia Função, selecione Usuário de Segredos do Key Vault.
    4. Na guia Membros, selecione Identidade gerenciada>+ Selecionar membros.
    5. Na página Selecionar identidade gerenciada, escolha a identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância do Gerenciamento de API e clique em Selecionar.
    6. Selecione Examinar + atribuir.

Requisitos para firewall do Key Vault

Se o firewall do Key Vault estiver habilitado no seu cofre de chaves, os itens a seguir serão requisitos adicionais:

  • Você deve usar a identidade gerenciada atribuída pelo sistema da instância do Gerenciamento de API para acessar o cofre de chaves.

  • No firewall do Key Vault, habilite a opção Permitir que os serviços confiáveis da Microsoft ignorem esse firewall.

  • Verifique se o endereço IP do cliente local tem permissão para acessar o cofre de chaves temporariamente enquanto você seleciona um certificado ou segredo a ser adicionado ao Gerenciamento de API do Azure. Para obter mais informações, confira Definir configurações de rede do Azure Key Vault.

    Depois de concluir a configuração, você pode bloquear o endereço do cliente no firewall do cofre de chaves.

Requisitos de rede virtual

Se a instância do Gerenciamento de API for implantada em uma rede virtual, defina também as configurações de rede a seguir:

  • Habilite um ponto de extremidade de serviço para o Azure Key Vault na sub-rede do Gerenciamento de API.
  • Configure uma regra de NSG (grupo de segurança de rede) para permitir tráfego de saída para as marcas de serviço AzureKeyVault e AzureActiveDirectory.

Para obter detalhes, consulte Configuração de rede ao configurar o Gerenciamento de API do Azure em uma VNet.

Adicionar um certificado do cofre de chaves

Veja Pré-requisitos para integração do cofre de chaves.

Importante

Ao adicionar um certificado do cofre de chaves à instância do Gerenciamento de API, você deve ter permissões para listar segredos do cofre de chaves.

Cuidado

Ao usar um certificado do cofre de chaves no Gerenciamento de API, tenha cuidado para não excluir o certificado, o cofre de chaves ou a identidade gerenciada usados para acessar o cofre de chaves.

Para adicionar um certificado do cofre de chaves ao Gerenciamento de API:

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.

  2. Em Segurança, selecione Certificados.

  3. Selecione Certificados>+ Adicionar.

  4. Em ID, insira um nome de sua preferência.

  5. Em Certificado, selecione Cofre de chaves.

  6. Insira o identificador de um certificado do cofre de chaves ou escolha Selecionar para selecionar um certificado de um cofre de chaves.

    Importante

    Se você mesmo inserir um identificador de certificado do cofre de chaves, verifique se ele não tem informações de versão. Caso contrário, o certificado não será girado automaticamente no Gerenciamento de API após uma atualização no cofre de chaves.

  7. Em Identidade do cliente, selecione uma identidade gerenciada atribuída pelo sistema ou uma existente atribuída pelo usuário. Saiba como adicionar ou modificar identidades gerenciadas no serviço de Gerenciamento de API.

    Observação

    A identidade precisa de permissões para obter e listar o certificado do cofre de chaves. Se você ainda não tiver configurado o acesso ao cofre de chaves, o Gerenciamento de API perguntará se ele pode configurar automaticamente a identidade com as permissões necessárias.

  8. Selecione Adicionar.

    Captura de tela da adição de um certificado do cofre de chaves ao Gerenciamento de API no portal.

  9. Selecione Salvar.

Carregar um certificado

Para carregar um certificado do cliente no Gerenciamento de API:

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.

  2. Em Segurança, selecione Certificados.

  3. Selecione Certificados>+ Adicionar.

  4. Em ID, insira um nome de sua preferência.

  5. Em Certificado, selecione Personalizado.

  6. Navegue para selecionar o arquivo de certificado .pfx e digite sua senha.

  7. Selecione Adicionar.

    Captura de tela do upload de um certificado do cliente no Gerenciamento de API no portal.

  8. Selecione Salvar.

Observação

Se você quiser usar apenas o certificado para autenticar o cliente com Gerenciamento de API, poderá carregar um arquivo CER.

Habilitar a instância do Gerenciamento de API para receber e verificar certificados do cliente

Nível Desenvolvedor, Básico, Standard ou Premium

Para receber e verificar certificados de cliente por HTTP/2 nas camadas Desenvolvedor, Básico, Básico v2, Padrão, Padrão v2 ou Premium, ative a configuração Negociar certificado do cliente na folha Domínios personalizados, como é mostrado abaixo.

Negociar um certificado de cliente

Camada de consumo

Para receber e verificar certificados do cliente no nível Consumo, ative configuração Solicitar certificado do cliente na folha Domínios personalizados, conforme mostrado abaixo.

Solicitar certificado de cliente

Política para validar certificados de cliente

Use a política validate-client-certificate para validar um ou mais atributos de um certificado de cliente usado para acessar APIs hospedadas em sua instância do Gerenciamento de API.

Configure a política para validar um ou mais atributos, incluindo emissor do certificado, entidade, impressão digital, se o certificado é validado em relação à lista de revogação online e outros.

Validação de certificado com variáveis de contexto

Você também pode criar expressões de política com a variável context para verificar os certificados do cliente. Exemplos nas seções a seguir mostram expressões usando a propriedade context.Request.Certificate e outras propriedades context.

Observação

A autenticação mútua de certificado pode não funcionar corretamente quando o ponto de extremidade do gateway de Gerenciamento de API é exposto por meio do Gateway de Aplicativo. Isso ocorre porque Gateway de Aplicativo funciona como um balanceador de carga de Camada 7, estabelecendo uma conexão SSL distinta com o serviço de Gerenciamento de API de back-end. Consequentemente, o certificado anexado pelo cliente na solicitação HTTP inicial não será encaminhado para o APIM. No entanto, como solução alternativa, você pode transmitir o certificado usando a opção variáveis de servidor. Para obter instruções detalhadas, confira Variáveis de servidor de autenticação mútua.

Importante

  • A partir de maio de 2021, a propriedade context.Request.Certificate solicita apenas o certificado quando a hostnameConfiguration da instância do Gerenciamento de API define a propriedade negotiateClientCertificate como True. Por padrão, negotiateClientCertificate é definido como false.
  • Se a renegociação do TLS estiver desabilitada em seu cliente, você poderá ver erros TLS ao solicitar o certificado usando a propriedade context.Request.Certificate. Se isso ocorrer, habilite as configurações de renegociação de TLS no cliente.
  • Não há suporte para a renegociação de certificação nas camadas do Gerenciamento de API v2.

Verificando o emissor e a entidade

As políticas abaixo podem ser configuradas para verificar o emissor e a entidade de um certificado do cliente:

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

Observação

Para desabilitar a verificação da lista de certificados revogados use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, os certificados AC raiz (ou intermediário) deverão ser carregados no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionarem.

Verificando a impressão digital

Veja abaixo que as políticas podem ser configuradas para verificar a impressão digital de um certificado do cliente:

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

Observação

Para desabilitar a verificação da lista de certificados revogados use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, os certificados AC raiz (ou intermediário) deverão ser carregados no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionarem.

Verificação de uma impressão digital em relação a certificados carregados no Gerenciamento de API

O exemplo a seguir mostra como verificar a impressão digital de um certificado do cliente em relação a certificados carregados no Gerenciamento de API:

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

Observação

Para desabilitar a verificação da lista de certificados revogados use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, os certificados AC raiz (ou intermediário) deverão ser carregados no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionarem.

Dica

O problema de deadlock de certificado do cliente descrito neste artigo pode se manifestar de várias maneiras, por exemplo, solicitações congeladas, resultados de solicitações no código de status 403 Forbidden após o tempo limite, context.Request.Certificate é null. Esse problema geralmente afeta solicitações POST e PUT com o tamanho do conteúdo de aproximadamente 60KB ou maior. Para evitar que esse problema ocorra, ative a configuração “Negociar certificado de cliente” para os nomes de host desejados na folha “Domínios personalizados”, conforme mostrado na primeira imagem deste documento. Esse recurso não está disponível na camada de consumo.

Próximas etapas