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.

But only the user proper is synced, and *not* the roles they belong to
(see next section for that).

When making a new user account it's possible to mark it as "local only"
- which causes it to *not* be synced to other nodes.  It should exist
only in the node where it was created.


Roles
~~~~~

By default *no* roles are synced across nodes; each is "local only"
effectively.

However you can mark a role as "synced" - which will cause it to be
synced across all nodes.  There are two flags you can set:

"Sync Attrs & Perms" is the flag you would set in order to cause the
role to be synced at all, in the first place.  As the name implies
this will sync the role proper as well as its permission list.

"Sync Users" is the flag to set if you want the role's user list to be
synced as well.

.. note::
   Role names must be unique within each system.  If you have 2 nodes
   and they each have e.g. a "Manager" role defined (separately), and
   then you turn on sync for one of them, there will be an error.

   Instead rename the one you don't want to keep, then turn on sync
   for the one you do.

Node Types
++++++++++

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.)

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*
to all nodes, but will only be actually *used* on the store nodes.