Creating role based user accounts to access resources
This note describes how user credentials are created through an external CLI utility. Passwords are SHA256 hashed using a nonce. Passwords are not discoverable or recoverable.
The RBAC Auth handler provides a way to login and logout of a website and to receive authorization to access designated resources based on a user's role or roles. In order for that mechanism to be useful, there must be a way to create user accounts, assign roles to users, and safely secure credentials against threats from bad actors.
rwserve-roles CLI utility is used to create user accounts.
Input to the utility is a user name, a clear-text password, and a comma-separated list of roles. Each of these three values are connected into a single string using a colon
: operator. Output is sent to the console's stdout, which is normally redirected by BASH script to the file
All accounts must have, at a minimum, the "anonymous" role. This will be enforced by the
rwserve-roles CLI utility, automatically adding it to the list when not explicitly provided.
Role names are not prescribed by the server. It is up to the webmaster to determine which roles are useful and to define identifying names for them.
A good recommendation to remember is: more roles leads to more complicated configurations leading to a greater risk of accidentally blocking legitimate access or accidentally allowing illegitimate access.
rwserve-roles in action
Here is an example demonstrating how to create a new user account for "webmaster" having the roles "editor" and "devops":
sudo rwserve-roles webmaster:secret:editor,devops >> /etc/rwserve/roles
rwserve-roles CLI utility hashes the clear-text password into a 32-byte SHA256 value. This password is never saved, and there is no retrieval or recovery method that can decrypt the hash. The hashing algorithm uses a separate 16-byte nonce to ensure that no two users have the same hash value, even if they coincidentally have the same password.
The combination of hash and nonce are stored in the
roles file as a
rwserve-roles CLI utility generates a UUID, which can be used by the webmaster as a unique key to other user data — such as name, contact information, preferences, etc. — stored in a separate file or database.
The location of the roles file is not predefined, but a common practice is to place it in
/etc/rwserve/roles. The webmaster configures the location of this file by specifying its path in the
roles entry of the
rbac configuration section.
Here is what the roles file might look like after creating the webmaster account:
webmaster ee13abc8-1b37-46d0-bfc2-425169411f6a 9ea896dc91018a6a9bc03e48e1c2b3dd:2ce0b565b347b454fbeb0636c0780c99e0542aaa145f8b02cae93b1115df4e47 editor,devops,anonymous
It is a plain text file with one account on each line, consisting of four tab-separated fields: 1) user, 2) UUID, 3) base64-encoded nonce:shaDigest, and 4) a comma separated list of roles.
The roles file is read into memory, and indexed for fast retrieval, at startup time. This mechanism is straightforward and simple, yet powerful enough to handle thousands of users, accommodating the needs of many typical websites.
The roles file must be readable by the server software and writable by the
rwserve-roles CLI utility. Apply these permissions:
chown root:rwserve /etc/rwserve/roles
chmod 640 /etc/rwserve/roles
During login, the user provides the clear-text password again (over secure SSL), and the same hashing algorithm is applied. Authentication is accepted only if the two hashes are the same.
If the user has forgotten the password, a new one must be provided, and a new hash generated from it.
Key points to remember:
- Basic user account data is stored in the
- Passwords are not recoverable from the stored hash.
- All user accounts are automatically assigned the "anonymous" role.