Configurez votre service d’application avec l’API de gestion Logto

Logto propose une puissante API de gestion (Management API) qui vous permet de créer et de personnaliser votre propre parcours d’organisation au sein de votre application. Comprendre son fonctionnement est essentiel pour concevoir votre configuration personnalisée. Voici les étapes de base et un aperçu pour intégrer l’API de gestion afin de mettre en œuvre votre expérience d’organisation.

Si vous connaissez déjà les bases, vous pouvez passer directement au tutoriel. Une fois que vous êtes à l’aise avec la configuration, vous pouvez explorer des API supplémentaires pour adapter le reste des parcours à vos besoins métier.

Établir une connexion machine à machine

Logto utilise l’authentification machine à machine (M2M) (Machine-to-machine authentication) pour connecter en toute sécurité votre service backend au point de terminaison de l’API de gestion Logto. Votre service backend peut alors utiliser l’API de gestion pour gérer des tâches liées à l’organisation telles que la création d’organisations, l’ajout ou la suppression de membres, et plus encore.

Cela implique :

1. Créer une application Machine-to-Machine (M2M) dans la Console Logto.

2. Obtenir un jeton d’accès M2M depuis Logto. En savoir plus.
3. Appeler les API de gestion Logto depuis votre service backend. Par exemple, lister toutes les organisations :

curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

Protégez votre serveur d’application

Puisque les utilisateurs finaux peuvent effectuer certaines actions sur l’organisation par eux-mêmes, il est important d’ajouter une couche d’autorisation (Authorization) entre l’utilisateur final et votre serveur d’application.
Vous pouvez appliquer cette couche globalement ou au niveau de l’organisation, selon les points de terminaison de l’API de gestion Logto que vous utilisez et la structure de l’API de votre produit. Le serveur doit intercepter chaque requête, valider le jeton d’organisation de l’utilisateur et les portées requises, puis seulement utiliser un identifiant M2M détenu côté serveur pour invoquer l’API de gestion.

Lorsqu’un utilisateur présente un jeton d’organisation pour demander une action (par exemple, créer une organisation), le serveur valide d’abord les portées dans le jeton. Si le jeton inclut la portée nécessaire, telle que org:create, autorisez la requête et appelez l’API de gestion Logto via le flux M2M pour créer l’organisation.

Si le jeton ne contient pas les portées requises, retournez une erreur 403 Forbidden et ignorez la logique M2M. Cela garantit que les utilisateurs sans les privilèges appropriés ne peuvent pas créer d’organisations.

Voici des schémas d’autorisation courants.

Utilisation des permissions d’organisation

Tout d’abord, assurez-vous d’avoir défini les permissions et rôles d’organisation dans votre modèle d’organisation dans la section précédente.

Ensuite, assurez-vous que UserScope.Organizations (valeur : urn:logto:organization) est inclus dans la configuration Logto. Prenons l’exemple du SDK React :

// src/App.js
import { UserScope } from '@logto/react';

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // Votre point de terminaison Logto
  appId: '40fmibayagoo00lj26coc', // Votre identifiant d’application
  resources: [
    'https://my.company.com/api', // Identifiant global de la ressource API
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // Demander un jeton d’organisation
  ],
};

Cela garantit que lors de l’appel à getOrganizationToken(organizationId), le SDK client demande un jeton d’organisation contenant les permissions d’organisation attribuées à l’utilisateur. Votre service backend peut alors valider le jeton et autoriser les requêtes suivantes en fonction de ces permissions.

Pour plus de détails sur la protection des permissions d’organisation (hors API), consultez le guide complet.

Utilisation des permissions au niveau de l’API

Cela s’applique lorsque vos ressources API et permissions sont enregistrées globalement, mais que les rôles sont définis au niveau de l’organisation (vous pouvez attribuer des permissions API à des rôles d’organisation dans le modèle d’organisation).

La mise en œuvre est la même que dans la section précédente. Fournissez toujours l’identifiant de l’organisation et appelez getOrganizationToken(organizationId) pour obtenir un jeton d’organisation ; sinon, les permissions d’organisation ne seront pas incluses.

Pour plus de détails sur la protection des permissions API au niveau de l’organisation, consultez le guide complet.

Utilisation du RBAC global

Dans ce cas, vous pouvez utiliser l’API de gestion Logto pour mettre en œuvre un contrôle d’accès au niveau du système.

Dans un environnement multi-locataires, un schéma courant consiste à avoir un superutilisateur ou un rôle de super administrateur. Par exemple, si vous construisez une plateforme SaaS avec Logto, vous pouvez souhaiter qu’un superutilisateur puisse gérer toutes les organisations clientes directement depuis votre propre application, sans avoir à se connecter à la Console Logto.

Ce superutilisateur peut effectuer des actions de niveau supérieur, telles que la création ou la suppression d’organisations en masse, nécessitant des permissions globales dépassant le contexte d’une seule organisation. Pour cela, enregistrez une ressource API dans Logto tout en exploitant l’API de gestion Logto et utilisez le RBAC global pour gérer ces permissions.

Pour plus de détails sur l’intégration et la gestion du contrôle d’accès pour le RBAC, consultez le guide complet.