Criar cabeçalhos personalizados em serviços de back-end

Nesta página, descrevemos como configurar cabeçalhos personalizados em serviços de back-end usados por balanceadores de carga de aplicativo externos globais.

Os cabeçalhos de solicitação e resposta personalizados permitem especificar cabeçalhos adicionais que o balanceador de carga pode adicionar a solicitações e respostas HTTP(S). Dependendo das informações detectadas pelo balanceador de carga, esses cabeçalhos podem incluir as seguintes informações:

  • Latência para o cliente
  • Localização geográfica do endereço IP do cliente
  • Parâmetros da conexão TLS

Cabeçalhos de solicitação personalizados são compatíveis com serviços de back-end, enquanto cabeçalhos de resposta personalizados são compatíveis com serviços e buckets de back-end.

Por padrão, o balanceador de carga adiciona determinados cabeçalhos a todas as solicitações e respostas HTTP(S) que ele encaminha por proxy entre back-ends e clientes. Para mais informações, consulte Protocolos de destino.

Antes de começar

  • Se necessário, atualize para a versão mais recente da CLI do Google Cloud:

    gcloud components update

Como os cabeçalhos personalizados funcionam

Os cabeçalhos personalizados funcionam da seguinte maneira:

  • Quando o balanceador de carga encaminha uma solicitação ao back-end, ele adiciona cabeçalhos de solicitação.

    O balanceador de carga adiciona cabeçalhos de solicitação personalizados apenas às solicitações do cliente, não às sondagens de verificação de integridade. Se o back-end exige um cabeçalho específico para autorização que esteja faltando no pacote de verificação de integridade, ele poderá falhar.

  • O balanceador de carga define os cabeçalhos de resposta antes de retornar as respostas ao cliente.

Para ativar cabeçalhos personalizados, especifique uma lista de cabeçalhos em uma propriedade do serviço ou bucket de back-end.

Especifique cada cabeçalho como uma string header-name:header-value. O cabeçalho precisa conter dois pontos separando o nome e o valor dele.

Os nomes de cabeçalho precisam atender aos seguintes requisitos:

  • O nome do cabeçalho precisa ser uma definição válida de nome de campo de cabeçalho HTTP (de acordo com a RFC 7230).
  • O cabeçalho Host pode ser configurado, mas está sujeito a determinadas limitações.
  • O nome do cabeçalho não pode ser authority. Essa é uma palavra-chave especial reservada pelo Google Cloud. Não é possível modificar esse cabeçalho para balanceadores de carga baseados no Envoy, como o balanceador de carga de aplicativo externo global. Em vez disso, recomendamos que você crie outros cabeçalhos personalizados para não interferir nos nomes de cabeçalho reservados.
  • O nome do cabeçalho não pode ser X-User-IP nem CDN-Loop.
  • Os seguintes cabeçalhos salto a salto não podem ser usados: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer, Upgrade, Proxy-Authorization e Proxy-Authenticate. De acordo com a RFC 2616 (link em inglês), esses cabeçalhos não são armazenados por caches nem propagados pelos proxies de destino.
  • O nome do cabeçalho não pode começar com X-Google, X-Goog-, X-GFE ou X-Amz-.
  • Um nome de cabeçalho não pode aparecer mais de uma vez na lista de cabeçalhos adicionados.

Os valores de cabeçalho precisam atender aos seguintes requisitos:

  • O valor do cabeçalho precisa ser uma definição válida de campo de cabeçalho HTTP (segundo a RFC 7230, com formulários obsoletos não permitidos).
  • O valor do cabeçalho pode estar em branco.
  • O valor do cabeçalho pode incluir uma ou mais variáveis, delimitadas por chaves, que se expandem para valores fornecidos pelo balanceador de carga. Na próxima seção, há uma lista de variáveis ​​permitidas no valor do cabeçalho.

A ferramenta de linha de comando gcloud tem uma flag para especificar cabeçalhos de solicitação: --custom-request-header. Use este flag para incluir o nome e o valor do cabeçalho entre aspas simples (').

O formato geral da sinalização é:

    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Confira a seguir um exemplo de um valor de cabeçalho com duas variáveis, client_region e client_city, entre chaves.

    --custom-request-header='X-Client-Geo-Location:{client_region},{client_city}'

Para clientes localizados em Mountain View, Califórnia, este seria o cabeçalho adicionado pelo balanceador de carga:

X-Client-Geo-Location:US,Mountain View

Para criar um serviço de back-end com cabeçalhos personalizados, consulte Configurar cabeçalhos de solicitação personalizados.

Cabeçalhos do host

As limitações a seguir se aplicam quando você está configurando um cabeçalho Host personalizado com um balanceador de carga de aplicativo externo global:

  • Só é possível configurar um cabeçalho de solicitação Host personalizado se você estiver substituindo um cabeçalho de solicitação Host.
  • Não é possível configurar um cabeçalho de resposta Host personalizado usando ações de cabeçalho no mapa de URL. No entanto, ainda é possível configurar o cabeçalho de resposta Host personalizado no serviço de back-end.
  • Além disso, os seguintes itens se aplicam aos cabeçalhos de solicitação e resposta:
    • Não é possível anexar ou remover cabeçalhos Host personalizados.
    • Não é possível usar variáveis com cabeçalhos Host personalizados.

Variáveis compatíveis com valores de cabeçalho

As variáveis a seguir podem aparecer em valores de cabeçalho personalizados.

Variável Descrição
cdn_cache_id Código do local e ID da instância de cache usada para exibir a solicitação. Esse é o mesmo valor preenchido no campo jsonPayload.cacheId dos registros de solicitação do Cloud CDN no Logging.
cdn_cache_status Status atual do cache. Os valores podem ser hit, miss, revalidated, stale, uncacheable ou disabled de qualquer objeto exibido por um Cloud CDN com back-end ativado.
origin_request_header Reflete o valor do cabeçalho Origin na solicitação de casos de uso de compartilhamento de recursos entre origens (CORS).
client_rtt_msec Tempo estimado de retorno para transmissão entre o balanceador de carga e o cliente HTTP(S), em milissegundos. É o parâmetro de tempo de retorno suavizado (SRTT, na sigla em inglês) medido pela pilha TCP do balanceador de carga, de acordo com a RFC 2988. O RTT suavizado é um algoritmo que lida com variações e anomalias que podem ocorrer em medições de RTT.
client_region O país (ou região) associado ao endereço IP do cliente. Esté é um código de região Unicode CLDR, como US ou FR. Na maioria dos países, esses códigos correspondem diretamente a códigos ISO-3166-2.
client_region_subdivision Subdivisão do país associado ao endereço IP do cliente, por exemplo, uma província ou um estado. Este é um ID de subdivisão Unicode CLDR, como USCA ou CAON. Esses códigos Unicode são derivados das subdivisões definidas pelo padrão ISO-3166-2.
client_city Nome da cidade de origem da solicitação. Por exemplo, Mountain View para Mountain View, Califórnia. Não há uma lista canônica de valores válidos para essa variável. Os nomes das cidades podem conter letras US-ASCII, números, espaços e os seguintes caracteres: !#$%&'*+-.^_`|~.
client_city_lat_long Latitude e longitude da cidade de origem da solicitação. Por exemplo, 37.386051,-122.083851 para uma solicitação de Mountain View.
client_ip_address O endereço IP do cliente. Geralmente, ele é igual ao endereço IP do cliente que é o penúltimo endereço no cabeçalho X-Forwarded-For, a menos que o cliente esteja usando um proxy ou o cabeçalho X-Forwarded-For tenha sido adulterado.
client_port A porta de origem do cliente.
client_encrypted true se a conexão entre o cliente e o balanceador de carga for criptografada (usando HTTPS, HTTP/2 ou HTTP/3); Caso contrário, false.
client_protocol O protocolo HTTP usado para a comunicação entre o cliente e o balanceador de carga. Um de HTTP/1.0, HTTP/1.1, HTTP/2, ou HTTP/3.
server_ip_address O endereço IP do balanceador de carga a que o cliente se conecta. Isso pode ser útil quando vários balanceadores de carga compartilham back-ends comuns. Este é o mesmo que o último endereço IP no cabeçalho X-Forwarded-For.
server_port O número da porta de destino à qual o cliente se conecta.
tls_sni_hostname Indicação do nome do servidor (conforme definido na RFC 6066, em inglês), caso ele seja fornecido pelo cliente durante o handshake do TLS ou do QUIC. O nome do host é convertido para letras minúsculas e qualquer ponto à direita é removido.
tls_version Versão de TLS negociada entre o cliente e o balanceador de carga durante o handshake de SSL. Os valores possíveis incluem TLSv1, TLSv1.1, TLSv1.2 e TLSv1.3. Se o cliente se conectar usando QUIC em vez de TLS, o valor será QUIC.
tls_cipher_suite Pacote de criptografia negociado durante o handshake de TLS. O valor corresponde a quatro dígitos hexadecimais definidos pelo Registro do pacote de criptografia TLS da IANA. Por exemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor fica em branco para QUIC e conexões do cliente não criptografadas.
tls_ja3_fingerprint Impressão digital TLS/SSL JA3 se o cliente se conecta usando HTTPS, HTTP/2 ou HTTP/3.

O balanceador de carga expande variáveis para strings vazias quando não consegue determinar os valores delas. Por exemplo:

  • Variáveis de localização geográfica quando a localização do endereço IP é desconhecida
  • Parâmetros TLS quando o TLS não está em uso
  • O {origin_request_header} quando a solicitação não inclui um cabeçalho Origin
  • O cabeçalho {cdn_cache_status} quando incluído em um cabeçalho de solicitação

Valores geográficos (regiões, subdivisões e cidades) são estimativas baseadas no endereço IP do cliente. De tempos em tempos, o Google atualiza os dados que fornecem esses valores para melhorar a precisão e refletir as mudanças geográficas e políticas. Mesmo que o cabeçalho X-Forwarded-For original contenha informações de local válidas, o Google estima os locais do cliente usando as informações do endereço IP de origem contidas nos pacotes recebidos pelo balanceador de carga.

Os cabeçalhos adicionados pelo balanceador de carga substituem cabeçalhos já existentes com o mesmo nome. Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas. Quando os nomes de cabeçalho são passados ​​para um back-end HTTP/2, o protocolo HTTP/2 os codifica como minúsculas.

Nos valores de cabeçalho, os espaços em branco iniciais e finais são insignificantes e não são passados para o back-end. Para permitir chaves nos valores de cabeçalho, o balanceador de carga interpreta duas chaves de abertura ({{) como uma única chave de abertura ({) e duas chaves de fechamento (}}) como uma única chave de fechamento (}).

Cabeçalhos personalizados TLS mútuos

As seguintes variáveis de cabeçalho adicionais estarão disponíveis se o TLS mútuo (mTLS) estiver configurado no TargetHttpsProxy do balanceador de carga.

Variável Descrição
client_cert_present true se o cliente tiver fornecido um certificado durante o handshake de TLS. Caso contrário, false.
client_cert_chain_verified true se a cadeia de certificados do cliente for verificada em relação a um TrustStore configurado. Caso contrário, false.
client_cert_error Strings predefinidas que representam as condições de erro. Para mais informações sobre as strings de erro, consulte os modos de validação de cliente mTLS.
client_cert_sha256_fingerprint Impressão digital SHA-256 codificada em Base64 do certificado do cliente.
client_cert_serial_number O número de série do certificado do cliente. Se o número de série for maior que 50 bytes, o client_cert_error será definido como client_cert_serial_number_exceeded_size_limit e o número de série será definido como uma string vazia.
client_cert_spiffe_id

O ID do SPIFFE no campo "Nome alternativo do assunto" (SAN, na sigla em inglês). Se o valor não for válido ou exceder 2.048 bytes, o ID do SPIFFE será definido como uma string vazia.

Se o ID SPIFFE for maior que 2.048 bytes, o client_cert_error será definido como client_cert_spiffe_id_exceeded_size_limit.
client_cert_uri_sans

Lista codificada por Base64 separada por vírgula das extensões SAN do tipo URI. As extensões do SAN são extraídas do certificado do cliente. O ID do SPIFFE não está incluído no campo client_cert_uri_sans.

Se client_cert_uri_sans for maior que 512 bytes, client_cert_error será definido como client_cert_uri_sans_exceeded_size_limit e a lista separada por vírgulas será definida como uma string vazia.
client_cert_dnsname_sans

Lista codificada por Base64 separada por vírgula das extensões SAN do tipo DNSName. As extensões do SAN são extraídas do certificado do cliente.

Se client_cert_dnsname_sans for maior que 512 bytes, client_cert_error será definido como client_cert_dnsname_sans_exceeded_size_limit e a lista separada por vírgulas será definida como uma string vazia.
client_cert_valid_not_before Carimbo de data/hora (formato de string de data RFC 3339) antes do qual o certificado do cliente não é válido. Por exemplo, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after Carimbo de data/hora (formato de string de data RFC 3339) após o qual o certificado do cliente não é válido. Por exemplo, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn

Codificação DER codificada em Base64 do campo completo do emissor do certificado.

Se o client_cert_issuer_dn tiver mais de 512 bytes, a string client_cert_issuer_dn_exceeded_size_limit será adicionada a client_cert_error e client_cert_issuer_dn será definido como uma string vazia.
client_cert_subject_dn

Codificação DER codificada em Base64 do campo completo do assunto do certificado.

Se o client_cert_subject_dn tiver mais de 512 bytes, a string client_cert_subject_dn_exceeded_size_limit será adicionada a client_cert_error e client_cert_subject_dn será definida como uma string vazia.
client_cert_leaf

O certificado de folha de cliente para uma conexão mTLS estabelecida em que o certificado passou na validação. A codificação do certificado é compatível com o RFC 9440 (link em inglês). Isso significa que o certificado DER binário é codificado usando Base64 e delimitado com dois-pontos em ambos os lados.

Se client_cert_leaf exceder 16 KB não codificados, a string client_cert_validated_leaf_exceeded_size_limit será adicionada a client_cert_error, e client_cert_leaf será definido como uma string vazia.
client_cert_chain

A lista de certificados delimitada por vírgulas, na ordem TLS padrão, da cadeia de certificados do cliente para uma conexão mTLS estabelecida em que o certificado do cliente passou na validação, sem incluir o certificado de folha. A codificação do certificado é compatível com a RFC 9440 (link em inglês).

Se o tamanho combinadoclient_cert_leaf e client_cert_chain antes que a codificação Base64 exceda 16 KB, a stringclient_cert_validated_chain_exceeded_size_limit foi adicionado aclient_cert_error eclient_cert_chain é definido como uma string vazia.

Configurar cabeçalhos de solicitação personalizados

Console

Para adicionar cabeçalhos de solicitação personalizados a um serviço de back-end existente:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Em Cabeçalhos de solicitação personalizados, clique em Adicionar cabeçalho.
  7. Insira o nome do cabeçalho e o valor do cabeçalho para o cabeçalho da solicitação personalizada.
  8. Insira qualquer cabeçalho adicional da solicitação personalizada.
  9. Clique em Salvar.

Para remover um cabeçalho de solicitação personalizado de um serviço de back-end:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Clique no X ao lado do nome do cabeçalho da solicitação personalizado que você quer remover.
  7. Clique em Salvar.

gcloud

Para especificar cabeçalhos de solicitação personalizados, use o comando gcloud compute backend-services create ou gcloud compute backend-services update com a sinalização --custom-request-header.

Para criar um serviço de back-end com cabeçalhos de solicitação personalizados:

gcloud compute backend-services create BACKEND_SERVICE_NAME \
    --global-health-checks \
    --global \
    --protocol HTTPS \
    --health-checks https-basic-check \
    --custom-request-header='HEADER_NAME:[HEADER_VALUE]'

Para adicionar mais cabeçalhos de solicitação, especifique um nome e um valor de cabeçalho exclusivos repetindo a sinalização --custom-request-header.

Para adicionar cabeçalhos personalizados a um serviço de back-end existente:

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --custom-request-header='HEADER_1_NAME:[HEADER_1_VALUE]' \
    --custom-request-header='HEADER_2_NAME:[HEADER_2_VALUE]'

A etapa anterior substitui todos os cabeçalhos que já estão no serviço de back-end pelos cabeçalhos de solicitação especificados no comando.

Para remover todos os cabeçalhos de um serviço de back-end:

gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --no-custom-request-headers

API

Faça uma solicitação PATCH ao método backendServices.patch:

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME
"customRequestHeaders": [
   "client_city:Mountain View"
]

Configurar cabeçalhos de resposta personalizados

Console

Para adicionar cabeçalhos de resposta personalizados a um serviço de back-end existente:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Em Cabeçalhos de resposta personalizados, clique em Adicionar cabeçalho.
  7. Insira o Nome do cabeçalho e o Valor do cabeçalho no cabeçalho de resposta personalizado.
  8. Insira qualquer outro cabeçalho de resposta personalizado.
  9. Clique em Salvar.

Para remover um cabeçalho de resposta personalizado de um serviço de back-end:

  1. Acesse a página de resumo do balanceamento de carga.
    Acessar a página "Balanceamento de carga"
  2. Clique em Back-ends.
  3. Clique no nome de um serviço de back-end.
  4. Clique em Editar .
  5. Clique em Configurações avançadas (afinidade de sessão, tempo limite de diminuição da conexão, políticas de segurança).
  6. Clique no X ao lado do nome do cabeçalho de resposta personalizado que você quer remover.
  7. Clique em Salvar.

gcloud

Para serviços de back-end, use o comando gcloud compute backend-services create ou gcloud compute backend-services update com a sinalização --custom-response-header.

Para buckets de back-end, use o comando gcloud compute backend-buckets create ou gcloud compute backend-buckets update com a sinalização --custom-response-header.

gcloud compute backend-services (create | update) BACKEND_SERVICE_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

gcloud compute backend-buckets (create | update) BACKEND_BUCKET_NAME
    --custom-response-header='HEADER_NAME:[HEADER_VALUE]'

Exemplo com cabeçalho X-Frame-Options:

gcloud compute backend-buckets update gaming-lab \
    --custom-response-header='X-Frame-Options: DENY'

Exemplo com cabeçalho Strict-Transport-Security:

O exemplo a seguir mostra como adicionar um cabeçalho de resposta personalizado para oferecer suporte ao HTTP Strict Transport Security (HSTS):

gcloud compute backend-services update customer-bs-name \
    --global \
    --custom-response-header='Strict-Transport-Security: max-age=63072000'

API

Para buckets de back-end, use a chamada de API Method: backendBuckets.insert ou Method: backendBuckets.update.

Para serviços de back-end, use a chamada de API Method: backendServices.insert ou Method: backendServices.update.

Use uma das seguintes chamadas de API:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendBuckets/BACKEND_BUCKET_NAME

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices

PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/global/backendServices/BACKEND_SERVICE_NAME

Adicione o seguinte snippet ao corpo da solicitação JSON:

"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]

Definir cabeçalhos de resposta para o Cloud Storage

Se você precisar definir cabeçalhos HTTP em respostas do Cloud Storage, como política de recursos de origem cruzada, X-Frame-Options ou cabeçalhos X-XSS-Protection, o Google Cloud oferece a opção de usar cabeçalhos personalizados do Cloud CDN com o Cloud Storage. Para isso, configure cabeçalhos personalizados no nível do bucket de back-end do balanceador de carga, conforme descrito nesta página.

Os cabeçalhos de resposta personalizados configurados no nível do bucket de back-end só são adicionados às respostas se a solicitação do cliente for enviada para o endereço IP do balanceador de carga. Os cabeçalhos personalizados não serão adicionados às respostas se a solicitação do cliente tiver sido feita diretamente para a API Cloud Storage.

Usar cabeçalhos personalizados com o Google Cloud Armor

Ao configurar uma política de segurança no Cloud Armor, você pode inserir um cabeçalho e um valor personalizados. Se a política de segurança do Google Cloud Armor estiver configurada para inserir o mesmo nome de cabeçalho personalizado dos cabeçalhos personalizados do balanceador de carga de aplicativo externo global ou clássico, o valor do cabeçalho especificado no Google Cloud Armor pelo valor preenchido pelo balanceador de carga. Se você não quiser que a política do Google Cloud Armor seja substituída, não use o mesmo nome.

Limitações

As limitações a seguir são válidas para cabeçalhos personalizados usados com balanceadores de carga globais:

  • O tamanho total de todos os cabeçalhos de solicitação personalizados (nome e valor combinados, antes da expansão da variável) para cada serviço de back-end não pode exceder 8 KB ou 16 cabeçalhos de solicitação.
  • O tamanho total de todos os cabeçalhos de resposta personalizados (nome e valor combinados, antes da expansão da variável) para cada serviço de back-end não pode exceder 8 KB ou 16 cabeçalhos de resposta.