Créer un script de revendications personnalisées pour le jeton

Pour ajouter des revendications personnalisées au jeton d’accès (Access token), vous devez fournir un script qui retourne un objet contenant ces revendications. Le script doit être écrit comme une fonction JavaScript qui retourne un objet avec les revendications personnalisées.

1. Accédez à Console > JWT personnalisé.

2. Il existe deux types différents de jetons d’accès pour lesquels vous pouvez personnaliser les revendications du jeton d’accès :

   • Jeton d’accès utilisateur : Le jeton d’accès délivré pour les utilisateurs finaux. Par exemple, pour les applications Web ou mobiles.
   • Jeton d’accès machine à machine : Le jeton d’accès délivré pour les services ou applications. Par exemple, pour les applications machine à machine.

   Différents types de jetons d’accès peuvent avoir des contextes de charge utile différents. Vous pouvez personnaliser les revendications du jeton pour chaque type de jeton d’accès séparément.

   Choisissez le type de jeton d’accès que vous souhaitez personnaliser, puis cliquez sur le bouton Ajouter des revendications personnalisées pour créer un nouveau script.

remarque:

La fonctionnalité de revendications personnalisées pour le jeton est uniquement disponible pour :

• les utilisateurs de Logto OSS
• les locataires Logto Cloud avec un environnement de développement
• les locataires Logto Cloud payants avec un environnement de production (y compris les locataires Pro et Enterprise)

Implémenter la fonction getCustomJwtClaims()

Dans la page de détails JWT personnalisé, vous trouverez l’éditeur de script pour écrire votre script de revendications personnalisées pour le jeton. Le script doit être une fonction JavaScript qui retourne un objet de revendications personnalisées.

Étape 1 : Modifier le script

Utilisez l’éditeur de code à gauche pour modifier le script. Un getCustomJwtClaims par défaut avec une valeur de retour d’objet vide est fourni pour commencer. Vous pouvez modifier la fonction pour retourner un objet contenant vos propres revendications personnalisées.

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

Cet éditeur utilise le serveur de langage JavaScript pour fournir la coloration syntaxique de base, la complétion de code et la vérification des erreurs. Les paramètres d’entrée sont bien typés et documentés au format jsDoc. Vous pouvez utiliser l’IntelliSense de l’éditeur pour accéder correctement aux propriétés de l’objet d’entrée. Vous trouverez les définitions détaillées des paramètres sur le côté droit de la page.

remarque:

Cette fonction sera exportée en tant que module. Assurez-vous de conserver le nom de la fonction getCustomJwtClaims afin que le module puisse l’exporter correctement.

Étape 2 : Paramètres d’entrée

La fonction getCustomJwtClaims prend un objet comme paramètre d’entrée. L’objet d’entrée contient les propriétés suivantes :

token

L’objet de charge utile du jeton. Cet objet contient les revendications originales du jeton et les métadonnées auxquelles vous pouvez accéder dans le script.

Vous trouverez la définition de type détaillée de l’objet de charge utile du jeton et de l’objet de données utilisateur sur le côté droit de la page. L’IntelliSense de l’éditeur vous aidera également à accéder correctement à ces propriétés de l’objet d’entrée.

• Objet de données du jeton d’accès utilisateur

  Propriété	Description	Type
  jti	L’identifiant unique du JWT	string
  aud	L’audience du jeton	string
  scope	Les portées du jeton	string
  clientId	L’identifiant client du jeton	string
  accountId	L’identifiant utilisateur du jeton	string
  expiresWithSession	Si le jeton expirera avec la session	boolean
  grantId	L’identifiant de la subvention d’authentification actuelle du jeton	string
  gty	Le type de subvention du jeton	string
  kind	Le type de jeton	AccessToken

• Objet de données du jeton d’accès machine à machine

  Propriété	Description	Type
  jti	L’identifiant unique du JWT	string
  aud	L’audience du jeton	string
  scope	Les portées du jeton	string
  clientId	L’identifiant client du jeton	string
  kind	Le type de jeton	ClientCredentials

context (Disponible uniquement pour le jeton d’accès utilisateur)

L’objet context contient les données utilisateur et les données de subvention pertinentes pour le processus d’autorisation (Authorization) en cours.

• Objet de données utilisateur Pour le jeton d’accès utilisateur, Logto fournit un contexte de données utilisateur supplémentaire auquel vous pouvez accéder. L’objet de données utilisateur contient toutes les données de profil utilisateur et les données d’appartenance à l’organisation (Organization) dont vous pourriez avoir besoin pour configurer les revendications personnalisées. Veuillez consulter Utilisateurs et Organisations pour plus de détails.

• Objet de données de subvention Pour le jeton d’accès utilisateur accordé par échange de jeton d’usurpation, Logto fournit un contexte de données de subvention supplémentaire auquel vous pouvez accéder. L’objet de données de subvention contient le contexte personnalisé du jeton sujet. Veuillez consulter Usurpation d’identité utilisateur pour plus de détails.

• Objet de données d’interaction utilisateur Pour un jeton d’accès utilisateur donné, il peut y avoir des cas où vous devez accéder aux détails d’interaction de l’utilisateur pour la session d’autorisation (Authorization) en cours. Par exemple, vous pourriez avoir besoin de récupérer l’identité SSO d’entreprise de l’utilisateur utilisée pour la connexion. Cet objet de données d’interaction utilisateur contient les données d’interaction les plus récentes soumises par l’utilisateur, y compris :

  Propriété	Description	Type
  interactionEvent	L’événement d’interaction de l’utilisateur actuel	SignIn ou Register
  userId	L’identifiant utilisateur de l’interaction utilisateur actuelle	string
  verificationRecords	Une liste d’enregistrements de vérification soumis par l’utilisateur pour s’identifier et se vérifier lors des interactions.	VerificationRecord[]

  Type d’enregistrement de vérification :

  // VerificationType.Password
  {
    id: string;
    type: 'Password';
    identifier: {
      type: 'username' | 'email' | 'phone' | 'userId';
      value: string;
    }
    verified: boolean;
  }

  // VerificationType.EmailVerificationCode
  {
    id: string;
    templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
    verified: boolean;
    type: 'EmailVerificationCode';
    identifier: {
      type: 'email';
      value: string;
    }
  }

  // VerificationType.PhoneVerificationCode
  {
    id: string;
    templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
    verified: boolean;
    type: 'PhoneVerificationCode';
    identifier: {
      type: 'phone';
      value: string;
    }
  }

  // VerificationType.Social
  {
    id: string;
    type: 'Social';
    connectorId: string;
    socialUserInfo?: {
      id: string;
      email?: string | undefined;
      phone?: string | undefined;
      name?: string | undefined;
      avatar?: string | undefined;
      rawData?: Record<string, unknown> | undefined;
    } | undefined;
  }

  // VerificationType.EnterpriseSso
  {
    id: string;
    type: 'EnterpriseSso';
    connectorId: string;
    enterpriseUserInfo?: {
      id: string;
      email?: string | undefined;
      phone?: string | undefined;
      name?: string | undefined;
      avatar?: string | undefined;
      [key: string]?: unknown;
    } | undefined;
    issuer?: string | undefined;
  }

  // VerificationType.Totp (MFA)
  {
    id: string;
    type: 'Totp';
    userId: string;
    verified: boolean;
  }

  // VerificationType.WebAuthn (MFA)
  {
    id: string;
    type: 'WebAuthn';
    userId: string;
    verified: boolean;
  }

  // VerificationType.BackupCode (MFA)
  {
    id: string;
    type: "BackupCode";
    userId: string;
    code?: string | undefined;
  }

  // VerificationType.OneTimeToken
  {
    id: string;
    type: "OneTimeToken";
    verified: boolean;
    identifier: {
      type: "email";
      value: string;
    };
    oneTimeTokenContext?: {
      jitOrganizationIds?: string[] | undefined;
    } | undefined;
  }
  remarque:

  Il peut y avoir plusieurs enregistrements de vérification dans l’objet de données d’interaction utilisateur, en particulier lorsque l’utilisateur a effectué plusieurs processus de connexion ou d’inscription.

  Par exemple, l’utilisateur s’est connecté en utilisant un enregistrement de vérification Social, puis a lié une nouvelle adresse e-mail via un enregistrement de vérification EmailVerificationCode, puis a vérifié le statut MFA avec un enregistrement de vérification Totp. Dans ce cas, vous devrez peut-être gérer tous les enregistrements de vérification en conséquence dans votre script.

  Chaque type d’enregistrement de vérification ne sera présent qu’une seule fois dans l’objet de données d’interaction utilisateur.

environmentVariables

Utilisez la section Définir les variables d’environnement à droite pour configurer les variables d’environnement pour votre script. Vous pouvez utiliser ces variables pour stocker des informations sensibles ou des données de configuration que vous ne souhaitez pas coder en dur dans le script. Par exemple, des clés API, des secrets ou des URLs.

Toutes les variables d’environnement que vous définissez ici seront disponibles dans le script. Utilisez l’objet environmentVariables dans le paramètre d’entrée pour accéder à ces variables.

api

L’objet api fournit un ensemble de fonctions utilitaires que vous pouvez utiliser dans votre script pour un contrôle d’accès supplémentaire lors du processus de délivrance du jeton. L’objet api contient les fonctions suivantes :

api.denyAccess(message?: string): void

La fonction api.denyAccess() vous permet de refuser le processus de délivrance du jeton avec un message personnalisé. Vous pouvez utiliser cette fonction pour appliquer une validation d’accès supplémentaire lors du processus de délivrance du jeton.

Étape 3 : Récupérer des données externes

Vous pouvez utiliser la fonction intégrée fetch de node pour récupérer des données externes dans votre script. La fonction fetch est basée sur les promesses et vous permet d’effectuer des requêtes HTTP vers des API externes.

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

remarque:

Attention, toute récupération de données externes peut introduire une latence dans le processus de délivrance du jeton. Assurez-vous que l’API externe est fiable et suffisamment rapide pour répondre à vos exigences.

De plus :

• Gérez correctement les erreurs et les délais d’attente dans votre script pour éviter que le processus de délivrance du jeton ne soit bloqué.
• Utilisez des en-têtes d’autorisation appropriés pour protéger votre API externe contre les accès non autorisés.

Étape 4 : Tester le script

Assurez-vous de tester votre script avant de l’enregistrer. Cliquez sur l’onglet Contexte de test à droite de la page pour modifier la charge utile du jeton simulée et le contexte de données utilisateur pour les tests.

Cliquez sur Exécuter le test dans le coin supérieur droit de l’éditeur pour exécuter le script avec les données simulées. Le résultat du script s’affichera dans le tiroir Résultat du test.

remarque:

Le résultat du test correspond à la sortie de la fonction getCustomJwtClaims avec les données simulées que vous avez définies ("revendications supplémentaires du jeton" obtenues après avoir terminé l’étape 3 dans le diagramme de séquence). La charge utile réelle du jeton et le contexte de données utilisateur seront différents lorsque le script sera exécuté lors du processus de délivrance du jeton.

Cliquez sur le bouton Créer pour enregistrer le script. Le script de revendications personnalisées pour le jeton sera enregistré et appliqué au processus de délivrance du jeton d’accès (Access token).