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.