Aller au contenu

Les périmètres de lignes

Une ligne de permission atteint un doctype entier, ou seulement les lignes qui répondent à une condition. Un périmètre de lignes nomme cette condition. Le doctype déclare ses périmètres une foisà ; un rôle s’y réfère par alias et n’écrit jamais ses propres prédicats.

  • Un rôle ne peut voir ou changer que ses propres lignes.
  • Un rôle peut voir des lignes qui répondent à une règle partagée, par exemple chaque projet actif.
  • Plusieurs rôles partagent une règle de lignes, et vous voulez la déclarer une fois.
  • La grammaire. Vous connaissez la grammaire des lignes de permission — voir Rôles et lignes de permission.
  • La déclaration. Les périmètres doivent exister sur la définition du doctype avant qu’un rôle puisse s’y référer. Les étapes d’écriture vivent dans Les périmètres nommés.

La définition du doctype porte les périmètres sous scopes. Chaque entrée est un filtre where sur les champs propres au doctypeà :

# définition production.Project
scopes:
mine:
description: "Projects owned by the actioner"
where:
owner_id: "$self"
global:
description: "Projects with no owner"
where:
owner_id: "$null"
active:
description: "Projects in the active status"
where:
status: "active"

Les rôles choisissent dans ce catalogue. Ils ne peuvent pas ajouter un prédicat à eux sur une ligne de permission. La grammaire de where :

Valeur Correspond à
"active" La valeur stockée littérale.
"$self" L’id du compte agissant. Il correspond à la fois à la forme référence iam.Account.<id> et à un id nu, si bien qu’un même périmètre fonctionne sur un champ propriétaire de type référence comme de type chaîne.
"$my_teams" Les valeurs d’un ensemble de contexte déclaré par le domaine, résolues à chaque requête. Un ensemble vide ou irrésoluble ne correspond à aucune ligne, même avec ne.
"$null" Les lignes où le champ est absent ou null en JSON. Ne marche qu’avec eq.
"$organizational_unit" Le chemin en arborescence du compte agissant, par exemple /engineering/backend/.

Une clé where peut porter un suffixe d’opérateur, comme les filtres de listeà : priority__gte, title__starts_with, price__between. Une clé nue signifie égal. Un champ accepte exactement les opérateurs que ses capacités filters déclarées permettent. Deux clés réservées existentà : $parent_id lit le lien parent, et $doc_id lit l’id de la ligne. Toutes deux ne prennent que eq ou ne.

Lisez chaque ligne avec son effetà :

{"action": "read", "on": "production.Project", "scope": ["$mine", "$global"]}

Cette ligne laisse un membre lire les projets qu’il possède et les projets sans propriétaire.

{"action": "update", "on": "crm.Deal", "scope": ["$mine"]}

Cette ligne laisse un membre modifier les affaires qu’il possède, et aucune autre.

{"action": "read", "on": "production.Project", "scope": "$all"}

Cette ligne laisse un membre lire chaque projet. $all est la forme explicite sans restrictionà ; omettre scope veut dire la même chose. Dans un tableau, $all ramène toute la ligne à l’absence de restriction.

  • Les listes. Le périmètre se compile en fragment SQL WHERE. Une liste avec périmètre répond 200 avec les lignes qui correspondent, éventuellement aucune. Un périmètre de lignes ne devient jamais un 403.
  • Les lectures individuelles, les mises à jour, les suppressions et les actions. Le contrôleur vérifie la ligne contre le périmètre. Une ligne qui échoue répond le même 404 qu’un document manquant, si bien que la réponse ne révèle jamais que le document existe.
  • La création. Aucune ligne n’existe encore, donc le périmètre ne tourne pas à la création. Le périmètre voyage jusqu’au hook de création Lua comme canal d’intention qui peut positionner des valeurs de champs, par exemple le propriétaire. La vérification du domaine signale un avertissement par ligne de création avec périmètre sur le domaine iam.
  • La redéfinition. Modifiez un périmètre sur le doctype, et chaque rôle qui référence l’alias utilise le nouveau prédicat dès la requête suivante. Aucune édition de rôle n’est nécessaire.
  • Le resserrement à la requête. Les routes de liste et d’agrégat et les outils d’agent acceptent scope=<name>. Cela ne fait que resserrer ce que l’appelant voit déjà. Un nom inconnu répond 422.
  • Les requêtes sans identifiant. Elles tournent sous le rôle anonymous. $self se résout à la valeur littérale anonymous, qui ne correspond à aucun compteà ; les périmètres $self restent donc inertes. $organizational_unit se résout au chemin racine /.

Un administrateur resserre un rôle d’édition sur production.Project :

  1. L’auteur déclare les périmètres mine, global et active ci-dessus.
  2. Le rôle porte la ligne de lecture avec ["$mine", "$global"] et la ligne de mise à jour avec $mine, toutes deux reprises ci-dessus.
  3. Un membre avec ce rôle liste les projets. Facet renvoie les projets que le membre possède plus chaque projet sans propriétaire, et rien d’autre.
  4. Le membre ouvre un projet qu’il possède et le modifie. La modification s’enregistre.
  5. Le membre ouvre un projet qu’un autre compte possède. La lecture répond 404, alors que le projet existe.
  6. Le membre liste avec ?scope=active et n’obtient que le sous-ensemble actif de ce qu’il voyait déjà.

Une liste avec périmètre renvoie des lignes inattendues

Section intitulée « Une liste avec périmètre renvoie des lignes inattendues »

Les alias d’un tableau se combinent en OU. Vérifiez si une ligne porte plus d’alias que voulu, ou si $all se trouve dans le tableau.

La ligne a échoué à la vérification du périmètre. C’est la réponse sans divulgation, par conception — voir Comment Facet vérifie les permissions.

Le nom du périmètre n’est pas déclaré sur le doctype visé par la ligne. Copiez le nom depuis la définition.

Une ligne de création avec périmètre s’enregistre avec un avertissement

Section intitulée « Une ligne de création avec périmètre s’enregistre avec un avertissement »

La création ignore les périmètres, par conception. Déplacez la règle de lignes dans un hook de création — voir Scripts de cycle de vie et garde-fous.

Un rôle project_manager ne lit que les projets de sa propre équipe. Les projets appartiennent à une équipe, et une équipe porte des lignes membres qui nomment un compte. La règle demande deux déclarations — une sur le domaine, une sur le doctype — puis une ligne de rôle nomme le périmètre.

  • Team → TeamMember est une composition : Team est la racine d’agrégat, TeamMember son enfant (member_of: Team), et chaque ligne membre porte une référence account vers iam.Account. Un doctype TeamMember dédié convient ici, parce qu’une appartenance est une ligne qui a sa propre vie, et qu’un compte peut siéger dans plusieurs équipes.
  • Project → Team est une référenceà : Project.team pointe vers projects.Team.
Diagram Diagram

Le diagramme montre les deux relations de données, les deux déclarations qui les lisent, et le rôle qui nomme le périmètre. Les déclarations d’écriture (la paire children/member_of, le champ référence, l’ensemble de contexte my_teams, et le périmètre team_projects) sont sur Les périmètres nommés. La partie admin suit.

Le rôle project_manager porte une ligne de lecture sur projects.Project :

{
"action": "read",
"on": "projects.Project",
"scope": ["$team_projects"]
}

team_projects est un périmètre que le doctype déclare, avec where: { team: "$my_teams" }. L’ensemble de contexte $my_teams se résout, à chaque requête, aux ids des équipes auxquelles l’appelant appartient.

  1. La personne appartient à deux équipes. Une liste de projects.Project renvoie les projets des deux équipes, et rien d’autre.
  2. Une lecture directe d’un projet d’une autre équipe répond 404, alors que le projet existe — la réponse sans divulgation de Comment Facet vérifie les permissions.
  3. La personne rejoint une nouvelle équipe. La requête suivante résout le nouvel ensemble my_teams et renvoie les projets de la nouvelle équipe. Aucune édition de rôle n’est nécessaire.