Como proteger APIs com a autenticação de certificado de cliente na Gestão de API

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

A Gestão de API permite proteger o acesso às APIs (ou seja, do cliente à Gestão de API) através de certificados de cliente e da autenticação TLS mútua. Pode validar os certificados apresentados pelo cliente de ligação e verificar as propriedades do certificado relativamente aos valores desejados através de expressões de política.

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

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

Opções de certificado

Para validação de certificados, a Gestão de API pode verificar os certificados geridos na instância de Gestão de API. Se optar por utilizar a Gestão de API para gerir os certificados de cliente, terá as seguintes opções:

  • Fazer referência a um certificado gerenciado no Azure Key Vault
  • Adicionar um ficheiro de certificado diretamente na Gestão de API

O uso de certificados de 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 em todos os serviços
  • Políticas de acesso granulares podem ser aplicadas a certificados armazenados em cofres de chaves
  • Os certificados atualizados no cofre de chaves são alternados automaticamente 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 criou uma instância de serviço de Gerenciamento de API, consulte Criar uma instância de serviço de Gerenciamento de API.

  • Você precisa acessar o certificado e a senha para gerenciamento em um cofre de chaves do Azure ou carregar para o serviço de Gerenciamento de API. O certificado deve estar no formato CER ou PFX. Certificados autoassinados são permitidos.

    Se você usar um certificado autoassinado, instale também certificados de CA raiz e intermediária confiáveis em sua instância de Gerenciamento de API.

    Nota

    Não há suporte para certificados de CA para validação de certificados na camada Consumo.

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

  1. Se ainda não tiver um cofre de chaves, crie um. Para conhecer as etapas para criar um cofre de chaves, consulte Guia de início rápido: criar um cofre de chaves usando o portal do Azure.

    Para criar ou importar um certificado para o cofre de chaves, consulte Guia de início rápido: definir e recuperar um certificado do Cofre de Chaves do Azure usando o portal do Azure.

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

Configurar o acesso ao cofre de chaves

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

  2. No menu à esquerda, selecione Configuração do Access e anote o modelo de permissão que está configurado.

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

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

    1. No menu à esquerda, selecione Políticas de acesso.
    2. Na página Políticas de acesso , selecione + Criar.
    3. No separador Permissões, em Permissões secretas, selecione Obter e Listar e, em seguida, selecione Seguinte.
    4. No separador Principal, Selecione entidade de segurança, procure o nome do recurso da sua identidade gerida e, em seguida, selecione Seguinte. Se você estiver usando uma identidade atribuída ao sistema, o principal será o nome da sua instância de Gerenciamento de API.
    5. Selecione Avançar novamente. No separador Rever + criar, selecione Criar.

    Para configurar o acesso ao Azure RBAC:

    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 Cofre da Chave.
    4. Na guia Membros, selecione Identidade> gerenciada+ Selecionar membros.
    5. Na página Selecionar identidade gerenciada, selecione a identidade gerenciada atribuída ao sistema ou uma identidade gerenciada atribuída pelo usuário associada à sua instância de Gerenciamento de API e selecione Selecionar.
    6. Selecione Rever + atribuir.

Requisitos para o firewall do Key Vault

Se o firewall do Cofre da Chave estiver habilitado no cofre de chaves, os seguintes requisitos são adicionais:

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

  • No firewall do Cofre de Chaves, habilite a opção Permitir que Serviços Microsoft Confiáveis ignorem esse firewall .

  • Certifique-se de que o endereço IP do cliente local tenha permissão para acessar o cofre de chaves temporariamente enquanto seleciona um certificado ou segredo para adicionar ao Gerenciamento de API do Azure. Para obter mais informações, consulte Configurar configurações de rede do Cofre da Chave do Azure.

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

Requisitos da rede virtual

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

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

Adicionar um certificado de cofre de chaves

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

Importante

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

Atenção

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

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

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

  2. Em Segurança, selecione Certificados.

  3. Selecione Certificados>+ Adicionar.

  4. Em Id, insira um nome de sua escolha.

  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, certifique-se de que ele não tenha 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 pelo usuário. Saiba como adicionar ou modificar identidades gerenciadas em seu serviço de Gerenciamento de API.

    Nota

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

  8. Selecione Adicionar.

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

  9. Selecione Guardar.

Carregar um certificado

Para carregar um certificado de cliente para o Gerenciamento de API:

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

  2. Em Segurança, selecione Certificados.

  3. Selecione Certificados>+ Adicionar.

  4. Em Id, insira um nome de sua escolha.

  5. Em Certificado, selecione Personalizado.

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

  7. Selecione Adicionar.

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

  8. Selecione Guardar.

Nota

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

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

Nível de desenvolvedor, básico, padrão ou premium

Para receber e verificar certificados de cliente por HTTP/2 nas camadas Developer, Basic, Basic v2, Standard, Standard v2 ou Premium, você deve habilitar a configuração Negociar certificado de cliente na folha Domínio personalizado, conforme mostrado abaixo.

Negociar certificado de cliente

Nível de consumo

Para receber e verificar certificados de cliente na camada Consumo, você deve habilitar a configuração Solicitar certificado de cliente na folha Domínios personalizados , conforme mostrado abaixo.

Pedir certificado do cliente

Política de validação de 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 de Gerenciamento de API.

Configure a política para validar um ou mais atributos, incluindo emissor do certificado, assunto, 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 context variável para verificar certificados de cliente. Exemplos nas seções a seguir mostram expressões usando a context.Request.Certificate propriedade e outras context propriedades.

Nota

A autenticação de certificado mútuo 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 o Application Gateway 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 de variáveis de servidor. Para obter instruções detalhadas, consulte Variáveis de servidor de autenticação mútua.

Importante

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

Verificação do emitente e do assunto

As políticas abaixo podem ser configuradas para verificar o emissor e o assunto de um certificado de 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>

Nota

Para desativar a verificação da lista de revogação de certificados, use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, o(s) certificado(s) de CA raiz (ou intermediário) deverá ser carregado (s) no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionar.

Verificar a impressão digital

As políticas abaixo podem ser configuradas para verificar a impressão digital de um certificado de 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>

Nota

Para desativar a verificação da lista de revogação de certificados, use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, o(s) certificado(s) de CA raiz (ou intermediário) deverá ser carregado (s) no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionar.

Verificando 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 de cliente em relação aos 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>

Nota

Para desativar a verificação da lista de revogação de certificados, use context.Request.Certificate.VerifyNoRevocation() em vez de context.Request.Certificate.Verify(). Se o certificado do cliente for autoassinado, o(s) certificado(s) de CA raiz (ou intermediário) deverá ser carregado (s) no Gerenciamento de API para context.Request.Certificate.Verify() e context.Request.Certificate.VerifyNoRevocation() funcionar.

Gorjeta

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

Próximos passos