Crear encabezados personalizados en servicios de backend

En esta página se describe cómo configurar encabezados personalizados en los servicios de backend que usan los balanceadores de carga de aplicación externos globales.

Los encabezados de solicitud y respuesta personalizados te permiten especificar encabezados adicionales que el balanceador de carga puede añadir a las solicitudes y respuestas HTTP(S). En función de la información detectada por el balanceador de carga, estos encabezados pueden incluir la siguiente información:

  • Latencia al cliente
  • Ubicación geográfica de la dirección IP del cliente
  • Parámetros de la conexión TLS

Los encabezados de solicitud personalizados se admiten en los servicios de backend, mientras que los encabezados de respuesta personalizados se admiten en los servicios de backend y los segmentos de backend.

El balanceador de carga añade de forma predeterminada determinados encabezados a todas las solicitudes y respuestas HTTP(S) que procesa en el proxy entre los backends y los clientes. Para obtener más información, consulta Proxies de destino.

Encabezados personalizados en mapas de URLs

Los balanceadores de carga de aplicaciones externos globales admiten una función similar para la transformación de encabezados en el mapa de URLs. Aunque puedes gestionar los encabezados personalizados en los servicios backend (como se describe en esta página), te recomendamos que incluyas las transformaciones de encabezados en el mapa de URLs para que todas las transformaciones de encabezados se mantengan en una sola ubicación.

Si hay configuraciones de encabezados personalizados tanto en el mapa de URLs como en el servicio de backend, se aplicarán ambas configuraciones. Sin embargo, si el mismo encabezado se define tanto en el servicio backend como en el mapa de URLs, el mapa de URLs tiene prioridad y se ignora la configuración del servicio backend. Para ver un ejemplo basado en un mapa de URLs, consulta Configurar la gestión del tráfico de los balanceadores de carga de aplicación externos globales.

Antes de empezar

  • Si es necesario, actualiza a la versión más reciente de la CLI de Google Cloud:

    gcloud components update

Cómo funcionan los encabezados personalizados

Los encabezados personalizados funcionan de la siguiente manera:

  • Cuando el balanceador de carga reenvía una solicitud al backend, añade encabezados de solicitud.

    El balanceador de carga añade encabezados de solicitud personalizados solo a las solicitudes de los clientes, no a las comprobaciones del estado. Si tu backend requiere un encabezado específico para la autorización que falta en el paquete de comprobación del estado, es posible que la comprobación del estado falle.

  • El balanceador de carga define los encabezados de respuesta antes de devolver las respuestas al cliente.

Para habilitar los encabezados personalizados, especifica una lista de encabezados en una propiedad del servicio de backend o del segmento de backend.

Cada encabezado se especifica como una cadena header-name:header-value. El encabezado debe contener dos puntos que separen el nombre y el valor del encabezado.

Los nombres de los encabezados deben cumplir los siguientes requisitos:

  • El nombre del encabezado debe ser una definición de nombre de campo de encabezado HTTP válida (según el RFC 7230).
  • El encabezado Host se puede configurar, pero está sujeto a ciertas limitaciones.
  • El nombre del encabezado no puede ser authority. Se trata de una palabra clave especial reservada porGoogle Cloud. No puedes modificar este encabezado en balanceadores de carga basados en Envoy, como el balanceador de carga de aplicación externo global. En su lugar, te recomendamos que crees otros encabezados personalizados para no interferir con los nombres de encabezados reservados.
  • El nombre del encabezado no puede ser X-User-IP ni CDN-Loop.
  • No se deben usar los siguientes encabezados de salto a salto: Keep-Alive, Transfer-Encoding, TE, Connection, Trailer y Upgrade. De acuerdo con el RFC 2616, las cachés no almacenan estos encabezados ni los proxies de destino los propagan.
  • El nombre del encabezado no debe empezar por X-Google, X-Goog-, X-GFE ni X-Amz-.
  • Un nombre de encabezado no puede aparecer más de una vez en la lista de encabezados añadidos.

Los valores de los encabezados deben cumplir los siguientes requisitos:

  • El valor del encabezado debe ser una definición de campo de encabezado HTTP válida según el RFC 7230 (no se permiten formas obsoletas).
  • El valor de la cabecera puede estar en blanco.
  • El valor del encabezado puede incluir una o varias variables entre llaves que abarquen los valores que proporciona el balanceador de carga. En la siguiente sección se incluye una lista de las variables permitidas en el valor del encabezado.

La herramienta de línea de comandos gcloud tiene una marca para especificar encabezados de solicitud, que es --custom-request-header. Asegúrate de incluir el nombre y el valor del encabezado entre comillas simples rectas (') con esta marca.

El formato general de la marca es el siguiente:

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

A continuación, se muestra un ejemplo de un valor de encabezado con dos variables, client_region y client_city, entre llaves.

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

En el caso de los clientes ubicados en Mountain View (California), el balanceador de carga añade un encabezado de la siguiente manera:

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

Para crear un servicio de backend con encabezados personalizados, consulta Configurar encabezados de solicitud personalizados.

Encabezados de host

Se aplican las siguientes limitaciones al configurar un encabezado Host personalizado con un balanceador de carga de aplicación externo global:

  • Solo puedes configurar un encabezado de solicitud Host personalizado si sustituyes un encabezado de solicitud Host.
  • No puedes configurar un encabezado de respuesta Host personalizado mediante acciones de encabezado en el mapa de URLs. Sin embargo, puedes configurar el encabezado de respuesta personalizado Host en el servicio de backend.
  • Además, se aplican los siguientes requisitos a los encabezados de solicitud y de respuesta:
    • No puedes añadir ni quitar encabezados Host personalizados.
    • No puedes usar variables con encabezados Host personalizados.

Variables admitidas con valores de encabezado

Las siguientes variables pueden aparecer en los valores de encabezado personalizados.

Variable Descripción
cdn_cache_id Código e ID de la instancia de caché utilizada para atender la solicitud. Es el mismo valor que se rellena en el campo jsonPayload.cacheId de los registros de solicitudes de Cloud CDN en Logging.
cdn_cache_status Estado actual de la caché. Los valores pueden ser hit, miss, revalidated, stale, uncacheable o disabled para cualquier objeto servido por un backend habilitado para Cloud CDN.
origin_request_header Refleja el valor del encabezado Origin de la solicitud en los casos prácticos de uso compartido de recursos entre dominios (CORS).
client_rtt_msec Tiempo de transmisión de ida y vuelta estimado entre el balanceador de carga y el cliente HTTP(S), en milisegundos. Es el parámetro de tiempo de ida y vuelta suavizado (SRTT) medido por la pila TCP del balanceador de carga, según el RFC 2988. El RTT suavizado es un algoritmo que gestiona las variaciones y las anomalías que pueden producirse en las mediciones de RTT.
client_region El país (o la región) asociado a la dirección IP del cliente. Es un código de región Unicode CLDR, como US o FR. En la mayoría de los países, estos códigos se corresponden directamente con los códigos ISO-3166-2.
client_region_subdivision Subdivisión, por ejemplo, una provincia o un estado, del país asociado a la dirección IP del cliente. Es un ID de subdivisión CLDR de Unicode, como USCA o CAON. Estos códigos Unicode se derivan de las subdivisiones definidas en el estándar ISO-3166-2.
client_city Nombre de la ciudad desde la que se ha originado la solicitud. Por ejemplo, Mountain View para Mountain View (California). No hay una lista canónica de valores válidos para esta variable. Los nombres de las ciudades pueden contener letras, números y espacios US-ASCII, así como los siguientes caracteres: !#$%&'*+-.^_`|~.
client_city_lat_long Latitud y longitud de la ciudad desde la que se ha originado la solicitud. Por ejemplo, 37.386051,-122.083851 para una solicitud de Mountain View.
client_ip_address La dirección IP del cliente. Por lo general, se trata de la misma dirección IP de cliente que la penúltima dirección del encabezado X-Forwarded-For, a menos que el cliente utilice un proxy o que se haya manipulado el encabezado X-Forwarded-For.
client_port Puerto de origen del cliente.
client_encrypted true si la conexión entre el cliente y el balanceador de carga está cifrada (con HTTPS, HTTP/2 o HTTP/3); de lo contrario, false.
client_protocol El protocolo HTTP que se usa para la comunicación entre el cliente y el balanceador de carga. Uno de los valores HTTP/1.0, HTTP/1.1, HTTP/2 o HTTP/3.
device_request_type

El dispositivo del cliente, derivado de los valores del encabezado User-Agent.

Estos son los valores posibles: DESKTOP, GAME_CONSOLE, GAME_CONSOLE, MOBILE, SET_TOP_BOX, SMART_SPEAKER, SMART_TV, TABLET, UNDETERMINED, WEARABLE.

server_ip_address La dirección IP del balanceador de carga al que se conecta el cliente. Esto puede ser útil cuando varios balanceadores de carga comparten backends comunes. Es lo mismo que la última dirección IP de la encabezado X-Forwarded-For.
server_port Número de puerto de destino al que se conecta el cliente.
tls_sni_hostname Indicación del nombre del servidor (tal como se define en el RFC 6066), si el cliente la proporciona durante el handshake TLS o QUIC. El nombre de host se convierte a minúsculas y se elimina cualquier punto final.
tls_version Versión de TLS negociada entre el cliente y el balanceador de carga durante el handshake de SSL. Entre los valores posibles se incluyen TLSv1, TLSv1.1, TLSv1.2 y TLSv1.3. Si el cliente se conecta mediante QUIC en lugar de TLS, el valor es QUIC.
tls_cipher_suite Conjunto de cifrado negociado durante el handshake TLS. El valor es un número hexadecimal de cuatro dígitos definido por el registro de conjuntos de cifrado TLS de IANA. Por ejemplo, 009C para TLS_RSA_WITH_AES_128_GCM_SHA256. Este valor está vacío en el caso de QUIC y de las conexiones de cliente sin cifrar.
tls_ja3_fingerprint JA3 Huella digital TLS/SSL si el cliente se conecta mediante HTTPS, HTTP/2 o HTTP/3.
tls_ja4_fingerprint JA4 Huella digital TLS/SSL si el cliente se conecta mediante HTTPS, HTTP/2 o HTTP/3.
user_agent_family

El tipo de navegador del cliente, derivado de los valores del encabezado User-Agent.

Estos son los valores posibles: APPLE, APPLEWEBKIT, BLACKBERRY, DOCOMO, GECKO, GOOGLE, KHTML, KOREAN, MICROSOFT, MSIE, NETFRONT, NOKIA, OBIGO, OPERA, OPENWAVE, OTHER, POLARIS, SEMC, SMIT, TELECA y USER_DEFINED.

El balanceador de carga expande las variables a cadenas vacías cuando no puede determinar sus valores. Por ejemplo:

  • Variables de ubicación geográfica cuando se desconoce la ubicación de la dirección IP
  • Parámetros de TLS cuando no se usa TLS
  • El {origin_request_header} cuando la solicitud no incluye un encabezado Origin
  • El encabezado {cdn_cache_status} cuando se incluye en un encabezado de solicitud

Los valores geográficos (regiones, subdivisiones y ciudades) son estimaciones basadas en la dirección IP del cliente. De vez en cuando, Google actualiza los datos que proporcionan estos valores para mejorar la precisión y reflejar los cambios geográficos y políticos. Aunque el encabezado X-Forwarded-For original contenga información de ubicación válida, Google estima las ubicaciones de los clientes mediante la información de la dirección IP de origen que contienen los paquetes recibidos por el balanceador de carga.

Los encabezados que añade el balanceador de carga sobrescriben los encabezados que ya tengan el mismo nombre. En los nombres de los encabezados no se distingue entre mayúsculas y minúsculas. Cuando se transfieren nombres de encabezados a un backend HTTP/2, el protocolo HTTP/2 codifica los nombres de los encabezados en minúsculas.

En los valores de encabezado, los espacios iniciales y finales no son significativos y no se transfieren al backend. Para permitir el uso de llaves en los valores de los encabezados, el balanceador de carga interpreta dos llaves de apertura ({{) como una sola llave de apertura ({) y dos llaves de cierre (}}) como una sola llave de cierre (}).

Encabezados personalizados de TLS mutuo

Las siguientes variables de encabezado adicionales están disponibles si se configura TLS mutuo (mTLS) en TargetHttpsProxy del balanceador de carga.

Variable Descripción
client_cert_present true si el cliente ha proporcionado un certificado durante el handshake TLS; de lo contrario, false.
client_cert_chain_verified true si la cadena de certificados de cliente se verifica con un TrustStore configurado; de lo contrario, false.
client_cert_error Cadenas predefinidas que representan las condiciones de error. Para obtener más información sobre las cadenas de error, consulta Modos de validación de clientes de mTLS.
client_cert_sha256_fingerprint Huella digital SHA-256 codificada en Base64 del certificado de cliente.
client_cert_serial_number Número de serie del certificado de cliente. Si el número de serie tiene más de 50 bytes, client_cert_error se define como client_cert_serial_number_exceeded_size_limit y el número de serie se define como una cadena vacía.
client_cert_spiffe_id

El ID de SPIFFE del campo de nombre alternativo del sujeto (SAN). Si el valor no es válido o supera los 2048 bytes, el ID de SPIFFE se define como una cadena vacía.

Si el ID de SPIFFE tiene más de 2048 bytes, client_cert_error se asigna a client_cert_spiffe_id_exceeded_size_limit.
client_cert_uri_sans

Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo URI. Las extensiones SAN se extraen del certificado de cliente. El ID de SPIFFE no se incluye en el campo client_cert_uri_sans.

Si el client_cert_uri_sans tiene más de 512 bytes, el client_cert_error se define como client_cert_uri_sans_exceeded_size_limit y la lista separada por comas se define como una cadena vacía.
client_cert_dnsname_sans

Lista separada por comas y codificada en Base64 de las extensiones SAN de tipo DNSName. Las extensiones SAN se extraen del certificado de cliente.

Si el client_cert_dnsname_sans tiene más de 512 bytes, el client_cert_error se define como client_cert_dnsname_sans_exceeded_size_limit y la lista separada por comas se define como una cadena vacía.
client_cert_valid_not_before Marca de tiempo (cadena de fecha en formato RFC 3339 ) anterior a la cual el certificado de cliente no es válido. Por ejemplo, 2022-07-01T18:05:09+00:00.
client_cert_valid_not_after Marca de tiempo (cadena de fecha en formato RFC 3339) tras la cual el certificado de cliente no es válido. Por ejemplo, 2022-07-01T18:05:09+00:00.
client_cert_issuer_dn

Codificación DER codificada en Base64 del campo Issuer completo del certificado.

Si client_cert_issuer_dn tiene más de 512 bytes, se añade la cadena client_cert_issuer_dn_exceeded_size_limit a client_cert_error y client_cert_issuer_dn se define como una cadena vacía.
client_cert_subject_dn

Codificación DER codificada en Base64 del campo Subject completo del certificado.

Si client_cert_subject_dn tiene más de 512 bytes, se añade la cadena client_cert_subject_dn_exceeded_size_limit a client_cert_error y client_cert_subject_dn se define como una cadena vacía.
client_cert_leaf

El certificado de hoja de cliente de una conexión mTLS establecida en la que el certificado ha superado la validación. La codificación de certificados cumple la normativa RFC 9440. Esto significa que el certificado DER binario se codifica con Base64 y se delimita con dos puntos a cada lado.

Si client_cert_leaf supera los 16 KB sin codificar, se añade la cadena client_cert_validated_leaf_exceeded_size_limit a client_cert_error y client_cert_leaf se asigna a una cadena vacía.
client_cert_chain

Lista de certificados separados por comas, en orden TLS estándar, de la cadena de certificados de cliente de una conexión mTLS establecida en la que el certificado de cliente ha superado la validación, sin incluir el certificado de hoja. La codificación de certificados cumple el estándar RFC 9440.

Si el tamaño combinado de client_cert_leaf y client_cert_chain antes de la codificación Base64 supera los 16 KB, la cadena client_cert_validated_chain_exceeded_size_limit se añade a client_cert_error y client_cert_chain se asigna a una cadena vacía.

Configurar encabezados de solicitud personalizados

Consola

Para añadir encabezados de solicitud personalizados a un servicio de backend, sigue estos pasos:

  1. Ve a la página de resumen de balanceo de carga.
    Ir a la página Balanceo de carga
  2. Haz clic en Back-ends.
  3. Haz clic en el nombre de un servicio backend.
  4. Haz clic en Editar .
  5. Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
  6. En Encabezados de solicitud personalizados, haz clic en Añadir encabezado.
  7. Introduce el nombre de la cabecera y el valor de la cabecera de la cabecera de solicitud personalizada.
  8. Introduce los encabezados de solicitud personalizados adicionales.
  9. Haz clic en Guardar.

Para quitar un encabezado de solicitud personalizado de un servicio de backend, sigue estos pasos:

  1. Ve a la página de resumen de balanceo de carga.
    Ir a la página Balanceo de carga
  2. Haz clic en Back-ends.
  3. Haz clic en el nombre de un servicio backend.
  4. Haz clic en Editar .
  5. Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
  6. Haz clic en la X situada junto al nombre del encabezado de solicitud personalizado que quieras quitar.
  7. Haz clic en Guardar.

gcloud

Para especificar encabezados de solicitud personalizados, usa el comando gcloud compute backend-services create o gcloud compute backend-services update con la marca --custom-request-header.

Para crear un servicio de backend con encabezados de solicitud personalizados, sigue estos pasos:

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 añadir más encabezados de solicitud, especifica un nombre y un valor únicos para cada encabezado repitiendo la marca --custom-request-header.

Para añadir encabezados personalizados a un servicio de backend, sigue estos pasos:

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

En el paso anterior, se sustituyen los encabezados que ya estén en el servicio backend por los encabezados de solicitud que especifiques en el comando.

Para quitar todos los encabezados de un servicio de backend, sigue estos pasos:

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

API

Haz una solicitud PATCH al 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 encabezados de respuesta personalizados

Consola

Para añadir encabezados de respuesta personalizados a un servicio de backend, sigue estos pasos:

  1. Ve a la página de resumen de balanceo de carga.
    Ir a la página Balanceo de carga
  2. Haz clic en Back-ends.
  3. Haz clic en el nombre de un servicio backend.
  4. Haz clic en Editar .
  5. Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
  6. En Encabezados de respuesta personalizados, haz clic en Añadir encabezado.
  7. Introduce el nombre de la cabecera y el valor de la cabecera de la cabecera de respuesta personalizada.
  8. Introduce los encabezados de respuesta personalizados adicionales que quieras.
  9. Haz clic en Guardar.

Para quitar un encabezado de respuesta personalizado de un servicio de backend, sigue estos pasos:

  1. Ve a la página de resumen de balanceo de carga.
    Ir a la página Balanceo de carga
  2. Haz clic en Back-ends.
  3. Haz clic en el nombre de un servicio backend.
  4. Haz clic en Editar .
  5. Haz clic en Configuraciones avanzadas (afinidad de sesión, tiempo de espera de desviación de conexión, políticas de seguridad).
  6. Haz clic en la X situada junto al nombre del encabezado de respuesta personalizado que quieras quitar.
  7. Haz clic en Guardar.

gcloud

En el caso de los servicios de backend, usa el comando gcloud compute backend-services create o gcloud compute backend-services update con la marca --custom-response-header.

En el caso de los segmentos de backend, usa el comando gcloud compute backend-buckets create o gcloud compute backend-buckets update con la marca --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]'

Ejemplo con el encabezado X-Frame-Options:

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

Ejemplo con el encabezado Strict-Transport-Security:

En el siguiente ejemplo se muestra cómo añadir un encabezado de respuesta personalizado para admitir la seguridad de transporte estricta mediante HTTP (HSTS):

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

API

En el caso de los segmentos de backend, usa la llamada a la API Method: backendBuckets.insert o Method: backendBuckets.update.

En el caso de los servicios de backend, usa la llamada a la API Method: backendServices.insert o Method: backendServices.update.

Usa una de las siguientes llamadas a la 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

Añade el siguiente fragmento al cuerpo de la solicitud JSON:

"customResponseHeaders":HEADER_NAME:[HEADER_VALUE]

Definir encabezados de respuesta para Cloud Storage

Si necesitas definir encabezados HTTP en las respuestas de Cloud Storage (por ejemplo, encabezados de política de recursos entre orígenes, X-Frame-Options o X-XSS-Protection),Google Cloud te ofrece la opción de usar encabezados personalizados para Cloud CDN con Cloud Storage. Para ello, configure encabezados personalizados a nivel de contenedor backend del balanceador de carga, tal como se describe en esta página.

Los encabezados de respuesta personalizados configurados a nivel de contenedor de backend solo se añaden a las respuestas si la solicitud del cliente se envía a la dirección IP del balanceador de carga. Los encabezados personalizados no se añaden a las respuestas si la solicitud del cliente se ha enviado directamente a la API Cloud Storage.

Usar encabezados personalizados con Google Cloud Armor

Cuando configuras una política de seguridad de Cloud Armor, puedes configurar Cloud Armor para que inserte un encabezado y un valor personalizados. Si tu política de seguridad de Cloud Armor está configurada para insertar el mismo nombre de encabezado personalizado que los encabezados personalizados de tu balanceador de carga de aplicaciones externo global o de tu balanceador de carga de aplicaciones clásico, el valor del encabezado especificado en tu política de seguridad de Cloud Armor se sobrescribe con el valor rellenado por el balanceador de carga. Si no quieres que se sobrescriba la política de Cloud Armor, asegúrate de no usar el mismo nombre.

Limitaciones

Las siguientes limitaciones se aplican a los encabezados personalizados que se usan con los balanceadores de carga globales:

  • El tamaño total de todos los encabezados de solicitud personalizados (con el nombre y el valor combinados, antes de la expansión de variables) de cada servicio de backend no debe superar los 8 KB ni los 16 encabezados de solicitud.
  • El tamaño total de todos los encabezados de respuesta personalizados (con el nombre y el valor combinados, antes de la expansión de variables) de cada servicio de backend no debe superar los 8 KB ni los 16 encabezados de respuesta.