Demonstrating Proof-of-Possession (DPoP)

Découvrez comment utiliser Demonstrating Proof-of-Possession (DPoP) pour lier les jetons d’accès à l’émetteur dans Auth0.

Demonstrating Proof-of-Possession (DPoP) est une extension du framework OAuth 2.0 qui lie, ou associe à l’émetteur, les jetons d’accès à l’aide de la cryptographie asymétrique et de JSON Web Tokens (JWTs) à la couche applicative. DPoP garantit que seule l’application cliente qui a demandé le jeton d’accès, et qui possède la clé privée, peut l’utiliser. Cela empêche l’utilisation abusive de jetons volés.

DPoP utilise une paire de clés publique/privée pour créer une preuve DPoP sous la forme d’un JSON Web Token (JWT) signé. La preuve DPoP contient :

• La clé publique du client (jwk).
• Le payload faisant référence à la requête de jeton d’accès, y compris la méthode (htm) et l’URI (htu).
• Une signature créée à l’aide de la clé privée du client.
• Un ID unique (jti) pour prévenir la réutilisation.
• Pour chaque requête d’API, un hachage SHA-256 (ath) du jeton d’accès encodé en base64url.
• Facultatif : pour les clients publics, une claim nonce pour s’assurer que l’application cliente a généré récemment le DPoP Proof JWT.

L’application cliente envoie le DPoP Proof JWT dans une requête de jeton au serveur d’autorisation d’Auth0. Une fois que le serveur d’autorisation d’Auth0 a validé le DPoP Proof JWT, il lie le jeton d’accès émis à la clé publique du client.

​

Cas d’utilisation courants

Découvrez quelques cas d’utilisation courants de DPoP :

• Applications monopage (SPAs) et applications mobiles : En tant que clients publics, les SPAs et les applications mobiles ne disposent pas d’un environnement fiable et confidentiel, comme un serveur backend, pour stocker en toute sécurité les secrets client, ce qui les rend vulnérables au vol de jetons. DPoP atténue cette vulnérabilité de sécurité en liant les jetons d’accès à la clé publique de l’application cliente et en créant ainsi un DPoP Proof JWT. L’application cliente signe le DPoP Proof JWT avec sa clé privée et l’envoie avec une requête d’autorisation. Le Auth0 Authorization Server valide le DPoP Proof JWT et, s’il est valide, lie le jeton d’accès émis à la clé publique du client.
• Intégrations d’API tierces : Si un agent IA intégré à votre application cliente envoie une requête à une API tierce au nom de l’utilisateur à l’aide d’un DPoP Proof JWT, alors le serveur de ressources peut valider par des moyens cryptographiques que la requête provient de l’agent IA et non d’un tiers non autorisé.

​

Types de grant d’application pris en charge

Auth0 prend en charge les types de grant d’application suivants pour le sender constraining avec DPoP :

Type de grant	Description
authorization_code	Grant de code d’autorisation
client_credentials	Grant Client Credentials
password	Grant Resource Owner Password
refresh_token	Grant Refresh Token
urn:ietf:params:oauth:grant-type:device_code	Grant d’autorisation de l’appareil
http://auth0.com/oauth/grant-type/password-realm	Utilise un grant d’extension semblable au grant Resource Owner Password, avec la possibilité d’indiquer un realm précis
http://auth0.com/oauth/grant-type/passwordless/otp	Requête de grant Passwordless
http://auth0.com/oauth/grant-type/mfa-oob	Requête de grant OOB d’authentification multifacteur
http://auth0.com/oauth/grant-type/mfa-otp	Requête de grant OTP d’authentification multifacteur
http://auth0.com/oauth/grant-type/mfa-recovery-code	Requête de grant de récupération d’authentification multifacteur
urn:ietf:params:oauth:grant-type:token-exchange	Requête de grant Custom Token Exchange
urn:okta:params:oauth:grant-type:webauthn	Requête de grant WebAuthn

​

Fonctionnement

Le diagramme de séquence suivant illustre les grandes étapes du flux DPoP d’Auth0 :

1. Lorsqu’elle demande un jeton d’accès au serveur d’autorisation Auth0, l’application cliente génère une paire de clés cryptographiques unique et utilise la clé publique pour prouver qu’elle possède bien la clé privée.
2. L’application cliente génère le DPoP Proof JWT et l’envoie au point de terminaison /token du serveur d’autorisation Auth0.
3. Le serveur d’autorisation Auth0 vérifie le DPoP Proof JWT et, s’il est valide, émet le jeton d’accès et le lie à la clé publique du client.
4. Avant d’envoyer une requête à l’API Customer, l’application cliente génère un nouveau DPoP Proof JWT pour prouver qu’elle possède la clé privée associée au jeton. L’application cliente envoie le DPoP Proof JWT ainsi que le jeton d’accès lié à l’émetteur au serveur de ressources.
5. Le serveur de ressources vérifie le DPoP Proof JWT pour s’assurer que seul le propriétaire légitime du jeton, ou l’application cliente d’origine, peut l’utiliser pour accéder aux ressources protégées. Pour demander un jeton d’accès à l’aide d’un jeton d’actualisation, l’application cliente génère un nouveau DPoP Proof JWT afin de s’assurer que le jeton d’actualisation est lié à la clé publique du client.

​

Lier des jetons à l’émetteur à l’aide de DPoP dans Auth0

Le diagramme suivant présente le flux de bout en bout pour lier des jetons à l’émetteur à l’aide de DPoP dans Auth0 :

Les sections suivantes vous guident, étape par étape, dans le flux DPoP d’Auth0 avec des exemples de code pour la mise en œuvre :

• Prérequis
• Étape 1 : L’application cliente génère une paire de clés DPoP
• Étape 2 : L’application cliente crée un DPoP Proof JWT
• Étape 3 : L’application cliente demande un jeton lié à DPoP
• Étape 4 : Le serveur d’autorisation Auth0 valide le DPoP Proof JWT
• Étape 5 : L’application cliente effectue une requête à l’API avec le jeton lié à DPoP et le DPoP Proof JWT
• Étape 6 : Gérer l’actualisation du jeton avec DPoP

​

Prérequis

Avant de commencer, assurez-vous d’avoir :

• Configurer Sender Constraining pour votre application cliente et votre serveur de ressources.

​

Étape 1 : l’application cliente génère une paire de clés DPoP

Pour DPoP, l’application cliente doit générer une paire de clés cryptographiques asymétriques. Auth0 prend en charge l’utilisation des courbes elliptiques, comme les clés ES256. Cette paire de clés est propre à votre application cliente et doit être stockée de façon sécurisée, par exemple dans un magasin de clés matériel.

L’application cliente garde la clé privée secrète et inclut la clé publique dans le JSON Web Token (JWT) de preuve DPoP, qui sert de « preuve de possession » à l’étape 2.

​

Étape 2 : L’application cliente crée un DPoP Proof JWT

Avant de demander un jeton d’accès lié à DPoP au point de terminaison /token de l’Auth0 Authorization Server, votre application cliente doit créer un DPoP Proof JWT. Un DPoP Proof JWT est un JSON Web Token (JWT) signé à l’aide de la clé privée de votre client et servant de « preuve de possession ».

Le DPoP Proof JWT se compose d’un en-tête JWT et d’une charge utile contenant des claims associées à la demande de jeton :

​

Revendications de l’en-tête JWT

Revendication du DPoP Proof JWT	Description
typ	Défini à dpop+jwt.
alg	L’algorithme de signature asymétrique utilisé, comme RS256 ou ES256.
jwk	Une représentation de la clé publique de votre client au format JSON Web Key (JWK).

​

Claims du payload JWT

Claim du JWT de preuve DPoP	Description
jti	Un identifiant unique du JWT pour empêcher les attaques par rejeu.
htm	La méthode HTTP de la requête à laquelle la preuve DPoP s’applique, par exemple POST pour les requêtes de jeton et GET pour les appels d’API.
htu	L’URI HTTP de la requête à laquelle le JWT de preuve DPoP s’applique, sans le fragment ni les paramètres de requête. Par exemple : https://api.example.com/data?param=1#section1 devient https://api.example.com/data.
iat	L’horodatage de création du JWT.
ath	Pour les appels d’API avec un jeton d’accès, un hachage SHA-256 du jeton d’accès encodé en base64url.
nonce	Pour les clients publics qui exigent un nonce, une valeur nonce fournie par le serveur.

Une fois que l’application cliente a créé le JWT de preuve DPoP, elle le signe avec la clé privée générée à l’étape 1.

L’exemple de code suivant montre comment créer et signer un JWT de preuve DPoP dans votre application cliente :

import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// Générer une paire de clés DPoP
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

// Construire le DPoP Proof JWT pour la demande de jeton
const jti = randomBytes(16).toString('base64url');
const jwk = keyPair.publicKey.export({ format: 'jwk' });
const dpopHeader = jwt.sign({
    jti,
    htm: 'POST',
    htu: 'https://[TENANT]/oauth/token',
    iat: Date.now() / 1000,
  },
  keyPair.privateKey,
  {
    algorithm: 'ES256',
    header: {
      typ: 'dpop+jwt',
      jwk,
    },
  });

​

Étape 3 : L’application cliente demande un jeton lié à DPoP

Lorsque votre application cliente demande un jeton d’accès au point de terminaison /token du serveur d’autorisation Auth0, elle inclut le JWT de preuve DPoP dans l’en-tête HTTP de la requête :

DPoP: {DPoP_proof_JWT_value}

Voici un exemple de requête de jeton d’accès dans laquelle l’en-tête HTTP DPoP est renseigné à l’aide d’un DPoP Proof JWT :

POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
DPoP: {DPoP Proof JWT}
Authorization: Basic Y2xpZW50MTIzOm15c2VjcmV0
Cache-Control: no-cache
grant_type=client_credentials&client_id=client123

Pour implémenter la demande d’un jeton d’accès lié à DPoP dans votre application cliente, utilisez l’exemple de code suivant, qui effectue les opérations suivantes :

1. Remplit l’en-tête HTTP DPoP avec un JWT de preuve DPoP signé.
2. Envoie l’en-tête HTTP DPoP avec un JWT de preuve DPoP signé dans une requête de jeton d’accès vers le point de terminaison /token.
3. Traite la réponse de l’Auth0 Authorization Server.

// Effectuer la requête vers le point de terminaison /oauth/token
// Remplacer [...] par votre grant_type, client_id et URL de tenant réels
const response = await fetch('https://[TENANT]/oauth/token', {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: '...',
      client_id: '...',
      // Autres paramètres du corps ici
    }),
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      // Ajouter l'en-tête DPoP
      dpop: dpopHeader
    }
  });

// Traiter la réponse du serveur d'autorisation Auth0
const result = await response.json();
console.log('Initial token request result:', result);

​

Clients publics

Si un client public, comme une application monopage (SPA) ou une application mobile, demande un jeton d’accès lié à DPoP, vous n’aurez pas de secret client ni d’autres paramètres d’authentification du client. Dans ce cas, et conformément à la RFC 9449, Auth0 exige que votre en-tête HTTP DPoP contienne une valeur nonce afin de s’assurer que l’application cliente a généré récemment le DPoP Proof JWT. Il s’agit du comportement attendu, car cela permet au serveur d’autorisation de s’assurer que la preuve DPoP est récente et de limiter la période pendant laquelle une preuve peut être utilisée.

Si un client public effectue une requête /token et n’inclut pas de valeur nonce dans l’en-tête HTTP DPoP, Auth0 renvoie un code HTTP 400 et un message d’erreur comme celui-ci :

{
  error: 'use_dpop_nonce',
  error_description: 'Le serveur d'autorisation exige un nonce dans la preuve DPoP'
}

Auth0 inclut un en-tête DPoP-Nonce dans les en-têtes de la réponse. Cela correspond au flux standard « challenge-response » défini dans la spécification DPoP. Vous devez utiliser la valeur de l’en-tête DPoP-Nonce et régénérer la preuve DPoP (comme à la Step 2), inclure un claim nonce avec cette valeur, puis renvoyer la requête à l’endpoint /token.

L’exemple de code suivant montre le flux de bout en bout lorsqu’une requête /token est envoyée, puis renvoyée avec un claim nonce par un client public :

import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// Générer une paire de clés DPoP
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

/**
 * Fonction utilitaire pour générer un DPoP Proof JWT.
 * @param {string} method - Méthode HTTP (p. ex., 'POST', 'GET').
 * @param {string} url - URL complète de la requête.
 * @param {string} [nonce] - Valeur DPoP-Nonce facultative provenant du serveur.
 * @param {string} [accessToken] - Jeton d'accès facultatif à hacher pour la revendication 'ath'.
 * @returns {string} Le DPoP Proof JWT signé.
 */
function generateDPoPHeader(method, url, nonce) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

// Demander le jeton d'accès pour la première fois sans nonce 
async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // Autres paramètres du corps ici
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://[TENANT]/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// La première fois qu'on demande des jetons, on n'aura pas de nonce
let { response, result } = await getTokens(); 
console.log('Initial token request result:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');

  console.log('Received nonce:', nonce);

  // Réessayer avec le nonce
  ({ response, result } = await getTokens(nonce)); 

  console.log('Tokens received:', result);
}

​

Étape 4 : Auth0 Authorization Server valide le DPoP Proof JWT

Lorsque Auth0 Authorization Server reçoit la demande de jeton, il effectue les opérations suivantes :

• Extrait le DPoP Proof JWT, sa clé publique et sa signature.
• Vérifie la signature à l’aide de la clé publique fournie.
• Valide les claims htm, htu, jti, et iat.
• Si tout est valide, il émet un jeton d’accès. Auth0 Authorization Server inclut une claim de confirmation, cnf, dans le jeton d’accès. La claim cnf contient l’empreinte (hachage) de la clé publique extraite du DPoP Proof JWT. En l’incluant dans le jeton d’accès, Auth0 Authorization Server lie le jeton d’accès à cette clé publique précise, ou le « restreint à l’émetteur ».
• Définit le token_type dans l’en-tête Authorization sur DPoP plutôt que sur Bearer dans la réponse de jeton. Traditionnellement, lorsque le jeton d’accès est transmis dans l’en-tête Authorization, il est défini sur Bearer. Toutefois, comme nous transmettons un jeton d’accès lié à une clé publique à l’aide de DPoP, il est plutôt défini sur DPoP.
• Auth0 Authorization Server émet ensuite le jeton d’accès DPoP restreint à l’émetteur à votre application cliente.

​

Étape 5 : L’application cliente appelle l’API avec le jeton lié à DPoP et le DPoP Proof JWT

Pour chaque appel d’API à un serveur de ressources qui applique DPoP, votre application cliente doit présenter à la fois le jeton d’accès lié à DPoP et un nouveau DPoP Proof JWT.

En exigeant un DPoP Proof JWT avec chaque requête d’API, DPoP garantit que seule l’application cliente qui possède la clé privée peut utiliser le jeton d’accès.

Pour une nouvelle requête d’API, l’application cliente :

1. Génère un nouveau DPoP Proof JWT avec les claims suivantes :

• La claim htm correspond à la méthode HTTP de la requête d’API, comme GET ou POST.
• La claim htu correspond à l’URI de la requête d’API.
• La claim ath correspond au hachage SHA-256 encodé en base64url du jeton d’accès lié à DPoP que vous avez reçu à l’étape 3.

2. Signe de façon cryptographique le nouveau DPoP Proof JWT avec la clé privée du client.

3. Inclut le jeton d’accès lié à DPoP dans l’en-tête Authorization au moyen du schéma d’authentification DPoP :

// Le schéma DPoP correspond au token_type reçu du serveur d'autorisation
Authorization: DPoP {access_token}

4. Inclut le DPoP Proof JWT nouvellement généré dans l’en-tête HTTP DPoP :

DPoP: {new_dpop_proof_jwt}

L’en-tête HTTP DPoP doit inclure une revendication ath supplémentaire. La revendication ath est un hachage SHA256 du jeton d’accès émis, encodé en base64url.

Le serveur de ressources :

• Reçoit la requête API et extrait le jeton d’accès, la preuve JWT DPoP, la clé publique et la signature.
• Vérifie la signature de la preuve JWT DPoP à l’aide de la clé publique figurant dans son en-tête jwk.
• Valide les revendications htm, htu, jti, iat et ath.
• Vérifie que la clé publique indiquée dans la preuve JWT DPoP, dans son en-tête jwk, correspond à la clé publique liée au jeton d’accès par la revendication cnf.jkt de ce jeton.

Le serveur de ressources est responsable d’implémenter la protection contre la relecture de jti ; tous les Auth0 SDKs ne l’appliquent pas d’emblée.

Si toutes les vérifications réussissent, le serveur de ressources autorise la requête. Sinon, il la rejette et l’accès est refusé.

L’exemple de code suivant demande un jeton d’accès à Auth0 à l’aide de DPoP, puis effectue une requête vers le point de terminaison /userinfo à l’aide d’un jeton d’accès lié à DPoP :

import { generateKeyPairSync, randomBytes, createHash } from 'node:crypto';
import jwt from 'jsonwebtoken';

const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

function hashToken(token) {
  return createHash('sha256').update(token).digest('base64url');
}

function generateDPoPHeader(method, url, nonce, accessToken) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce,

      // Inclure facultativement une revendication `ath` contenant un hachage du jeton d'accès
      ...(accessToken ? { ath: hashToken(accessToken) } : {}),
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // Autres paramètres du corps ici
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://test1.local.dev.auth0.com/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// La première fois, nous n'aurons pas de nonce
let { response, result } = await getTokens(); 
console.log('Initial token request result:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');
  console.log('Received nonce:', nonce);
  ({ response, result } = await getTokens(nonce)); // Réessayer avec le nonce
  console.log('Tokens received:', result);
}

// Appeler maintenant /userinfo avec DPoP
const userInfoResponse = await fetch('https://[TENANT]/userinfo', {
  method: 'GET',
  headers: {
    // Transmettre notre jeton d'accès avec le schéma d'autorisation DPoP
    Authorization: `DPoP ${result.access_token}`,

    // Inclure un en-tête DPoP, cette fois avec le hachage du jeton d'accès
    dpop: generateDPoPHeader('GET', 'https://[TENANT]/userinfo', nonce, result.access_token),
  },
});

console.log('User info response status:', userInfoResponse.status);
console.log('User info result:', await userInfoResponse.json());

​

Étape 6 : Gérer l’actualisation du jeton avec DPoP

Lorsque votre jeton d’accès lié à DPoP expire, vous pouvez utiliser un jeton d’actualisation pour en obtenir un nouveau. Une requête de jeton d’actualisation nécessite un DPoP Proof JWT généré à l’aide de la même paire de clés que celle utilisée dans la requête de jeton initiale.

Voici comment fonctionne le flux de jeton d’actualisation avec DPoP dans Auth0 :

L’application cliente :

• Envoie une requête de jeton d’actualisation au point de terminaison /token de l’Auth0 Authorization Server.
• Génère un DPoP Proof JWT pour la requête de jeton d’actualisation (comme à l’étape 2, avec htm défini à POST et htu défini comme l’URI du point de terminaison de jeton).
• Inclut le DPoP Proof JWT dans l’en-tête HTTP DPoP.

L’Auth0 Authorization Server :

• Valide le DPoP Proof JWT (comme à l’étape 4) et émet un nouveau jeton d’accès lié à DPoP.

​

Considérations importantes

Lors de la mise en œuvre de DPoP dans vos applications clientes, tenez compte des éléments suivants :

• Sécurité de la clé privée : La sécurité de votre mise en œuvre de DPoP dépend de celle de la clé privée de votre client; vous devez donc la protéger contre tout accès non autorisé. Les clés privées doivent être générées et stockées dans un support matériel sécurisé, puis marquées comme non exportables.
• Protection contre les attaques par rejeu (jti** et dpop-nonce ) :** La claim jti dans le DPoP Proof JWT aide à prévenir les attaques par rejeu visant les ressources protégées, comme le point de terminaison /userinfo. Le serveur d’autorisation Auth0 émet un en-tête HTTP DPoP-Nonce dans sa réponse, que les clients publics doivent inclure sous forme de claim nonce dans les DPoP Proof JWT subséquents pour renforcer la protection contre les attaques par rejeu.
• Limites de débit : Comme le flux défi-réponse DPoP peut parfois nécessiter une requête initiale suivie d’une nouvelle tentative avec le nonce fourni par le serveur, chaque échange compte en pratique comme deux requêtes dans les limites de débit de votre tenant Auth0. Assurez-vous que le volume de requêtes de votre application tient compte de cette surcharge.
• Gestion des erreurs : Vous êtes responsable de mettre en œuvre la logique nécessaire pour gérer les erreurs propres à DPoP provenant du serveur d’autorisation Auth0 ou du serveur de ressources, comme invalid_dpop_proof ou use_dpop_nonce.
• Types de clients : Utilisez DPoP pour les clients publics, comme les Single Page Applications (SPA) ou les applications mobiles qui ne peuvent pas stocker un client secret de façon sécuritaire. Pour les clients confidentiels, comme les services backend avec des client secrets, DPoP ajoute une couche de sécurité, mais ces clients disposent déjà d’autres mécanismes de liaison à l’expéditeur.
• Performance : Comme la génération et la signature de DPoP Proof JWT pour chaque appel d’API ajoutent une légère surcharge, assurez-vous que les opérations cryptographiques de votre application cliente sont efficaces.
• Rotation des clés : Mettez en œuvre une stratégie de rotation de vos paires de clés DPoP pour renforcer la sécurité. Assurez-vous d’utiliser la même paire de clés pendant une même session.
• Persistance : Pour les applications clientes qui doivent maintenir une session et réutiliser des access tokens liés à DPoP, comme les SPA de longue durée, enregistrez et récupérez de façon sécuritaire la paire de clés originale entre les rechargements de l’application. Si une nouvelle paire de clés est générée ou si une autre paire de clés est utilisée, l’access token lié à DPoP devient invalide, puisqu’il est lié cryptographiquement à la clé publique de la paire d’origine. Vous pouvez enregistrer la paire de clés, par exemple, dans l’IndexedDB d’un navigateur ou dans le stockage sécurisé d’une application mobile.

​

En savoir plus

• Configurer Sender Constraining