Client Credentials Exchange

Découvrez comment 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 est fixée au 18 novembre 2026, et ils ne sont plus offerts aux nouveaux tenants créés à compter du 16 octobre 2023. Les tenants existants avec 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 enrichies, à de la documentation intégrée et à des packages npm publics, et vous pouvez connecter des intégrations externes qui améliorent votre expérience globale en matière d’extensibilité. Pour en savoir plus sur ce qu’offre Actions, consultez Understand How Auth0 Actions Work.

Pour vous aider dans votre migration, nous proposons des guides pour vous aider à passer de Rules à Actions et à migrer de Hooks à Actions. Nous avons aussi une page dédiée, Move to Actions, qui présente des comparaisons de fonctionnalités, une démo d’Actions et d’autres ressources pour vous accompagner dans votre 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, Hooks vous permet d’exécuter des actions personnalisées lorsqu’un jeton d’accès est émis par l’endpoint POST /oauth/token de l’Authentication API à l’aide du Client Credentials Flow. Par exemple, vous pouvez empêcher l’émission du token, ajouter des claims personnalisées au jeton d’accès ou modifier ses scopes. Pour en savoir plus, consultez Client Credentials Flow.

Les Hooks à ce point d’extensibilité sont bloquants (synchrones), ce qui signifie qu’ils s’exécutent dans le cadre du processus du trigger 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 Create Hooks.

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

​

Code de départ et paramètres

Lorsque vous créez un Hook exécuté au point d’extensibilité Client Credentials Exchange, le code de départ 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 le client
@param {string} client.name - nom du client
@param {string} client.id - ID du client
@param {string} client.tenant - nom du tenant Auth0
@param {object} client.metadata - métadonnées du client
@param {array|undefined} scope - soit un tableau de chaînes représentant le claim de scope du token, soit undefined
@param {string} audience - claim d'audience du token
@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 claims supplémentaires
  // access_token['https://example.com/claim'] = 'bar';
  // access_token.scope.push('extra');

  // Rejeter le token 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 du traitement 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 que vous ajoutez avec le script.

​

Réponse par défaut

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

{
  "scope": "array of strings"
}

​

Réponse du code de départ

Une fois le code de départ personnalisé avec vos scopes et des claims supplémentaires, vous pouvez tester le Hook à l’aide de l’outil d’exécution intégré à l’éditeur de Hook. Cet outil simule une requête au Hook avec le même corps et la même réponse que ceux obtenus lors d’un Client Credentials Exchange.

L’exécution du code avec cet outil nécessite d’enregistrer, ce qui signifie que le code d’origine sera écrasé.

Lorsque vous exécutez un Hook basé sur le code de départ, 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 à ceux 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 l'access token
    // 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');

    // Fonction de rappel pour indiquer la fin de l'exécution et retourner le nouvel
    // array de scopes
    cb(null, access_token);
};

Pour en savoir plus, consultez Scopes.

​

Réponse

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

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

​

Exemple de script : Ajouter un claim au jeton d’accès

Dans cet exemple, nous ajoutons un claim personnalisé avec espace de noms et sa valeur au jeton d’accès. Pour en savoir plus, consultez Create Namespaced Custom Claims.

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

• La propriété scope de l’objet de réponse
• Toute propriété dont le nom contient 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é depuis un hook, utilisez context.webtask.secrets.SECRET_NAME.

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

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

    // Fonction de rappel pour indiquer la fin de l'opération et retourner le nouveau claim
    cb(null, access_token);
  };

​

Réponse

Lorsque nous exécutons ce Hook, l’objet de réponse renvoyé est :

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

​

Exemple de script : générer une erreur ou rejeter 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 de l’IETF Datatracker.)

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

module.exports = function(client, scope, audience, context, cb) {
    // Fonction de rappel pour indiquer la fin de l'exécution et retourner un nouveau claim
    cb(new Error("Unknown error occurred.");
  };

Ensuite, lorsque vous envoyez une demande d’octroi client_credentials au point de terminaison /oauth/token, Auth0 renverra :

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

Cependant, si vous voulez exercer 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 envoyez une requête d’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 répond :

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 faites une demande d’octroi client_credentials au point de terminaison /oauth/token, Auth0 répond :

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

À l’heure actuelle, 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