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

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O Edge permite criar hosts virtuais compatíveis com TLS unidirecional e bidirecional. Com o TLS unidirecional, o cliente emite uma solicitação de sessão para um host virtual implantado em um roteador de borda 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 passam certificados 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 um host virtual compatível com TLS, o Edge pode capturar informações sobre a conexão TLS. Seu proxy de API poderá então acessar essas informações por meio variáveis de fluxo para realizar análises 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 TLS unidirecional, o Edge pode capturar informações sobre Criptografia TLS ou protocolo TLS usado 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.

Capturar informações para ambos 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 ficar 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 do 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 está 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>: ativa a captura das informações de conexão TLS. para TLS unidirecional e bidirecional. O valor padrão é false.
  • <ClientProperties>: ativar a captura de informações adicionais para TLS bidirecional. O valor padrão é false.

Por exemplo, a definição de host virtual a seguir usa 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. Você deve, portanto, certificar-se de que os limites de tamanho do cabeçalho estejam definidos adequadamente dependendo do uso do Edge para a nuvem ou o Edge para a nuvem privada:

  • Edge for the Cloud: a Apigee define os tamanhos dos cabeçalhos adequadamente.
  • 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, é possível usar AssignMessage política para acessá-los, acessá-los em JavaScript com a política JavaScript.

Também é possível fazer referência às variáveis de fluxo em um elemento <Condition> de um fluxo de proxy ou de destino. ou em um <Step> ou <RouteRule>. Por exemplo, você pode rotear uma solicitação para destinos diferentes com base no SN do cliente.

Para mais informações, acesse: