Aller au contenu

Rôles et lignes de permission

Un rôle est un document du doctype iam.Roles. Son id prend la forme qualifiée iam.Roles.<name>, par exemple iam.Roles.editor. Le rôle rassemble des lignes de permission, un niveau, des étiquettes de visibilité de champs, et les canaux de connectivité. Cette page explique les parties, et le garde-fou qui borne qui peut changer quoi.

  • Vous écrivez ou modifiez un rôle et devez en énoncer la portée exactement.
  • Vous devez savoir pourquoi une écriture de rôle a répondu 403.
  • Vous auditez quels rôles portent les actions d’opérateur sensibles.
Champ Contenu
name Le nom de rôle unique. Il forme l’id du document et est immuable.
level Entier obligatoire de 0 à 100. Il ordonne les rôles par autorité.
permissions Les lignes de permission.
visible_tags Les étiquettes de champs que le rôle peut voir. Par défaut ["default"] ; ["*"] voit tout.
connectivity Les canaux programmatiques, voir ci-dessous.
description Du texte libre pour les humains.

Une ligne a quatre parties. Toutes sont facultatives sauf action et on :

Partie Contenu
action read, create, update, delete, *, ou une action nommée.
on Un chemin de doctype, par exemple crm.Deal, ou le joker *.*.
scope Un tableau de périmètres de lignes nommés. Ils se combinent en OU.
except Un tableau de chemins concrets soustraits de la portée.

Une ligne sur un chemin parent couvre aussi les enfants imbriqués. Une ligne sur crm.Project correspond aussi à crm.Project.Comment. Le joker *.* correspond à chaque doctype de chaque domaine. Les rôles admin créés par l’initialisation le portent.

La forme tableau est obligatoire sur chaque chemin d’écriture. Chaque entrée nomme un périmètre déclaré sur le doctype cible. Les alias se combinent en OUà: la ligne atteint les lignes qui répondent à l’un des alias. Omettre scope atteint toutes les lignes. Voir Les périmètres de lignes pour la déclaration et les alias.

except resserre une seule ligne. Les entrées sont des chemins domaine.Doctype concretsà ; pas de jokers. Une entrée fait de la correspondance par préfixe comme on : une entrée sur core.DocType exclut aussi core.DocType.Comment. C’est de l’arithmétique de chemins, pas un système de refusà : elle n’accorde rien, et elle ne touche que la ligne qui la porte.

Chaque exemple est une ligne complète, avec l’effet énoncé.

{"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": "create", "on": "crm.Deal"}

Cette ligne laisse un membre créer une affaire partout dans crm.Deal.

{"action": "update", "on": "*.*", "except": ["core.Domain", "core.DocType"]}

Cette ligne laisse un membre modifier chaque document sauf les deux surfaces de définition : la forme des domaines et des doctypes reste en lecture seule pour lui.

{"action": "read", "on": "fin.Invoice", "scope": ["$mine"]}

Cette ligne laisse un membre lire uniquement les factures qu’il possède.

{"action": "read", "on": "hr"}

Un chemin à un seul segment, un nom de domaine en minuscules, couvre tout le domaine. Cette ligne laisse un membre lire chaque doctype de hr.

connectivity est un tableau tiré d’un vocabulaire ferméà : mcp, webhook, api et assistant. Il décide quelles portes programmatiques le rôle peut ouvrir du tout. Une liste vide donne un rôle réservé au navigateur. Les sessions navigateur et les tokens d’application ne dépendent jamais du champ.

  • api — le rôle peut porter des clés d’API. Voir Accès machineà : clés d’API.

  • mcp — des agents peuvent se connecter par la surface MCP (Model Context Protocol) avec ce rôle.

  • webhook — le rôle peut créer et recevoir des webhooks. Voir Webhooks sortants.

  • assistant — le rôle peut ouvrir l’assistant IA (intelligence artificielle). Voir Gouverner l’assistant.

    Chaque barrière de canal lit le rôle en direct. Un canal retiré s’applique à la requête suivante.

En plus des quatre actions CRUD, une ligne peut accorder une action nommée. Les noms d’actions qui barrent des routes fixes valent d’être connusà :

Action Sur Barre
provision_credentials iam.Account Mots de passe temporaires, liens d’invitation, lectures des états d’identifiants.
mfa_disable iam.Account POST /Api/iam/mfa/disable, la récupération par l’administrateur.
publish_artifact le doctype cible Fabriquer des liens de fichiers permanents sur ce doctype.
revoke *.* Révoquer n’importe quel lien de fichier.
download *.* Télécharger n’importe quel fichier comme opérateur.
purge *.* Supprimer définitivement n’importe quel fichier, la suppression auditée.

Chaque écriture contrôlée par l’appelant sur iam.Account et iam.Roles passe par un seul garde-fou. Il couvre create, update, delete, les actions nommées, et les transitions de retour arrière. Un refus répond 403. Le niveau de l’appelant vient de l’unique rôle élu de la requête, jamais du rôle le plus élevé qu’il porte.

Contrôle Règle
Affectation Chaque rôle du tableau roles final doit exister, être vivant, et se situer au niveau de l’appelant ou en dessous. default_role doit en faire partie.
Même niveau Un appelant peut affecter un rôle de son propre niveau, même quand ce rôle porte des pouvoirs qui lui manquent.
Protection de la cible Aucune écriture sur un compte ou un rôle dont le niveau courant dépasse celui de l’appelant, pas même pour l’abaisser.
Écriture du rôle Le niveau résultant ne doit pas dépasser celui de l’appelant. Chaque nouvelle ligne doit découler du rôle précédent ou du rôle de l’appelant. Les nouvelles étiquettes visibles doivent rester dans l’union des deux. Les canaux de connectivité et le budget de l’assistant suivent la même inclusion.

La règle d’inclusion borne un éditeur de rôlesà : un éditeur de niveau 30 ne peut pas élargir un rôle de niveau 20 au-del à de ce que le contenu précédent ou son propre rôle implique. Voir Affecter les rôles et l’élection pour le flux d’affectation.

Id du rôle Niveau Portée
iam.Roles.admin 100 * sur *.*, tous les canaux, toutes les étiquettes.
iam.Roles.editor 30 Lit et modifie le contenu partoutà ; les surfaces de définition et core.SystemSettings sont retranchées avec except.
iam.Roles.viewer 20 Lit partout, avec les mêmes retranchements.
iam.Roles.comment_author 20 Lecture, modification et suppression sur core.Comment, limitées à l’auteur par $mine.
iam.Roles.attachment_owner 20 Lecture, modification et suppression sur core.Attachment, limitées à la personne qui a déposé le fichier par $mine.
iam.Roles.anonymous 0 Sert les requêtes sans identifiant. Ses attributions de lecture forment la surface publique de l’API. Supprimez-le, et ces requêtes répondent 401.

Le retranchement de core.SystemSettings est le modèle à copierà : les rôles editor et viewer créés par l’initialisation soustraient le chemin de leurs lignes générales avec except: ["core.SystemSettings"], et les réglages d’exécution restent réservés aux administrateurs. Un rôle sur mesure peut toujours recevoir le chemin explicitement.

L’id du document est iam.Roles.<name>, et les documents comptes référencent cet id. Un renommage désynchroniserait l’id du nomà ; le hook de mise à jour refuse donc toute écriture qui porte name. Pour renommer, créez un nouveau rôle sous le nouveau nom, déplacez les affectations, puis supprimez l’ancien. Le hook de suppression refuse tant qu’un compte porte encore le rôle.

Créez un rôle de lecture régionale pour le domaine fin :

Fenêtre de terminal
curl -k -X POST -H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "regional_reader",
"level": 10,
"visible_tags": ["default"],
"permissions": [
{"action": "read", "on": "fin.Invoice"},
{"action": "read", "on": "hr.Employee", "scope": ["$mine"]}
]
}' \
"https://facet.localhost:3443/Api/iam/Roles"

Le nouveau rôle lit chaque facture et laisse chaque membre lire sa propre fiche employé. Il ne porte aucun canal ni aucune action d’opérateur.

Vérifiez les quatre lignes du garde-fou ci-dessus. La cause la plus fréquente est une nouvelle ligne de permission que le propre rôle de l’appelant n’implique pas, ou une cible dont le niveau dépasse celui de l’appelant.

Une écriture avec un périmètre en chaîne répond 422 must be an array

Section intitulée « Une écriture avec un périmètre en chaîne répond 422 must be an array »

Les chemins d’écriture exigent la forme tableau. Remplacez "scope": "$mine" par "scope": ["$mine"].

Le nom est immuable. Recréez le rôle sous le nouveau nom.

Vérifiez visible_tags sur son rôle — voir Visibilité des champs par étiquettes.