Aller au contenu principal

Interagir avec Management API

Qu'est-ce que Logto Management API ?​

Le Logto Management API est un ensemble complet d'API qui donne aux développeurs un contrôle total sur leur implémentation pour répondre à leurs besoins en matière de produit et de pile technologique. Il est pré-construit, répertorié dans la liste des ressources API dans la Logto Console, et ne peut pas être supprimé ou modifié.

Son identifiant suit le modèle https://[tenant-id].logto.app/api

Ressource Logto Management API Détails Logto Management API

Avec le Logto Management API, vous pouvez accéder aux services backend robustes de Logto, qui sont hautement évolutifs et peuvent être utilisés dans une multitude de scénarios. Il va au-delà de ce qui est possible avec les capacités low-code de l'Admin Console.

Certaines API fréquemment utilisées sont listées ci-dessous :

  • Utilisateur
  • Application
  • Journaux
  • Rôles
  • Ressources
  • Connecteurs
  • Organisations

Pour en savoir plus sur les API disponibles, veuillez visiter https://openapi.logto.io/.

Comment accéder à Logto Management API​

Créer une application M2M​

remarque

Si vous n'êtes pas familier avec le flux d'authentification M2M (Machine-to-Machine), nous vous recommandons de lire Comprendre le flux d'authentification d'abord pour comprendre les concepts de base.

Allez sur Console > Applications, sélectionnez le type d'application M2M et commencez le processus de création.

Pendant le processus de création de l'application M2M, vous serez dirigé vers une page où vous pouvez attribuer des Rôles M2M à vos applications :

Assign M2M roles modal

Ou vous pouvez également attribuer ces rôles sur la page de détails de l'application M2M lorsque vous avez déjà créé une application M2M :

Assign M2M roles page

Dans le module d'attribution de rôle, vous pouvez voir que tous les rôles M2M sont inclus, et les rôles indiqués par une icône Logto signifient que ces rôles incluent des Permissions Logto Management API.

Attribuez maintenant des rôles M2M incluant des Permissions Logto Management API pour votre application M2M.

Récupérer un jeton d’accès​

Notions de base sur la requête de jeton d’accès​

L'application M2M effectue une requête POST vers le point de terminaison de jeton pour récupérer un jeton d’accès (Access token) en ajoutant les paramètres suivants en utilisant le format application/x-www-form-urlencoded dans le corps de l'entité de la requête HTTP :

  • grant_type : Doit être défini sur client_credentials
  • resource : La ressource à laquelle vous souhaitez accéder
  • scope : La portée de la requête d’accès

Vous devez également inclure les informations d'identification de votre application M2M dans l'en-tête de la requête pour que le point de terminaison de jeton puisse authentifier votre application M2M.

Cela est réalisé en incluant les informations d'identification de l'application dans le formulaire d' Authentification (Basic authentication) dans l'en-tête de la requête Authorization, où le nom d'utilisateur est l'ID de l'application et le mot de passe est le secret de l'application.

Vous pouvez trouver l'ID de l'application et le secret de l'application sur la page des détails de votre application M2M :

ID de l'application et secret de l'application

Récupérer un jeton d’accès pour Logto Management API​

Logto fournit une ressource intégrée "Logto Management API", c'est une ressource en lecture seule avec la permission all pour accéder à Logto Management API, vous pouvez la voir dans votre liste de ressources API. L'indicateur de ressource API suit le modèle https://{your-tenant-id}.logto.app/api , et cela sera votre valeur de ressource utilisée dans le corps de la requête de jeton d’accès.

Détails de Logto Management API

Avant d'accéder à Logto Management API, assurez-vous que votre application M2M a été assignée avec des rôles M2M qui incluent la permission all de cette ressource intégrée "Logto Management API".

info

Logto fournit également un rôle M2M préconfiguré "Logto Management API access" pour les nouveaux locataires créés, auquel la permission all de la ressource Logto Management API a déjà été assignée. Vous pouvez l'utiliser directement sans configurer manuellement les permissions. Ce rôle préconfiguré peut également être modifié et supprimé selon les besoins.

Maintenant, composez tout ce que nous avons et envoyez la requête :

const logtoEndpoint = 'https://your.logto.endpoint'; // Remplacez par votre point de terminaison Logto
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
attention

Pour les utilisateurs de Logto Cloud : lorsque vous interagissez avec Logto Management API, vous ne pouvez pas utiliser de domaine personnalisé, utilisez le point de terminaison Logto par défaut https://{your_tenant_id}.logto.app/oidc/token pour obtenir des jetons d’accès.

Réponse du jeton d’accès​

Un corps de réponse d'accès réussi serait comme :

{
  "access_token": "eyJhbG...2g", // Utilisez ce jeton pour accéder à Logto Management API
  "expires_in": 3600, // Expiration du jeton en secondes
  "token_type": "Bearer", // Type d'authentification pour votre requête lors de l'utilisation du jeton d’accès
  "scope": "all" // portée `all` pour Logto Management API
}
remarque

Logto ne prend pas actuellement en charge l'application M2M pour représenter un utilisateur. Le sub dans la charge utile du jeton d’accès sera l'ID de l'application.

Accéder à Logto Management API en utilisant le jeton d’accès​

Vous pouvez remarquer que la réponse du jeton a un champ token_type, qui est fixé à Bearer.

Ainsi, vous devez placer le jeton d’accès dans le champ Authorization des en-têtes HTTP avec le format Bearer (Bearer YOUR_TOKEN) lorsque vous interagissez avec votre serveur de ressource API.

Utilisation du jeton d’accès (Jeton d’accès) demandé avec la ressource API de gestion intégrée de Logto https://[your-tenant-id].logto.app/api pour obtenir toutes les applications dans Logto :

const logtoEndpoint = 'https://your.logto.endpoint'; // Remplacez par votre point de terminaison Logto
const accessToken = 'eyJhb...2g'; // Jeton d’accès

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

Scénarios typiques pour l'utilisation de Logto Management API​

Nos développeurs ont implémenté de nombreuses fonctionnalités supplémentaires en utilisant Logto Management API. Nous croyons que notre API est hautement évolutive et peut répondre à un large éventail de vos besoins. Voici quelques exemples de scénarios qui ne sont pas possibles avec la Logto Admin Console mais peuvent être réalisés grâce à Logto Management API.

Implémenter le profil utilisateur par vous-même​

Logto ne fournit actuellement pas de solution d'interface utilisateur pré-construite pour les profils utilisateurs. Nous reconnaissons que les profils utilisateurs sont étroitement liés aux attributs commerciaux et de produit. Pendant que nous travaillons à déterminer la meilleure approche, nous vous suggérons d'utiliser nos API pour créer votre propre solution. Par exemple, vous pouvez utiliser notre API d'interaction, API de profil et API de code de vérification pour développer une solution personnalisée qui répond à vos besoins.

Recherche avancée d'utilisateurs​

La Logto Admin Console prend en charge les fonctions de recherche et de filtrage de base. Pour des options de recherche avancées comme la recherche floue, la correspondance exacte et la sensibilité à la casse, consultez nos tutoriels et guides Recherche avancée d'utilisateurs.

Implémenter la gestion des organisations par vous-même​

Si vous utilisez la fonctionnalité organisations pour construire votre application multi-locataires, vous pourriez avoir besoin de Logto Management API pour des tâches comme les invitations d'organisation et la gestion des membres. Pour votre produit SaaS, où vous avez à la fois des administrateurs et des membres dans le locataire, Logto Management API peut vous aider à créer un portail d'administration personnalisé adapté à vos besoins commerciaux. Consultez ceci pour plus de détails.

Conseils pour l'utilisation de Logto Management API​

Gestion des réponses API paginées​

Certaines des réponses API peuvent inclure de nombreux résultats, les résultats seront paginés. Logto fournit 2 types d'informations de pagination.

Utilisation des en-têtes de lien​

Un en-tête de réponse paginée sera comme :

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

L'en-tête de lien fournit l'URL pour la page précédente, suivante, première et dernière des résultats :

  • L'URL pour la page précédente est suivie de rel="prev".
  • L'URL pour la page suivante est suivie de rel="next".
  • L'URL pour la dernière page est suivie de rel="last".
  • L'URL pour la première page est suivie de rel="first".

Utilisation de l'en-tête total-number​

En plus des en-têtes de lien standard, Logto ajoutera également un en-tête Total-Number :

Total-Number: 216

Cela serait très pratique et utile pour afficher les numéros de page.

Changer le numéro de page et la taille de la page​

Il y a 2 paramètres de requête optionnels :

  • page : indique le numéro de page, commence à 1, la valeur par défaut est 1.
  • page_size : indique le nombre d'éléments par page, la valeur par défaut est 20.

Limite de taux​

remarque

Ceci est uniquement pour Logto Cloud.

Pour assurer la fiabilité et la sécurité de nos services pour tous les utilisateurs, nous employons un pare-feu général qui surveille et gère le trafic vers notre site Web. Bien que nous n'imposions pas de limite de taux stricte, nous recommandons aux utilisateurs de limiter leur activité à environ 200 requêtes toutes les 10 secondes pour éviter de déclencher nos mesures de protection.