Client Credentials Exchange

Découvrez comment les Hooks peuvent être utilisés avec le point d’extensibilité Client Credentials Exchange, offert pour les connexions de base de données et les connexions Passwordless.

La date de fin de vie (EOL) de Rules et Hooks sera le 18 novembre 2026, et ils ne sont plus offerts aux nouveaux locataires créés à compter du 16 octobre 2023. Les locataires existants ayant des Hooks actifs conserveront l’accès au produit Hooks jusqu’à sa fin de vie.

Nous vous recommandons fortement d’utiliser Actions pour étendre Auth0. Avec Actions, vous avez accès à des informations de type détaillées, à une documentation intégrée et à des packages npm publics, et vous pouvez connecter des intégrations externes qui améliorent votre expérience globale d’extensibilité. Pour en savoir plus sur ce qu’offre Actions, consultez Comprendre le fonctionnement d’Auth0 Actions.

Pour faciliter votre migration, nous proposons des guides pour vous aider à migrer de Rules vers Actions et à migrer de Hooks vers Actions. Nous avons également une page dédiée, Move to Actions, qui présente des comparaisons de fonctionnalités, une démonstration d’Actions et d’autres ressources pour vous accompagner dans votre parcours de migration.

Pour en savoir plus sur la dépréciation de Rules et Hooks, consultez notre billet de blogue : Preparing for Rules and Hooks End of Life.

Au point d’extensibilité Client Credentials Exchange, les Hooks vous permettent d’exécuter des actions personnalisées lorsqu’un Jeton d’accès est émis par le point de terminaison POST /oauth/token de l’API d’authentification au moyen du flux d’identifiants du client. Par exemple, vous pouvez empêcher l’émission du jeton, ajouter des revendications personnalisées au jeton d’accès ou modifier ses scopes. Pour en savoir plus, consultez Flux d’identifiants du client.

Les Hooks à ce point d’extensibilité sont bloquants (synchrones), ce qui signifie qu’ils s’exécutent dans le cadre du processus du déclencheur et empêchent le reste du pipeline Auth0 de s’exécuter tant que le Hook n’est pas terminé.

Le triggerId du point d’extensibilité Client Credentials Exchange est credentials-exchange. Pour savoir comment créer des Hooks pour ce point d’extensibilité, consultez Créer des Hooks.

Pour en savoir plus sur les autres points d’extensibilité, consultez Points d’extensibilité.

​

Code initial et paramètres

Lorsque vous créez un Hook exécuté au point d’extensibilité Client Credentials Exchange, l’exemple de code initial ci-dessous peut vous être utile. Les paramètres pouvant être transmis à la fonction Hook et utilisés par celle-ci sont indiqués au début de l’exemple de code.

/**
@param {object} client - informations sur l'application
@param {string} client.name - nom de l'application
@param {string} client.id - ID client
@param {string} client.tenant - nom du locataire Auth0
@param {object} client.metadata - métadonnées de l'application
@param {array|undefined} scope - soit un tableau de chaînes représentant la revendication scope du jeton, soit undefined
@param {string} audience - revendication audience du jeton
@param {object} context - informations de contexte Auth0
@param {object} context.webtask - contexte du Hook (webtask)
@param {function} cb - function (error, accessTokenClaims)
*/

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope; // ne pas supprimer cette ligne

  // Modifier les scopes ou ajouter des revendications supplémentaires
  // access_token['https://example.com/claim'] = 'bar';
  // access_token.scope.push('extra');

  // Refuser le jeton et répondre avec une réponse d'erreur OAuth2
  // if (denyExchange) {
  //   // Pour retourner un HTTP 400 avec { "error": "invalid_scope", "error_description": "Not authorized for this scope." }
  //   return cb(new InvalidScopeError('Not authorized for this scope.'));
  //
  //   // Pour retourner un HTTP 400 avec { "error": "invalid_request", "error_description": "Not a valid request." }
  //   return cb(new InvalidRequestError('Not a valid request.'));
  //
  //   // Pour retourner un HTTP 500 avec { "error": "server_error", "error_description": "A server error occurred." }
  //   return cb(new ServerError('A server error occurred.'));
  // }

  cb(null, access_token);
};

Veuillez noter :

• La fonction de rappel (cb) à la fin de l’exemple de code signale la fin de l’exécution et doit être incluse.

• La ligne access_token.scope = scope garantit que tous les scopes accordés seront présents dans le jeton d’accès. Si vous la supprimez, tous les scopes seront réinitialisés et le jeton ne comprendra que les scopes ajoutés par le script.

​

Réponse par défaut

Lorsque vous exécutez un Hook au niveau du point d’extensibilité Client Credentials Exchange, l’objet de réponse par défaut est :

{
  "scope": "array of strings"
}

​

Réponse du code initial

Une fois que vous avez personnalisé le code initial avec vos scopes et vos revendications supplémentaires, vous pouvez tester le Hook à l’aide de l’outil d’exécution intégré à l’éditeur de Hook. Cet outil simule un appel au Hook avec le même corps et la même réponse que ceux que vous obtiendriez lors d’un Client Credentials Exchange.

L’exécution du code à l’aide de cet outil nécessite d’enregistrer les modifications, ce qui signifie que le code d’origine sera écrasé.

Lorsque vous exécutez un Hook basé sur le code initial, l’objet de réponse est :

{
  "audience": "https://my-tenant.auth0.com/api/v2/",
  "client": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "client-name",
    "tenant": "my-tenant",
    "metadata": {
      "plan": "full"
    }
  },
  "scope": [
    "read:connections"
  ]
}

​

Exemple de script : Ajouter un scope supplémentaire au jeton d’accès

Dans cet exemple, nous utilisons un Hook pour ajouter un scope supplémentaire aux scopes déjà présents dans le jeton d’accès.

module.exports = function(client, scope, audience, context, cb) {
    // Scopes à ajouter
    var access_token = {};

    // Obtenir le scope actuellement présent sur le jeton d'accès
    // et l'ajouter à l'objet avec lequel on travaille
    // Ne pas supprimer cette ligne !
    access_token.scope = scope;

    // Ajouter le scope `read:resource`
    access_token.scope.push('read:resource');

    // Rappel pour indiquer la fin de l'opération et retourner le nouveau
    // tableau de scopes
    cb(null, access_token);
};

Pour en savoir plus, consultez Scopes.

​

Réponse

Lorsque ce Hook est exécuté, l’objet de réponse est :

{
  "scope": [
    "read:connections",
    "read:resource"
  ]
}

​

Exemple de script : ajouter une revendication au jeton d’accès

Dans cet exemple, nous ajoutons une revendication personnalisée dotée d’un espace de noms ainsi que sa valeur au jeton d’accès. Pour en savoir plus, consultez Create Namespaced Custom Claims.

Vous pouvez ajouter les éléments suivants comme revendications au jeton émis :

• la propriété scope de l’objet de réponse
• toute propriété dont le nom comporte un espace de noms

Le point d’extensibilité ignore toutes les autres propriétés de l’objet de réponse.

Pour accéder à un Hook Secret configuré à partir d’un hook, utilisez context.webtask.secrets.SECRET_NAME.

module.exports = function(client, scope, audience, context, cb) {
    // Revendications à ajouter
    var access_token = {};

    // Nouvelle revendication à ajouter au jeton
    access_token['https://example.com/foo'] = 'bar';

    // Callback pour indiquer la fin de l'opération et retourner la nouvelle revendication
    cb(null, access_token);
  };

​

Réponse

Lorsque ce Hook est exécuté, l’objet de réponse est :

{
  "https://example.com/foo": "bar"
}

​

Exemple de script : lever une erreur ou refuser un jeton d’accès

Dans cet exemple, nous utilisons des objets Error personnalisés pour générer des réponses d’erreur OAuth2. (Pour en savoir plus, consultez OAuth2 RFC - Section 5.2 in the IETF Datatracker.)

Si une simple erreur JavaScript est renvoyée dans la fonction de rappel, comme :

module.exports = function(client, scope, audience, context, cb) {
    // Rappel pour indiquer la fin de l'exécution et retourner une nouvelle revendication
    cb(new Error("Unknown error occurred.");
  };

Ensuite, lorsque vous demanderez un octroi client_credentials au point de terminaison /oauth/token, Auth0 renverra :

HTTP 500
{ "error": "server_error", "error_description": "Unknown error occurred." }

Toutefois, si vous souhaitez un contrôle accru sur la réponse d’erreur OAuth2, vous pouvez plutôt utiliser trois objets Error personnalisés.

​

InvalidScopeError

module.exports = function(client, scope, audience, context, cb) {
    const invalidScope = ...; // déterminer si le scope est valide

    if(invalidScope) {
      cb(new InvalidScopeError("Scope is not permitted."));
    }
  };

Ensuite, lorsque vous demandez un octroi client_credentials au point de terminaison /oauth/token, Auth0 répond :

HTTP 400
{ "error": "invalid_scope", "error_description": "Scope is not permitted." }

​

InvalidRequestError

module.exports = function(client, scope, audience, context, cb) {
    const invalidRequest = ...; // déterminer si la requête est valide

    if(invalidRequest) {
      cb(new InvalidRequestError("Bad request."));
    }
  };

Ensuite, lorsque vous demandez un octroi client_credentials au point de terminaison /oauth/token, Auth0 renvoie :

HTTP 400
{ "error": "invalid_request", "error_description": "Bad request." }

​

ServerError

module.exports = function(client, scope, audience, context, cb) {
    callOtherService(function(err, response) {
      if(err) {
        return cb(new ServerError("Error calling remote system: " + err.message));
      }
    });
  };

Ensuite, lorsque vous demandez un octroi client_credentials au point de terminaison /oauth/token, Auth0 répond :

HTTP 400
{ "error": "server_error", "error_description": "Error calling remote system: ..." }

Pour le moment, le comportement de la classe JavaScript intégrée Error et de ServerError est identique, mais la classe ServerError vous permet de préciser explicitement l’erreur OAuth2 qui sera renvoyée.

​

En savoir plus