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 rattaché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 spécifiques à 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 permissions 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 l’implémentation​

  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 les 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 : authentification et sécurisation des API avec 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 la lecture pour voir comment ce flux fonctionne en pratique.

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

Étapes d’implémentation​

Enregistrez votre ressource API​

  1. Accédez à 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. Accédez à Console → Modèle d’organisation → Rôles d’organisation.
  2. Créez des rôles d’organisation (par exemple, admin, member) et attribuez les permissions API à chaque rôle.
  3. Attribuez les 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 à 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 l’iss (émetteur) correspond à votre point de terminaison Logto.
  • S’assurer que l’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 rattaché à 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.

Optional: Handle user permission change​

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions​

When a user loses permissions:

  • Newly issued tokens immediately reflect the reduced scopes.
  • Existing JWTs keep the old scopes until they expire.
  • Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions​

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations​

  • Validate scopes in your API on every call.
  • Keep token expiration short.
  • Add optional notifications if you need immediate permission-change propagation.

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 rattaché à une 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 à des actions réelles ; 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