npm package: @revector/ui-admin-console
Description: A basic administration console
Latest version: 0.0.1-beta.5

= Auth-Service

Setting up new projects always involves the annoying step of creating the User authorization scheme. This component helps side-step most of the tedious boilerplate associated with creating the backend for mapping Roles and Permissions to each User.

@revector/auth-services handles the Authorization side of Users/Roles/Permissions management. It ties into Firebase's Authentication handling, but mostly focuses on the Authorization side of things.

In case you're wondering, authentication is "Are you who you say you are?" and authorization is "I believe that you are who you say you are, but are you allowed to do this?".

=== Structure

Permission::
    A Name/Description pair. Nothing fancy: 'CAN CREATE ROLE' / 'A user with this permission is allowed to create new Roles'.

Role::
    A Name/Description pair associated with a list of Permissions. For example an 'Administrator' role would probably be assigned all Permissions, giving members of the Administrator Role the right to do anything.


User::
    Each User has an identifier, a set of Roles and a set of Permissions. When a User is assigned a Role, the Role's permissions are 'copied' into the User's list of Permissions. There's a reason behind this, which we'll get to shortly. A User is associated with the Firebase authentication identifier for each Firebase auth user. See the Firebase Auth console for your firebase project: https://console.firebase.google.com/project/${YourProject}/authentication/users.


=== About User Permissions

As mentioned earlier, when a User is assigned a Role, the permissions from the Role are copied into the User's list of permissions. There's a reason for this madness.

While it would be easier to loop through a User's Roles and sum up the Permissions on each login or somesuch, the Firebase Auth system doesn't work well with such a logic-heavy lookup. If you aren't familiar with https://firebase.google.com/docs/database/security/securing-data[Firebase auth configuration], that's okay. But you'll have to believe us when we tell you that having a single table which only contains the allowed values makes things MUCH easier on us when we go to configure permissions with Firebase. And it turns out it's pretty easy to use within the application as well.

If you are familiar, or just went and became so, what copying the permissions allows us to do is this:


[source, javascript]
// Firebase Auth configuration JSON:
"auth": {
      "permissions": {
        ".read": "auth != null",
        ".write": "auth != null && root.child('auth/user_permissions').child(auth.uid).hasChild('MODIFY PERMISSIONS')"
      },
      "roles": {
        ".read": "auth != null",
        ".write": "auth != null && root.child('auth/user_permissions').child(auth.uid).hasChild('MODIFY ROLES')"
      }
   }


A real test for write of such critical fields should include additional checks for creation, and ESPECIALLY for deletion, as roles and permissions should never be modified outside of a transaction, if ever. Modifying a Permission name is actually kind of a big deal, once you app is up and running.

In any event, you can see how simple the lookup is using a single permission table. If you were to try to map permissions dynamically based on assigned roles this would be either incredibly difficult or impossible. It would absolutely be unmaintainable.


=== Bootstrapping

@todo