User Accounts

Preliminaries

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.

The 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 /etc/rwserve/roles.

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
						

The 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 shaDigest.

Finally, the 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.

Persistence

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.

Permissions

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
						

Login

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.

Review

Key points to remember:

• Basic user account data is stored in the roles file.
• Passwords are not recoverable from the stored hash.
• All user accounts are automatically assigned the "anonymous" role.