rattail-manual/docs/data/auth.rst

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.