From 922a7a5f1110669173650dc94836916c360be32d Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Thu, 14 Oct 2021 10:41:18 -0400 Subject: [PATCH] Add overview docs for user auth (login + permissions) --- docs/data/auth.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++ docs/data/index.rst | 1 + 2 files changed, 173 insertions(+) create mode 100644 docs/data/auth.rst diff --git a/docs/data/auth.rst b/docs/data/auth.rst new file mode 100644 index 0000000..8358b4b --- /dev/null +++ b/docs/data/auth.rst @@ -0,0 +1,172 @@ + +User Auth +========= + +Rattail of course includes the concept of a "user" account. In +general the purpose this serves is 2-fold: + +* restrict access to certain parts of the app +* provide attribution, e.g. "who did what (and when)" + + +Overview +-------- + +Rattail has a User table, which contains the basic account record. It +is quite minimal but a User can relate to a Person, and then +indirectly a Customer etc. + +User records then are associated to a great many other things, +e.g. when a user creates a new batch, their user account is associated +with that batch. + +User accounts do not themselves, directly, have "permission" to do +anything. But a User may belong to zero or more Roles, which then +grant it permission to do things. (Even if zero, the special +"Authenticated" role may automatically grant some permissions; more on +that below.) + + +Authentication (aka. Login) +--------------------------- + +Normally each person who "logs in" to Rattail must already have a User +account. The login succeeds if they supply correct username and +password, both of which are stored in the User account (with the +password being encrypted). + +Additionally, the User account may be marked "inactive" by the admin; if +so then login will not be allowed for that user. + +Customization is possible, for instance to check credentials against +Active Directory or your POS system etc. User accounts may even be +auto-created on first login etc. + + +Authorization (aka. Permissions) +-------------------------------- + +Rattail has a Role table, to define various user roles. The admin can +create new roles as needed, to reflect the organizational realities +etc. + +Permissions then are granted to (or revoked from) the various roles +which are defined. If a permission is "attached" to the role, then +the role "has" it, otherwise not. + +Users then may be associated with zero or more roles, and they inherit +the full set of permissions from all roles to which they belong. + + +Special Roles +~~~~~~~~~~~~~ + +There are 3 special roles which come built-in: + + +.. _admin_role: + +Administrator ++++++++++++++ + +This role is special for obvious reasons. + +Only users who belong to this role, can "become root" (see +:ref:`becoming_root`). + +Other than that though, the role behaves normally. For instance if +you are the admin user and only belong to this role, then you will +normally see only those things which are included in this role's +permissions (unless you become root of course). + +Permissions for this role may be edited as for any other role. +Although there is a chance that you must "become root" to do so; that +is normal and not something that requires fixing per se. + + +Guest ++++++ + +This "guest" role is really "anonymous" - i.e. any "user" who is +actively using the system but has not logged in, falls into this role +automatically. + +Permissions for this role may be edited as for any other role. But +they will apply *only* to users who are not logged in. + + +.. _auth_role: + +Authenticated ++++++++++++++ + +This role automatically applies to any user who *has* logged in, +regardless of any other roles the user may belong to. + +Permissions for this role may be edited as for any other role. They +will apply to anyone who has logged in. + + +.. _becoming_root: + +Becoming Root +~~~~~~~~~~~~~ + +Any user who belongs to the special Administrator role (see +:ref:`admin_role`) - and *only* users in that role - are automatically +granted permission to "become root" when they are logged in. + +Becoming root is similar in spirit to the ``su`` command in Unix. +Basically when you become root, all normal permission checks are +bypassed; you can do anything "supported" by the system. Note that +the term "supported" is used loosely here, and just means whatever the +code can "literally" do. (Some of which may be bad for your system!) + +So of course be careful with this, it can be quite handy but if you +find yourself "frequently" using it to access some feature, you +probably should just grant permission for that feature to the +Administrator role, and then you can stop having to become root all +the time! (Which helps to avoid doing something bad by accident.) + + +Syncing Users & Roles +--------------------- + +Users and roles are closely related, but how (and/or whether) they are +synced across app nodes, is handled differently. + + +Users +~~~~~ + +By default all users are synced across all nodes; simple as that. + +It is possible however to mark a user account as "local only" - which +will cause that particular user to *not* be synced to other nodes; it +will exist only in the current node. + + +Roles +~~~~~ + +By default *no* roles are synced across nodes; each is "local only" +effectively. + +It is possible however to mark a role as "synced" - which will cause +that role to be synced across all nodes. + +In a multi-node system it is likely that there are different "types" +of nodes. In such a system it may be useful to sync certain roles, +but have them only "apply" to certain node types. (The roles must +exist in all nodes for sync to work properly, but need only apply to +certain nodes.) + +If a role is synced, then not only its primary attributes (e.g. name) +will be synced, but also its user "membership" list as well as its +permission list. + +The main use case here is in a multi-store setup, where you have one +"host" node and two or more "store" nodes. You can create a role with +node type of "store" and flag it for sync. The role will be synced +along with its users and permissions, but will only be actually *used* +on the store nodes. diff --git a/docs/data/index.rst b/docs/data/index.rst index 03060bb..d4b79e8 100644 --- a/docs/data/index.rst +++ b/docs/data/index.rst @@ -9,6 +9,7 @@ Data Layer db/index trainwreck other + auth importing/index sync versioning