Créer un script de jeton d’accès personnalisé (Create a custom access token script)

Pour ajouter des revendications personnalisées au jeton d’accès, 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.

Accédez à Console > JWT personnalisé.
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 pour lequel vous souhaitez personnaliser les revendications, puis cliquez sur le bouton Ajouter des revendications personnalisées pour créer un nouveau script.

remarque:

La fonctionnalité de revendications personnalisées dans les jetons n’est disponible que pour :

les utilisateurs de Logto OSS
les locataires Logto Cloud avec environnement de développement
les locataires Logto Cloud payants avec environnement de production (y compris locataires Pro et locataires 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. Le script doit être une fonction JavaScript qui retourne un objet de revendications personnalisées.

Page de détails des revendications personnalisées du jeton

Étape 1 : Modifier le script

Utilisez l’éditeur de code à gauche pour modifier le script. Une fonction getCustomJwtClaims par défaut, retournant un objet vide, est fournie pour commencer. Vous pouvez modifier la fonction pour retourner un objet avec 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 la partie droite 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 exporter la fonction correctement.

Sur les jetons d’accès utilisateur, les revendications de contexte d’authentification acr, amr et auth_time sont réservées par Logto (voir Authentification step-up). Si votre script retourne l’une de ces clés, Logto les ignore et préserve son propre contexte d’authentification dérivé.

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

La fonction getCustomJwtClaims prend un objet comme paramètre d’entrée. Cet objet 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 détaillée du type de l’objet de charge utile du jeton et de l’objet de données utilisateur sur la partie droite 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 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 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 d’organisation Pour les jetons d’accès d’organisation (un jeton d’accès demandé pour une organisation spécifique), Logto fournit l’organisation cible via context.organization, afin que vous puissiez attacher des revendications par organisation — par exemple, faire correspondre l’ID d’organisation Logto à un ID interne stocké dans les données personnalisées de l’organisation. Cet objet de données n’est présent que lorsque le jeton est délivré pour une organisation spécifique, et contient :

Propriété	Description	Type
`id`	L’identifiant unique de l’organisation	`string`
`name`	Le nom de l’organisation	`string`
`description`	La description de l’organisation	`string \| null`
`customData`	Les données personnalisées de l’organisation	`Record<string, unknown>`

Veuillez consulter Organisations pour plus de détails.

Objet de données de subvention Pour un 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 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 actuelle	`string`
`verificationRecords`	Liste des 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 de 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 la 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.

APIs d’exécution

Les scripts de jeton d’accès personnalisés peuvent utiliser ces APIs Web standard à la fois dans Logto Cloud et Logto auto-hébergé :

fetch, Request, Response et Headers
Web Crypto via crypto et crypto.subtle
TextEncoder et TextDecoder
URL et URLSearchParams

Par exemple, vous pouvez calculer des valeurs SHA-256 et HMAC-SHA-256 avec Web Crypto :

const toHex = (buffer) =>
  [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, '0')).join('');

const sha256 = async (input) =>
  toHex(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input)));

const hmacSha256 = async (key, input) => {
  const encoder = new TextEncoder();
  const cryptoKey = await crypto.subtle.importKey(
    'raw',
    encoder.encode(key),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  return toHex(await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(input)));
};

Les scripts ne peuvent pas importer de packages. Évitez les globales et modules spécifiques à Node.js car ils ne sont pas portables entre Logto auto-hébergé et Logto Cloud et ne font pas partie du contrat de script pris en charge.

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

Vous pouvez utiliser la fonction standard fetch pour récupérer des données externes dans votre script. La fonction fetch est basée sur les promesses et vous permet de faire des requêtes HTTP vers des APIs 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 de la 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 est 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 sera enregistré et appliqué au processus de délivrance du jeton d’accès.

Implémenter la fonction getCustomJwtClaims()​

Étape 1 : Modifier le script​

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

token​

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

environmentVariables​

api​

APIs d’exécution​

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

Étape 4 : Tester le script​

Implémenter la fonction `getCustomJwtClaims()`

Étape 1 : Modifier le script

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

token

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

environmentVariables

api

APIs d’exécution

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

Étape 4 : Tester le script