Attributs acceptés

Lorsque vous configurez des extensions à l'aide de plug-ins ou d'appels pour les services de backend basés sur ext-proc, vous pouvez spécifier les attributs de requête et de connexion à transférer vers ces services. Cette page décrit les attributs acceptés et indique ceux qui sont disponibles pour chaque type d'extension.

En configurant des extensions pour transférer des attributs spécifiques, vous pouvez effectuer les opérations suivantes :

• Prenez des décisions de routage dynamiques.
• Enrichissez les en-têtes de requête avec des informations sur le client.
• Implémentez des règles de sécurité personnalisées basées sur l'emplacement du client ou les paramètres TLS.
• Générez des journaux personnalisés détaillés.

Vous pouvez spécifier des attributs avec le champ forwardAttributes dans la configuration YAML pour les extensions de plug-in et d'accroche. Par exemple, pour les extensions de trafic, consultez Configurer une extension de trafic.

La spécification d'attributs avec forwardAttributes est acceptée pour les extensions d'autorisation, de périphérie, de route et de trafic. Vous pouvez implémenter forwardAttributes en utilisant des plug-ins Wasm ou des callouts (avec le protocole ext_proc) sur les produits suivants :

• Équilibreurs de charge d'application externes régionaux
• Équilibreurs de charge d'application internes régionaux
• Équilibreurs de charge d'application externes globaux
• Équilibreurs de charge d'application internes interrégionaux

Le tableau suivant liste les attributs et les extensions compatibles :

Attribut	Description	Extensions
request.origin	Valeur de l'en-tête d'origine dans une requête pour les cas d'utilisation CORS (Cross-Origin Resource Sharing).	trafic
request.method	Méthode de requête HTTP, telle que GET ou POST.	autorisation, périphérie, itinéraire, trafic
request.mcp_method	Méthode de requête HTTP, telle que GET ou POST.	autorisation
request.host	Équivaut à request.headers['host'].	autorisation, périphérie, itinéraire, trafic
request.path	Chemin d'URL HTTP demandé.	autorisation, périphérie, itinéraire, trafic
request.query	Requête d'URL HTTP, au format name1=value&name2=value2, telle qu'elle apparaît sur la première ligne de la requête HTTP. Aucun décodage n'est effectué.	autorisation, périphérie, itinéraire, trafic
request.scheme	Schéma d'URL HTTP, tel que HTTP ou HTTPS. Les valeurs de cet attribut sont en minuscules.	autorisation, périphérie, itinéraire, trafic
request.backend_service_name	Service de backend auquel la requête est transférée.	autorisation, trafic
request.backend_service_project_number	Lorsqu'un VPC partagé est utilisé, il s'agit du numéro de projet du service de backend auquel la requête est transférée.	autorisation, trafic
request.mcp_param	Paramètre MCP.	autorisation
request.user_agent_family	Type de navigateur du client, dérivé des valeurs d'en-tête User-Agent. Ces valeurs font référence à la chaîne de texte brut que les clients HTTP entrants (tels que les navigateurs Web, les applications mobiles ou les outils automatisés) envoient dans l'en-tête de requête HTTP User-Agent standard.	edge, traffic (trafic) (uniquement pour les équilibreurs de charge d'application externes globaux et les équilibreurs de charge d'application externes régionaux)
request.device_request_type	Type d'appareil du client. Les valeurs possibles pour cet attribut sont APPLE, APPLEWEBKIT, BLACKBERRY, DOCOMO, GECKO, GOOGLE, KHTML, KOREAN, MICROSOFT, MSIE, NETFRONT, NOKIA, OBIGO, OPERA, OPENWAVE, OTHER, POLARIS, SEMC, SMIT, TELECA ou USER_DEFINED.	edge, traffic (trafic) (uniquement pour les équilibreurs de charge d'application externes globaux et les équilibreurs de charge d'application externes régionaux)
request.header_order	Ordre des en-têtes HTTP dans la requête du client sous forme de chaîne de noms d'en-têtes séparés par une virgule (par exemple, host,accept,cookie). Cet attribut est compatible avec les en-têtes suivants : accept, accept-charset, accept-encoding, accept-language, connection, content-length, content-type, cookie, host, if-modified-since, ping-from, ping-to, pragma, referer, user-agent, via et x-forwarded-for.	Trafic (uniquement pour les équilibreurs de charge d'application externes globaux)
response.cdn_cache_id	Code d'emplacement et ID de l'instance de cache utilisée pour diffuser la requête. Il s'agit de la même valeur que celle indiquée dans le champ jsonPayload.cacheId des journaux de requêtes Cloud CDN.	Trafic (uniquement pour les équilibreurs de charge d'application externes globaux)
response.cdn_cache_status	État actuel de l'instance de cache utilisée pour diffuser la requête. Les valeurs possibles pour cet attribut sont hit, miss, revalidated, stale, uncacheable ou disabled.	Trafic (uniquement pour les équilibreurs de charge d'application externes globaux)
source.ip	Adresse IP du client.	bord, itinéraire, trafic
source.port	Port source du client.	bord, itinéraire, trafic
source.client_region	Pays ou région associé à l'adresse IP du client. Cette valeur est un code de région CLDR au format Unicode, tel que US ou FR. Pour la plupart des pays, ces codes correspondent directement aux codes ISO-3166-2.	edge, traffic (trafic) (uniquement pour les équilibreurs de charge d'application externes globaux et les équilibreurs de charge d'application externes régionaux)
source.client_region_subdivision	Subdivision (une province ou un État, par exemple) du pays associée à l'adresse IP du client. Il s'agit d'un ID de subdivision CLDR au format Unicode, tel que USCA ou CAON. Ces codes Unicode sont dérivés des subdivisions définies par la norme ISO-3166-2.	edge, traffic (uniquement pour les équilibreurs de charge d'application externes globaux)
source.client_city	Nom de la ville d'où provient la requête. Par exemple, Mountain View pour Mountain View en Californie. Il n'existe pas de liste canonique de valeurs valides pour cette variable. Les noms de villes peuvent contenir des lettres, des chiffres et des espaces au format US-ASCII, ainsi que les caractères suivants : !#$%&'*+-.^_`|~.	edge, traffic (uniquement pour les équilibreurs de charge d'application externes globaux)
source.client_city_lat_long	Latitude et longitude de la ville d'origine de la requête, par exemple 37.386051,-122.083851 pour une requête provenant de Mountain View.	edge, traffic (uniquement pour les équilibreurs de charge d'application externes globaux)
connection.client_encrypted	La valeur est true si la connexion entre le client et l'équilibreur de charge est chiffrée (à l'aide de HTTPS, HTTP/2 ou HTTP/3), sinon elle est false.	trafic
connection.client_rtt_msec	Temps de transmission aller-retour estimé entre l'équilibreur de charge et le client HTTP(S), en millisecondes. Il s'agit du paramètre de délai aller-retour lissé (SRTT, Smoothed Round-Trip Time) (tel que défini dans la RFC 2988) mesuré par la pile TCP de l'équilibreur de charge.	Trafic (uniquement pour les équilibreurs de charge d'application externes globaux)
connection.client_protocol	Protocole HTTP utilisé pour la communication entre le client et l'équilibreur de charge. Il peut s'agir de HTTP/1.0, HTTP/1.1, HTTP/2 ou HTTP/3.	trafic
connection.server_ip_address	Adresse IP de l'équilibreur de charge auquel le client se connecte. Cette valeur peut être utile lorsque plusieurs équilibreurs de charge partagent des backends communs. Identique à la dernière adresse IP de l'en-tête X-Forwarded-For.	trafic
connection.server_port	Numéro du port de destination auquel le client se connecte.	trafic
connection.sni	Indication du nom du serveur (telle que définie dans la RFC 6066), si ce nom est fourni par le client lors du handshake TLS ou QUIC. Le nom d'hôte est converti en minuscules et tous les points se trouvant à la fin du nom sont supprimés.	autorisation, bord, trafic
connection.tls_version	Version de TLS négociée entre le client et l'équilibreur de charge lors du handshake SSL. Les valeurs possibles sont TLSv1, TLSv1.1, TLSv1.2 et TLSv1.3. Si le client se connecte à l'aide de QUIC au lieu de TLS, la valeur est QUIC.	bord, trafic
connection.sha256_peer_certificate_digest	Hachage SHA256 encodé en hexadécimal du certificat de pair dans la connexion TLS en aval, le cas échéant.	autorisation, bord, trafic
connection.tls_cipher_suite	La suite de chiffrement négociée lors du handshake TLS. La valeur se compose de quatre chiffres hexadécimaux définis par le Registre des suites de chiffrement TLS de l'IANA. Par exemple, 009C correspond à TLS_RSA_WITH_AES_128_GCM_SHA256. Cette valeur est vide pour QUIC et les connexions clientes non chiffrées.	trafic
connection.tls_ja3_fingerprint	Empreinte JA3 TLS/SSL si le client se connecte à l'aide de HTTPS, HTTP/2 ou HTTP/3.	trafic
connection.tls_ja4_fingerprint	Empreinte JA4 TLS/SSL si le client se connecte à l'aide de HTTPS, HTTP/2 ou HTTP/3.	bord, trafic
connection.client_cert_present	La valeur est true si le client a fourni un certificat lors du handshake TLS. Sinon, elle est false.	autorisation, trafic
connection.client_cert_chain_verified	La valeur est true si la chaîne de certificats client est validée par rapport à une configuration TrustStore configurée ou false.	autorisation, trafic
connection.client_cert_error	Chaînes prédéfinies représentant les conditions d'erreur. Pour plus d'informations sur les chaînes d'erreur, consultez la section Modes de validation des clients mTLS.	autorisation, trafic
connection.client_cert_serial_number	Numéro de série du certificat client. Si le numéro de série dépasse 50 octets, client_cert_error est défini sur client_cert_serial_number_exceeded_size_limit et le numéro de série est défini sur une chaîne vide.	autorisation, trafic
connection.client_cert_spiffe_id	L'ID SPIFFE du champ "Autre nom de l'objet (SAN)". Si la valeur n'est pas valide ou dépasse 2 048 octets, l'ID SPIFFE est défini sur une chaîne vide. Si l'ID SPIFFE dépasse 2 048 octets, client_cert_error est défini sur client_cert_spiffe_id_exceeded_size_limit.	autorisation, trafic
connection.client_cert_uri_sans	Liste des extensions SAN de type URI encodées en base64 et séparées par une virgule. Les extensions SAN sont extraites du certificat client. L'ID SPIFFE n'est pas inclus dans le champ client_cert_uri_sans. Si client_cert_uri_sans dépasse 512 octets, client_cert_error est défini sur client_cert_uri_sans_exceeded_size_limit et la liste d'éléments séparés par des virgules est défini sur une chaîne vide.	autorisation, trafic
connection.client_cert_dnsname_sans	Liste des extensions SAN de type DNSName encodées en base64 et séparées par une virgule. Les extensions SAN sont extraites du certificat client. Si client_cert_dnsname_sans dépasse 512 octets, client_cert_error est défini sur client_cert_dnsname_sans_exceeded_size_limit et la liste d'éléments séparés par des virgules est définie sur une chaîne vide.	autorisation, trafic
connection.client_cert_valid_not_before	Code temporel (format de chaîne de date RFC 3339) avant lequel le certificat client n'est pas valide (par exemple, 2022-07-01T18:05:09+00:00).	autorisation, trafic
connection.client_cert_valid_not_after	Code temporel (au format de chaîne de date RFC 3339) après lequel le certificat client n'est pas valide (par exemple, 2022-07-01T18:05:09+00:00).	autorisation, trafic
connection.client_cert_issuer_dn	Champ Issuer complet, encodé au format DER en base64, tiré du certificat. Si client_cert_issuer_dn dépasse 512 octets, la chaîne client_cert_issuer_dn_exceeded_size_limit est ajoutée à client_cert_error et client_cert_issuer_dn est défini sur une chaîne vide.	autorisation, trafic
connection.client_cert_subject_dn	Champ Subject complet, encodé au format DER en base64, tiré du certificat. Si client_cert_subject_dn dépasse 512 octets, la chaîne client_cert_subject_dn_exceeded_size_limit est ajoutée à client_cert_error et client_cert_subject_dn est défini sur une chaîne vide.	autorisation, trafic
connection.client_cert_leaf	Certificat d'entité finale du client pour une connexion mTLS établie où le certificat a été validé. L'encodage du certificat est conforme à la norme RFC 9440. Cela signifie que le certificat DER binaire est encodé en base64 et délimité de chaque côté par des signes deux-points. Si client_cert_leaf dépasse 16 Ko non encodé, la chaîne client_cert_validated_leaf_exceeded_size_limit est ajoutée à client_cert_error et client_cert_leaf est défini sur une chaîne vide.	autorisation, trafic
connection.client_cert_chain	Liste de certificats séparés par une virgule (dans l'ordre TLS standard) de la chaîne de certificats client pour une connexion mTLS établie où le certificat client a été validé, sans inclure le certificat d'entité finale. L'encodage du certificat est conforme à la norme RFC 9440. Si la taille combinée de client_cert_leaf et client_cert_chain avant encodage en base64 dépasse 16 Ko, la chaîne client_cert_validated_chain_exceeded_size_limit est ajoutée à client_cert_error et client_cert_chain est définie sur une chaîne vide.	autorisation, trafic

Limites

• Disponibilité des attributs : tous les attributs ne sont pas compatibles avec tous les types d'extensions. Pour en savoir plus, consultez le tableau sur cette page.

• Configuration requise : pour envoyer des attributs à l'extension, vous devez les lister explicitement dans le champ forwardAttributes de la configuration de votre extension. Si vous n'indiquez pas d'attribut dans ce champ, l'équilibreur de charge ne transmet pas cet attribut spécifique à votre extension.

• Limites de taille : vous pouvez configurer jusqu'à 16 attributs pour une même extension.

• Attributs mTLS : les attributs du certificat client (connection.client_cert_*) sont renseignés dans les données transmises à votre extension uniquement si vous avez activé mTLS et que le client présente un certificat.