Como acessar informações de conexão TLS em um proxy de API

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O Edge permite criar hosts virtuais com suporte para TLS unidirecional e bidirecional. Com o TLS unidirecional, o cliente emite uma solicitação de sessão para um host virtual implantado em um Edge Router e o roteador responde com um certificado que contém a chave pública do host virtual. Para um certificado assinado, o cliente poderá fazer uma solicitação à autoridade de certificação (CA) para autenticar o certificado.

No TLS bidirecional, o cliente e o Edge transmitem certificados que são validados como parte de uma solicitação:

  • O roteador de borda apresenta o certificado ao cliente TLS para se autenticar. O cliente verifica a identidade do servidor antes de enviar seu certificado para o servidor.
  • O cliente TLS apresenta o certificado ao Edge para autenticação.

Consulte Sobre hosts virtuais para mais informações.

Como capturar informações de conexão TLS

Durante uma solicitação para um proxy de API por meio de um host virtual compatível com TLS, o Edge pode capturar informações sobre a conexão TLS. O proxy de API pode acessar essas informações em variáveis de fluxo para realizar análise e validação adicionais.

O tipo de informação TLS capturada pelo Edge depende da compatibilidade do host virtual com TLS unidirecional ou bidirecional. Por exemplo, para o TLS unidirecional, o Edge pode capturar informações sobre a criptografia ou o protocolo TLS usados na conexão TLS.

Para o TLS bidirecional, o Edge pode capturar as mesmas informações capturadas para o TLS unidirecional, além de capturar informações sobre o certificado do cliente. Por exemplo, o Edge pode capturar a impressão digital SHA1 do certificado do cliente e o certificado do cliente no formato PEM.

Como capturar informações para TLS unidirecional e bidirecional

A tabela a seguir lista as variáveis de fluxo que contêm informações de conexão TLS capturadas pelo Edge e estão disponíveis para acesso no proxy de API. Essas informações são capturadas e TLS bidirecional configurando <ConnectionProperties> como verdadeiro no Definição de host virtual:

Variável de fluxo Descrição
tls.cipher A criptografia usada pela conexão TLS.
tls.protocol O protocolo usado pela conexão TLS.
tls.server.name O nome do servidor SNI solicitado.
tls.session.id

O identificador da sessão.

Essa variável de fluxo está disponível quando você define <ConnectionProperties> ou <ClientProperties> ou como verdadeiro.

Como capturar informações adicionais de TLS durante a TLS bidirecional

A tabela a seguir lista as variáveis de fluxo que contêm detalhes sobre o certificado do cliente capturados pelo Edge em TLS bidirecional. Essas informações são capturadas para TLS bidirecional ao definir <ClientProperties> como verdadeiro na definição do host virtual:

Variável de fluxo Descrição
tls.client.s.dn O nome distinto (DN, na sigla em inglês) do assunto que identifica o certificado do cliente.
tls.client.i.dn O nome distinto (DN, na sigla em inglês) do emissor do certificado do cliente.
tls.client.raw.cert O certificado do cliente no formato PEM.
tls.client.cert.serial O número de série do certificado do cliente.
tls.client.cert.fingerprint Impressão digital SHA1 do certificado do cliente.
tls.session.id

O identificador da sessão.

Essa variável de fluxo fica disponível quando você define <ConnectionProperties> ou <ClientProperties> como verdadeiro.

Como configurar um host virtual para capturar informações de TLS

Para configurar o host virtual para capturar informações de TLS, defina as seguintes propriedades abaixo de <PropagateTLSInformation> a true.

  • <ConnectionProperties>: permite a captura de informações de conexão TLS para TLS unidirecional e bidirecional. O valor padrão é false.
  • <ClientProperties>: ativa a captura de informações adicionais para a TLS bidirecional. O valor padrão é false.

Por exemplo, a definição de host virtual a seguir usa o TLS bidirecional e permite a captura de ambos os tipos de informações de TLS:

<VirtualHost name="secure">
    ....
    <SSLInfo>
        <Enabled>true</Enabled>
        # Enable two-way TLS.
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <IgnoreValidationErrors>false</IgnoreValidationErrors>
        <KeyAlias>ks-alias</KeyAlias>
        <KeyStore>ref://ks-ref</KeyStore>
        <TrustStore>ref://ts-ref</TrustStore>
    </SSLInfo>
    <PropagateTLSInformation>
        <ConnectionProperties>true</ConnectionProperties>
        <ClientProperties>true</ClientProperties>
    </PropagateTLSInformation>
</VirtualHost>

Se você estiver transmitindo um corpo JSON, defina as propriedades como:

  "propagateTLSInformation" : {
    "connectionProperties" : true,
    "clientProperties" : true
  }

Definir limites de tamanho dos cabeçalhos

Quando você ativa a captura de informações do TLS em um host virtual, o Edge transmite essas informações usando cabeçalhos HTTP. Portanto, verifique se os limites de tamanho do cabeçalho estão definidos corretamente de acordo com o uso do Edge para nuvem ou do Edge para nuvem privada:

  • Edge para a nuvem: a Apigee define os tamanhos de cabeçalho de maneira adequada.
  • Edge para a nuvem privada: recurso não disponível.

Como acessar as variáveis de fluxo em um proxy de API

No proxy de API, é possível acessar e inspecionar as variáveis de fluxo TLS. Por exemplo, use a política AssignMessage para acessá-las em JavaScript.

Também é possível referenciar as variáveis de fluxo em um elemento <Condition> de um proxy ou fluxo de destino, ou em um <Step> ou <RouteRule>. Por exemplo, é possível encaminhar uma solicitação para destinos diferentes com base no SN do cliente.

Para mais informações, consulte: