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.
Quand l’utiliser
Section intitulée « Quand l’utiliser »- 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.
Avant de commencer
Section intitulée « Avant de commencer »- 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.
Explication
Section intitulée « Explication »Où vivent les périmètres
Section intitulée « Où vivent les périmètres »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.Projectscopes: 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.
Ce que dit une ligne de permission
Section intitulée « Ce que dit une ligne de permission »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.
Comment Facet applique un périmètre
Section intitulée « Comment Facet applique un périmètre »- Les listes. Le périmètre se compile en fragment SQL
WHERE. Une liste avec périmètre répond200avec les lignes qui correspondent, éventuellement aucune. Un périmètre de lignes ne devient jamais un403. - 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
404qu’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épond422. - Les requêtes sans identifiant. Elles tournent sous le rôle
anonymous.$selfse résout à la valeur littéraleanonymous, qui ne correspond à aucun compteà ; les périmètres$selfrestent donc inertes.$organizational_unitse résout au chemin racine/.
Un administrateur resserre un rôle d’édition sur production.Project :
- L’auteur déclare les périmètres
mine,globaletactiveci-dessus. - Le rôle porte la ligne de lecture avec
["$mine", "$global"]et la ligne de mise à jour avec$mine, toutes deux reprises ci-dessus. - 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.
- Le membre ouvre un projet qu’il possède et le modifie. La modification s’enregistre.
- Le membre ouvre un projet qu’un autre compte possède. La lecture répond
404, alors que le projet existe. - Le membre liste avec
?scope=activeet n’obtient que le sous-ensemble actif de ce qu’il voyait déjà.
Dépannage
Section intitulée « Dépannage »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.
Un membre reçoit 404 sur un document qui existe
Section intitulée « Un membre reçoit 404 sur un document qui existe »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.
L’API répond Unknown scope
Section intitulée « L’API répond Unknown scope »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.
Exemple complet, ses projets via les équipes
Section intitulée « Exemple complet, ses projets via les équipes »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.
Le modèle de documents
Section intitulée « Le modèle de documents »- Team → TeamMember est une composition :
Teamest la racine d’agrégat,TeamMemberson enfant (member_of: Team), et chaque ligne membre porte une référenceaccountversiam.Account. Un doctypeTeamMemberdé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.teampointe versprojects.Team.
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.
La ligne du rôle
Section intitulée « La ligne du rôle »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.
Ce que voit le manager
Section intitulée « Ce que voit le manager »- La personne appartient à deux équipes. Une liste de
projects.Projectrenvoie les projets des deux équipes, et rien d’autre. - 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. - La personne rejoint une nouvelle équipe. La requête suivante résout le
nouvel ensemble
my_teamset renvoie les projets de la nouvelle équipe. Aucune édition de rôle n’est nécessaire.
Voir aussi
Section intitulée « Voir aussi »- Les périmètres nommés — déclarez les périmètres et leurs ensembles de contexte sur le doctype et le domaine.
- Rôles et lignes de permission — la
grammaire des lignes autour de
scope. - Visibilité des champs par étiquettes — resserrer au niveau des champs de la même façon.
- Comment Facet vérifie les permissions — où siègent les contrôleurs.
- Internes sur GitHubà : rbac.md.