Aller au contenu principal

Protéger les ressources API au niveau de l’organisation

Combinez les ressources API avec le modèle d’organisation pour restreindre l’accès aux API et aux données au sein de chaque organisation, garantissant ainsi une isolation au niveau du locataire dans votre SaaS.

Que sont les ressources API au niveau de l’organisation ?​

Les ressources API au niveau de l’organisation sont des points de terminaison ou des services dans votre application qui sont limités à une organisation spécifique. Ces API appliquent l’autorisation et l’accès en fonction du contexte organisationnel, garantissant que les utilisateurs ou clients n’accèdent qu’aux données et actions pertinentes pour leur organisation.

Exemples d’utilisation

  • API pour gérer les membres, rôles ou paramètres d’une organisation (par exemple, /organizations/{organizationId}/members)
  • Tableaux de bord, analyses ou rapports limités à l’organisation
  • Points de terminaison de facturation, d’abonnement ou d’audit liés à une organisation
  • Toute API où les actions et les données sont isolées par locataire

Logto vous permet de sécuriser ces API d’organisation en utilisant OAuth 2.1 et le contrôle d’accès basé sur les rôles (RBAC), tout en prenant en charge les architectures SaaS multi-locataires.

Ces permissions sont gérées via les rôles d’organisation définis dans le modèle d’organisation. Chaque organisation utilise le même modèle, garantissant un modèle de permission cohérent pour toutes les organisations.

Fonctionnement dans Logto​

  • Les ressources API et les permissions sont enregistrées globalement : Chaque ressource API est définie avec un indicateur de ressource unique (URI) et un ensemble de permissions (portées) dans Logto.
  • Rôles au niveau de l’organisation : Les rôles d’organisation sont définis dans le modèle d’organisation. Les permissions (portées) des ressources API sont attribuées aux rôles d’organisation, qui sont ensuite attribués aux utilisateurs ou clients au sein de chaque organisation.
  • Autorisation contextuelle : Lorsqu’un client demande un jeton d’accès avec à la fois une ressource API et un organization_id, Logto émet un jeton qui inclut à la fois le contexte organisationnel et l’audience API. Les permissions (portées) du jeton sont déterminées par les rôles d’organisation de l’utilisateur pour l’organisation spécifiée.
  • Séparation des ressources globales : Les ressources API peuvent être accessibles avec ou sans contexte organisationnel. Le RBAC d’organisation n’est appliqué que si un organization_id est inclus dans la requête. Pour les API partagées entre tous les utilisateurs, voir Protéger les ressources API globales.
Ressources API au niveau de l’organisation RBAC

Vue d’ensemble de la mise en œuvre​

  1. Enregistrez votre ressource API et définissez ses permissions (portées) dans Logto.
  2. Définissez les rôles d’organisation dans le modèle d’organisation et attribuez les permissions API pertinentes.
  3. Attribuez des rôles aux utilisateurs ou clients au sein de chaque organisation.
  4. Demandez un jeton d’accès pour l’API avec un organization_id pour inclure le contexte organisationnel.
  5. Validez les jetons d’accès dans votre API, en appliquant à la fois le contexte organisationnel et les permissions.

Comment Logto applique le RBAC d’organisation​

  • Si vous demandez un jeton d’accès sans organization_id, seuls les rôles / permissions globaux sont pris en compte.
  • Si vous demandez un jeton d’accès avec un organization_id, Logto évalue les rôles d’organisation de l’utilisateur et leurs permissions associées pour cette organisation.
  • Le JWT résultant contiendra à la fois l’audience API (aud revendication) et le contexte organisationnel (organization_id revendication), avec des portées filtrées selon celles accordées par les rôles d’organisation de l’utilisateur.

Flux d’autorisation : authentifier et sécuriser les API avec le contexte organisationnel​

Le flux suivant montre comment un client (web, mobile ou backend) obtient et utilise des jetons d’organisation pour accéder aux ressources API au niveau de l’organisation.

Veuillez noter que ce flux ne détaille pas tous les paramètres ou en-têtes requis, mais se concentre sur les étapes clés. Continuez à lire pour voir comment le flux fonctionne en pratique.

Authentification utilisateur = navigateur / application. M2M = service backend ou script utilisant les identifiants client + contexte organisationnel.

Étapes de mise en œuvre​

Enregistrez votre ressource API​

  1. Allez dans Console → Ressources API.
  2. Créez une nouvelle ressource API (par exemple, https://api.yourapp.com/org) et définissez ses permissions (portées).

Pour les étapes complètes de configuration, voir Définir des ressources API avec des permissions.

Configurez les rôles d’organisation​

  1. Allez dans Console → Modèle d’organisation → Rôles d’organisation.
  2. Créez des rôles d’organisation (par exemple, admin, member) et attribuez des permissions API à chaque rôle.
  3. Attribuez des rôles aux utilisateurs ou clients au sein de chaque organisation. S’ils ne sont pas encore membres, invitez-les ou ajoutez-les d’abord.

Pour les étapes complètes de configuration, voir Utiliser les rôles d’organisation.

Obtenez des jetons d’organisation pour les ressources API​

Votre client / application doit demander un jeton avec à la fois resource et organization_id pour accéder aux API au niveau de l’organisation. Logto émet des jetons d’organisation sous forme de JSON Web Tokens (JWTs). Vous pouvez les obtenir en utilisant soit le flux de jeton de rafraîchissement, soit le flux client credentials.

Flux de jeton de rafraîchissement​

Presque tous les SDK officiels Logto prennent en charge l’obtention de jetons d’organisation via le flux de jeton de rafraîchissement par défaut. Une bibliothèque cliente OAuth 2.0 / OIDC standard peut également être utilisée pour implémenter ce flux.

Lors de l’initialisation du SDK Logto, ajoutez urn:logto:scope:organizations et les permissions d’organisation souhaitées (portées) au paramètre scopes.

Certains SDK Logto disposent d’une portée prédéfinie pour les organisations, telle que UserScope.Organizations dans les SDK JavaScript.

remarque:

Inspectez la revendication organizations dans le jeton d’identifiant (ID token) pour obtenir une liste des identifiants d’organisation auxquels l’utilisateur appartient. Cette revendication répertorie toutes les organisations dont l’utilisateur est membre, ce qui facilite l’énumération ou le changement d’organisation dans votre application.

Lors de l’appel de getAccessToken(), spécifiez à la fois la ressource API (resource) et l’ID de l’organisation (organizationId) pour obtenir un jeton d’organisation.

Pour plus de détails sur chaque SDK, voir Démarrages rapides.

Flux client credentials​

Pour les scénarios machine à machine (M2M), vous pouvez utiliser le flux client credentials pour obtenir un jeton d’accès avec des permissions de ressource API au niveau de l’organisation. En effectuant une requête POST vers le point de terminaison /oidc/token de Logto avec les paramètres d’organisation, vous pouvez demander un jeton d’organisation en utilisant votre client ID et secret.

Voici les paramètres clés à inclure dans la requête :

  • resource : L’identifiant de la ressource API (par exemple, https://api.yourapp.com/org).
  • organization_id : L’ID de l’organisation pour laquelle vous souhaitez le jeton.
  • scope : Les permissions de ressource API au niveau de l’organisation que vous souhaitez demander (par exemple, invite:member, manage:billing).

Voici un exemple non normatif de requête de jeton utilisant le type de flux client credentials :

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com/org
&organization_id=your-organization-id
&scope=invite:member manage:billing

Validez les jetons d’organisation​

Les jetons d’organisation émis par Logto (JWTs) contiennent des revendications que votre API peut utiliser pour appliquer le contrôle d’accès au niveau de l’organisation.

Lorsque votre application reçoit un jeton d’organisation, vous devez :

  • Vérifier la signature du jeton (en utilisant les JWKs de Logto).
  • Confirmer que le jeton n’est pas expiré (exp revendication).
  • Vérifier que le iss (émetteur) correspond à votre point de terminaison Logto.
  • S’assurer que le aud (audience) correspond à l’identifiant de la ressource API que vous avez enregistrée (par exemple, https://api.yourapp.com/org).
  • Valider la revendication organization_id pour s’assurer que le jeton est limité à la bonne organisation.
  • Séparer la revendication scope (séparée par des espaces) et vérifier les permissions requises.
  • Si le chemin de votre API inclut l’ID de l’organisation (par exemple, /organizations/{organizationId}/members), assurez-vous que la revendication organization_id correspond au paramètre du chemin.

Pour des guides étape par étape et spécifiques à chaque langage, voir Comment valider les jetons d’accès.

Bonnes pratiques et conseils de sécurité​

  • Validez toujours le contexte organisationnel : Ne vous fiez pas uniquement au jeton ; vérifiez la revendication organization_id pour chaque appel d’API limité à l’organisation.
  • Utilisez les restrictions d’audience : Vérifiez toujours la revendication aud pour vous assurer que le jeton est destiné à la bonne organisation.
  • Gardez les permissions orientées métier : Utilisez des noms clairs correspondant à de vraies actions ; n’accordez que ce qui est nécessaire pour chaque rôle d’organisation.
  • Séparez les permissions API et non-API lorsque c’est possible (mais les deux peuvent être dans un même rôle).
  • Gardez la durée de vie des jetons courte : Réduit le risque en cas de fuite d’un jeton.
  • Révisez régulièrement votre modèle d’organisation : Mettez à jour les rôles et permissions au fur et à mesure de l’évolution de votre produit.

FAQ​

Que se passe-t-il si je n’inclus pas organization_id dans ma requête de jeton ?​

Seuls les rôles / permissions globaux seront évalués. Le RBAC d’organisation ne sera pas appliqué.

Puis-je mélanger des permissions d’organisation et non-organisation dans un même rôle ?​

Non, les permissions d’organisation (y compris les permissions API au niveau de l’organisation) sont définies par le modèle d’organisation et ne peuvent pas être mélangées avec des permissions API globales. Cependant, vous pouvez créer des rôles qui incluent à la fois des permissions d’organisation et des permissions API au niveau de l’organisation.

Pour aller plus loin​

Comment valider les jetons d’accès Personnalisation des revendications de jeton

Cas d’usage : Construire une application SaaS multi-locataire

 RFC 8707 : Indicateurs de ressource