Configurer les signatures de messages HTTP dans les ACL du locataire

Cette fonctionnalité est offerte uniquement aux clients du plan Entreprise. Pour en savoir plus, consultez la page Tarification.

Les listes de contrôle d’accès (ACL) réseau du locataire Auth0 permettent aux locataires Entreprise d’évaluer et d’imposer une validation cryptographique de l’origine du trafic HTTP entrant à l’aide des signatures de messages HTTP RFC 9421 (HMAC-SHA256). En inspectant les signatures des requêtes directement à la périphérie du réseau Auth0, vous pouvez vous assurer que le trafic provient exclusivement de mandataires périphériques ou de passerelles API de confiance, ce qui permet de prévenir l’usurpation de requêtes, la falsification de paramètres et le contournement direct du locataire.

Cas d’utilisation et enjeu de sécurité

Lorsqu’elles hébergent des flux d’authentification, les organisations déploient souvent des proxys inverses ou des passerelles en périphérie (comme Cloudflare Workers, Kong ou Envoy) en aval d’Auth0 afin d’appliquer des politiques de sécurité personnalisées, un filtrage des adresses IP ou un enrichissement des en-têtes. Si un attaquant découvre le domaine de votre locataire Auth0 (p. ex., https://YOUR_AUTH0_DOMAIN.com), il peut envoyer des requêtes directement aux principaux points de terminaison d’authentification, comme /oauth/token ou /authorize, et ainsi contourner vos contrôles de sécurité en périphérie. Les clés API statiques classiques placées dans des en-têtes personnalisés risquent d’être interceptées ou de fuiter.

Fonctionnement

Lorsque vous imposez les signatures de messages HTTP (HTTP Message Signatures) dans les ACL du locataire :

Votre mandataire périphérique calcule une signature cryptographique HMAC-SHA256 qui couvre les attributs HTTP essentiels (comme @method, @path et les paires clé-valeur brutes @query-param), ainsi que les métadonnées requises (created, expires et keyid).
Lorsque le trafic atteint Auth0, les ACL du locataire vérifient la signature HMAC et les paramètres d’horodatage avant de traiter la requête.
Auth0 bloque immédiatement, au niveau de la couche réseau, les requêtes directes, non signées, altérées ou expirées.

Critères d’évaluation des signatures

Auth0 vérifie les éléments suivants dans les signatures :

L’algorithme doit être HMAC-SHA256 (hmac-sha256).
La signature peut couvrir les composants dérivés suivants de la requête HTTP :

Composants du message HTTP	Description
`@method`	Vérifie la méthode de la requête HTTP (p. ex., `POST`, `GET`)
`@path`	Vérifie le chemin cible (sans les paramètres de requête)
`@query-param`	Vérifie des paramètres de requête nommés précis et leurs valeurs (p. ex., `"@query-param";name="state"`), ce qui associe les signatures à des requêtes d’autorisation précises et renforce la protection contre la relecture

Chaque String d’entrée de signature doit inclure les paramètres created, expires et keyid. Les requêtes auxquelles il manque l’un de ces paramètres sont considérées comme non correspondantes.
La fenêtre de validité de la signature ne peut pas dépasser 1 heure (expires - created <= 3600), et Auth0 applique une tolérance intégrée de 60 secondes pour le décalage d’horloge (created <= now + 60s et now <= expires + 60s).
Les requêtes contenant plusieurs étiquettes de dictionnaire de signature sont rejetées.

Configurer

Enregistrer la clé de connexion du mandataire périphérique

Créez une clé HMAC-SHA256 pour signer les requêtes HTTP envoyées par votre mandataire périphérique.

POST /api/v2/keys/network-acls
Content-Type: application/json
Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}

{
  "name": "edge-proxy-signing-key-v1",
  "alg": "hmac-sha256",
  "value": "KEY_VALUE"
}

Le champ value doit être une String encodée en Base64 qui, une fois décodée, fait au minimum 32 octets bruts et au maximum 512 octets.

Exemple de réponse

{
  "id": "key_aBcDeFgH",
  "name": "edge-proxy-signing-key-v1",
  "alg": "hmac-sha256",
  "fingerprint": "2af9255caa009789b913e5075072dc86af7b7c85d550201c04730431ecd335b5",
  "created_at": "2026-09-04T10:00:00.000Z",
  "updated_at": "2026-09-04T10:00:00.000Z"
}

Conservez l’id renvoyé (p. ex. key_aBcDeFgH). Vous le fournirez comme paramètre keyid dans vos en-têtes HTTP Signature-Input et l’associerez aux règles de l’ACL du locataire.

Configurer les en-têtes de requête en amont

Votre mandataire périphérique ou votre service de signature doit ajouter deux en-têtes standards RFC 9421 (Signature-Input et Signature) à toutes les requêtes transférées. Si votre fournisseur utilise une bibliothèque à code source ouvert, nous vous recommandons de vérifier auprès de lui.

Construire la base de signature

Conformément à la section 2.5 de la RFC 9421, la base de signature se compose d’une ligne par composant couvert, dans l’ordre exact indiqué dans Signature-Input, la dernière ligne étant @signature-params :

"@method": POST
"@path": /oauth/token
"@signature-params": ("@method" "@path");created=1752019200;expires=1752019500;keyid="key_aBcDeFgH"

Exemples d’en-têtes

Consultez les exemples d’en-têtes suivants pour savoir comment utiliser Signature-Input et Signature. Exemple pour (POST /oauth/token)

Signature-Input: sig1=("@method" "@path");created=1752019200;expires=1752019500;keyid="key_aBcDeFgH"
Signature: sig1=:Ic2zxAtZmz2iy0g7qMxEGAic6EH8t70Soh+pC6/Y5L8=:

Exemple avec le paramètre state dans une requête GET /authorize?state=abc123xyz&client_id=myclient

Signature-Input: sig1=("@method" "@path" "@query-param";name="state");created=1752019200;expires=1752019500;keyid="key_aBcDeFgH"
Signature: sig1=:OCnwy3NadPiHa1qmtFVHKaSxLebfdJMjqTPEOByO+yw=:

Configurer les règles de l’ACL du locataire

Pour exiger des signatures valides, créez une règle d’ACL du locataire qui bloque les requêtes selon le signal http_message_signature.

Bloquer les requêtes non signées ou invalides

Pour bloquer toute requête entrante qui ne contient pas de signature de message HTTP valide signée par une clé autorisée, configurez une règle not_match semblable à l’exemple ci-dessous. Nous vous recommandons de configurer le mode de surveillance afin d’évaluer l’incidence de la règle not_match.

POST /api/v2/network-acls
Content-Type: application/json
Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}

{
  "description": "Block requests not signed by trusted edge proxy",
  "active": true,
  "priority": 10,
  "rule": {
    "action": { 
      "block": true 
    },
    "scope": "tenant",
    "not_match": {
      "http_message_signature": {
        "keys": [
          { "id": "key_aBcDeFgH" }
        ]
      }
    }
  }
}

Rotation des clés sans interruption de service

Vous pouvez effectuer la rotation des secrets de signature sans interrompre le trafic en direct en attribuant plusieurs identifiants de clé actifs à une règle ACL.

Générez un nouvel identifiant de clé à l’aide du terminal Créer une clé ACL réseau.

Pour utiliser Management API, vous devez obtenir un jeton d’accès Management API avec les permissions suivantes : create:network_acl_keys, update:network_acls et delete:network_acl_keys.

Mettez à jour la règle ACL. Pour ce faire, ajoutez le nouvel identifiant de clé au tableau http_message_signature.keys, en plus de la clé active (jusqu’à 10 clés permises par règle) :

"keys": [
  { "id": "key_aBcDeFgH" },
  { "id": "key_xYzWvUtS" }
]

Avant de passer à l’étape suivante, nous vous recommandons de vérifier manuellement que la nouvelle clé est acceptée. Un délai peut s’écouler entre la mise à jour de la règle et son application.

Mettez à jour la signature en périphérie. Configurez votre mandataire périphérique pour qu’il commence à signer le trafic entrant avec le nouvel identifiant de clé (exemple : key_xYzWvUtS).
Surveillez les journaux du locataire. Inspectez l’événement de journal acls_summary. Vérifiez le champ valid_signature_key_ids dans les détails du journal pour confirmer que le trafic entrant est bien validé avec le nouvel identifiant de clé :

{
  "type": "acls_summary",
  "details": {
    "stats": [
      {
        "acl_id": "acl_abc123",
        "action": "ACTION_TYPE_BLOCK",
        "valid_signature_key_ids": ["key_xYzWvUtS"]
      }
    ]
  }
}

Mettez l’ancienne clé hors service. Une fois que valid_signature_key_ids ne fait plus référence à key_aBcDeFgH, retirez l’ID de l’ancienne clé de la règle ACL et appelez le terminal Delete Network ACL Key :

DELETE /api/v2/keys/network-acls/key_aBcDeFgH

Limites

Tenez compte des limites suivantes :

Vous pouvez utiliser jusqu’à 10 clés actives par locataire et associer jusqu’à 10 identifiants de clé par règle de liste de contrôle d’accès (ACL).
Les points de terminaison de clés de Management API sont limités à 10 requêtes par seconde (RPS) pour les opérations de lecture (network_acl_keys_read) et à 5 RPS pour les opérations d’écriture (network_acl_keys_write).

Protéger votre application

Effectuer des requêtes d’API au nom de l’utilisateur

Protégez votre tenant

Configurer les signatures de messages HTTP dans les ACL du locataire

Cas d’utilisation et enjeu de sécurité

Fonctionnement

Critères d’évaluation des signatures

Configurer

Enregistrer la clé de connexion du mandataire périphérique

Configurer les en-têtes de requête en amont

Construire la base de signature

Exemples d’en-têtes

Configurer les règles de l’ACL du locataire

Bloquer les requêtes non signées ou invalides

Rotation des clés sans interruption de service

Limites

​Cas d’utilisation et enjeu de sécurité

​Fonctionnement

​Critères d’évaluation des signatures

​Configurer

​Enregistrer la clé de connexion du mandataire périphérique

​Configurer les en-têtes de requête en amont

​Construire la base de signature

​Exemples d’en-têtes

​Configurer les règles de l’ACL du locataire

​Bloquer les requêtes non signées ou invalides

​Rotation des clés sans interruption de service

​Limites

Cas d’utilisation et enjeu de sécurité

Fonctionnement

Critères d’évaluation des signatures

Configurer

Enregistrer la clé de connexion du mandataire périphérique

Configurer les en-têtes de requête en amont

Construire la base de signature

Exemples d’en-têtes

Configurer les règles de l’ACL du locataire

Bloquer les requêtes non signées ou invalides

Rotation des clés sans interruption de service

Limites