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:

Administrator

This role is special for obvious reasons.

Only users who belong to this role, can “become root” (see 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.

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

Any user who belongs to the special Administrator role (see Administrator) - 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.