Lorsque vous configurez des extensions à l'aide de plug-ins ou d'appels pour des services de backend basés sur ext-proc, vous pouvez spécifier les attributs de requête et de connexion à transférer à ces services. Cette page décrit les attributs compatibles 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 :
- Prendre des décisions de routage dynamiques.
- Enrichir les en-têtes de requête avec des informations sur le client.
- Mettre en œuvre des règles de sécurité personnalisées en fonction de l'emplacement du client ou des paramètres TLS.
- Générer 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'appel. Par exemple, pour les extensions de trafic, consultez Configurer une extension de trafic.
La spécification d'attributs avec forwardAttributes est compatible avec les extensions d'autorisation, de bord, de route et de trafic. Vous pouvez implémenter forwardAttributes en
utilisant des plug-ins Wasm ou des appels (avec le
ext_proc
protocole) 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 répertorie 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, bord, route, trafic |
request.mcp_method |
Méthode de requête HTTP, telle que GET ou
POST. |
autorisation |
request.host |
Équivalent pratique de request.headers['host']. |
autorisation, bord, route, trafic |
request.path |
Chemin de l'URL HTTP demandé. | autorisation, bord, route, 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, bord, route, trafic |
request.scheme |
Schéma d'URL HTTP, tel que HTTP ou
HTTPS. Les valeurs de cet attribut sont en minuscules. |
autorisation, bord, route, 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 User-Agent
valeurs
d'en-tête. 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 standard User-Agent. |
bord, 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. |
bord, trafic (uniquement pour les équilibreurs de charge d'application externes globaux et les équilibreurs de charge d'application externes régionaux) |
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
jsonPayload.cacheId champ 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 peuvent être 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, route, trafic |
source.port |
Port source du client. | bord, route, trafic |
source.client_region |
Pays ou région associé à l'adresse IP du client.
La 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. |
bord, 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. |
bord, trafic (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 : !#$%&'*+-.^_`|~. |
bord, trafic (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. |
bord, trafic (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 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. Elle est 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 du certificat de pair dans la connexion TLS en aval, encodé en hexadécimal, le cas échéant. | autorisation, bord, trafic |
connection.tls_cipher_suite |
Suite de chiffrement négociée lors du handshake TLS. La valeur
se compose de quatre caractères hexadécimaux. Elle est définie par le Registre de l'IANA portant sur la suite de chiffrement TLS.
Par exemple, 009C correspond à
TLS_RSA_WITH_AES_128_GCM_SHA256. Cette valeur est vide
pour QUIC et pour les connexions clientes non chiffrées. |
trafic |
connection.tls_ja3_fingerprint |
Empreinte TLS/SSL JA3 si le client se connecte à l'aide de
HTTPS, HTTP/2, ou HTTP/3. |
trafic |
connection.tls_ja4_fingerprint |
Empreinte TLS/SSL JA4 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 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, sinon
elle est 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
est plus de 50 octets, le 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 |
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, séparées par une virgule. Les extensions SAN sont extraites du
client certificate. L'ID SPIFFE n'est pas inclus dans le
client_cert_uri_sans champ. Si
client_cert_uri_sans dépasse 512 octets, le
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éfinie sur une chaîne vide. |
autorisation, trafic |
connection.client_cert_dnsname_sans |
Liste des extensions SAN de
type DNSName encodées en base64, séparées par une virgule. Les extensions SAN sont extraites de
the 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 |
Horodatage (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 |
Horodatage (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
est plus long que 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éfinie sur une chaîne vide. |
autorisation, trafic |
connection.client_cert_subject_dn |
Champ complet, encodé au format DER en base64, tiré du certificat.Subject Si client_cert_subject_dn
est plus long que 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éfinie 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éfini 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 de cette page.
Configuration requise : pour envoyer des attributs à l'extension, vous devez les répertorier explicitement dans le champ
forwardAttributesde la configuration de votre extension. Si vous ne répertoriez pas un attribut dans ce champ, l'équilibreur de charge ne transfère pas cet attribut spécifique à votre extension.Limites de taille : vous pouvez configurer un maximum de 16 attributs pour une seule extension.
Attributs mTLS : les attributs de certificat client (
connection.client_cert_*) ne sont renseignés dans les données transmises à votre extension que si vous avez activé mTLS et que le client présente un certificat.