Aller au contenu principal

Protéger les permissions d’organisation (hors API)

Utilisez le modèle d’organisation pour gérer et appliquer les rôles et permissions au niveau de l’organisation dans Logto, en contrôlant l’accès aux fonctionnalités et flux de travail internes à une organisation.

Que sont les permissions d’organisation (hors API) ?​

Les permissions d’organisation (hors API) contrôlent ce que les utilisateurs peuvent faire dans le contexte d’une organisation, mais ne sont pas appliquées au niveau de l’API. Elles régissent plutôt l’accès aux fonctionnalités de l’application, aux éléments d’interface, aux flux de travail ou aux actions métier, plutôt qu’aux API backend.

Cas d’usage courants

  • Inviter ou gérer des membres au sein d’une organisation
  • Attribuer ou modifier des rôles d’organisation
  • Gérer la facturation, les paramètres ou les fonctions administratives d’une organisation
  • Accès à des tableaux de bord, des analyses ou des outils internes sans point d’accès API

Logto vous permet de sécuriser ces permissions 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 une cohérence du modèle de permissions entre toutes les organisations.

Fonctionnement dans Logto​

  • Contrôle d’accès basé sur les rôles au niveau de l’organisation (RBAC) : Les rôles et permissions sont définis dans le modèle d’organisation. Lorsqu’un utilisateur rejoint une organisation, il se voit attribuer un ou plusieurs rôles, lui accordant des permissions spécifiques.
  • Application hors API : Les permissions sont vérifiées et appliquées dans l’interface de votre application, les flux de travail ou la logique backend, pas nécessairement par une passerelle API.
  • Séparation de la protection API : Les permissions d’organisation (hors API) sont distinctes des permissions des ressources API. Vous pouvez combiner les deux pour des scénarios avancés.
Permissions d’organisation RBAC

Vue d’ensemble de l’implémentation​

  1. Définissez les permissions d’organisation dans Logto sous le modèle d’organisation.
  2. Créez des rôles d’organisation qui regroupent les permissions nécessaires pour vos actions spécifiques à l’organisation.
  3. Attribuez les rôles aux utilisateurs ou clients dans chaque organisation.
  4. Obtenez un jeton d’organisation (JWT) pour l’organisation courante en utilisant le jeton de rafraîchissement ou le flux client credentials.
  5. Validez les jetons d’accès dans l’interface ou le backend de votre application pour appliquer les permissions d’organisation.

Flux d’autorisation : authentifier et sécuriser les permissions d’organisation​

Le flux suivant montre comment un client (web, mobile ou backend) obtient et utilise des jetons d’organisation pour l’application des permissions hors API.

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 client credentials + contexte d’organisation.

Étapes d’implémentation​

Enregistrer les permissions d’organisation​

  1. Rendez-vous sur Console → Modèle d’organisation → Permissions d’organisation.
  2. Définissez les permissions d’organisation nécessaires (ex : invite:member, manage:billing, view:analytics).

Pour toutes les étapes de configuration, voir Définir les permissions d’organisation.

Configurer les rôles d’organisation​

  1. Rendez-vous sur Console → Modèle d’organisation → Rôles d’organisation.
  2. Créez des rôles regroupant les permissions d’organisation définies précédemment (ex : admin, member, billing).
  3. Attribuez ces rôles aux utilisateurs ou clients dans chaque organisation.

Pour toutes les étapes de configuration, voir Utiliser les rôles d’organisation.

Obtenir des jetons d’organisation (hors API)​

Votre client/application doit obtenir un jeton d’organisation (hors API) pour accéder aux permissions d’organisation. Logto émet des jetons d’organisation sous forme de JSON Web Tokens (JWTs). Vous pouvez les obtenir via le flux de jeton de rafraîchissement ou 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. Une bibliothèque cliente OAuth 2.0 / OIDC standard peut également être utilisée pour 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.

Utilisez getOrganizationToken ou une méthode similaire (comme getAccessToken avec un ID d’organisation) pour demander un jeton d’organisation pour une organisation spécifique.

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 aux permissions d’organisation. En effectuant une requête POST vers l’endpoint /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 :

  • organization_id : L’ID de l’organisation pour laquelle vous souhaitez le jeton.
  • scope : Les permissions d’organisation à demander (ex : 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
&organization_id=your-organization-id
&scope=invite:member manage:billing

Valider les jetons d’organisation​

Les jetons d’organisation émis par Logto (JWTs) contiennent des revendications que votre application/interface/backend 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é (revendication exp).
  • Vérifier que l’iss (émetteur) correspond à votre endpoint Logto.
  • S’assurer que l’aud (audience) correspond à l’identifiant formaté de l’organisation (ex : urn:logto:organization:{organization_id}).
  • Découper la revendication scope (séparée par des espaces) et vérifier les permissions requises.

Pour des guides détaillés 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é​

  • Ne vous fiez jamais uniquement à l’interface pour l’application des permissions : Validez toujours les permissions côté backend pour les actions critiques.
  • 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 hors API autant que possible (mais les deux peuvent être dans un même rôle).
  • Révisez régulièrement le modèle d’organisation à mesure que votre produit évolue.

FAQ​

Puis-je mélanger des permissions d’organisation et hors 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 les permissions API globales. Cependant, vous pouvez créer des rôles incluant à la fois des permissions d’organisation et des permissions API au niveau de l’organisation.

Où dois-je appliquer les permissions hors API ?​

Vérifiez les permissions hors API à la fois dans l’interface (pour le contrôle d’accès aux fonctionnalités) et dans votre logique serveur pour les actions sensibles.

Pour aller plus loin​

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

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