# authorization
Authorization is a _role-based-access-control_ (RBAC) library, to find _permission_ for the logged-_user_ on a _resource_.  
  
A _resource_ can be a _check box_, _button_, or _textarea_ in html page.  
  
Permissions can be used to _enable_/_disable_/_view_/_hide_ components such as checkbox, input text, buttons, ... in html pages.  
  
  
## mappings of user - roles - permissions    
Following two mapping files are used; they are external; they can be edited in any text editor:  
* user to roles mapping file (refer [sample_user-roles.json](https://github.com/mohankumaranna/authorization/blob/master/sample_user_roles.json))  
* for each resources, a role to permissions mapping is added. (refer [sample_resource_permissions.json](https://github.com/mohankumaranna/authorization/blob/master/sample_resource_permissions.json))  
  
## permissions 
A resource can have one or more of the following permission type:  
*  __C__ reate (also known as Add)  
*  __R__ ead (aka View)  
*  __U__ pdate (aka Edit)  
*  __D__ elete  (aka Remove)

## explanations  
* __user to roles__  mapping

    Let's say, an user to have a view only role, a mapping can be made like:  
  ```
  {  
      "user_id": "1000",  
      "roles": ["viewer"]  
  }  
  
  Note: More than one role can be assigned within square bracket, like ["viewer", "supervisor"].  
  ```  

* __resource's role to permissions__  mapping  
  Let's say resource is a checkbox. Permission is required to enable/disable it.  
    
  role to permissions mapping can be like:  

```
{  
     "resource": "cb_enable",  
     "description": "enable or disable this checkbox",  
     "role2permissions": [  
        {"role": "viewer", "permission": "R", "condition": "{{resource_owner_id}} == {{session_user_id}}" },  
        {"role": "editor", "permission": "RU", "condition": "{{resource_owner_id}} == {{session_user_id}}" },  
        {"role": "admin", "permission": "CRUD" }]  
}  
```  
  
  **Note:**  
  a. In the above JSON notation, for a `cb_enable` resource, three roles to permissions mapping are made.  
  
  b. First role is a _viewer_ role, for which, permission is assigned as `R`, that means `READ-ONLY` permission, on a _condition_ that only owner of the resource, can view this check box.  
  
*    each resource, when created by an user, s/he becomes owner of it, his/her user id is stored/persisted as owner_id.  
  
*    when s/he login the application at later point in time, s/he will be identified through session user details.  
  
*    so, a comparision between stored owner_id is made with currently logged user (also referred as session user).  
  
*    a `Handlebars Template notation` is used in defining this condition.  
  
*    variables in this condition are resolved, and then comparision is done.  For now, only simple comparision is possible, such as: `a == b`, `a < b`, ...  
  
  c. Second role is an _editor_ role, which is assigned with `RU`, that means `READ and UPDATE` permissions, on condition that only owner of the resource, can view and update.  

  d. Third role is an _admin_ role, which is assinged with `CRUD`, that means `All permissions: CREATE, READ, UPDATE, DELETE`. No condition is needed here.  
  

## how to use it  
  Refer sample code below:
```
    let mut authzn = Authorization::load("./sample_resource_permissions.json", "./sample_user_roles.json");
    
    let user_id = "1002";
    authzn.set_permissions_for(user_id);
    
    let resource = "cb_enable";
    let owner_id = "1001";
    let mut data = Map::new();
    
    data.insert("resource_owner_id".to_string(), to_json( &owner_id ) );
    data.insert("session_user_id".to_string(), to_json( &user_id) );    

    let mut permitted = authzn.allows_add(&user_id, &resource, &data);
    if permitted { println!("CREATE PERMITTED"); } else { println!("Create NOT Permitted");}

    permitted = authzn.allows_view(&user_id, &resource, &data);
    if permitted { println!("VIEW PERMITTED"); } else { println!("View NOT Permitted");}

    permitted = authzn.allows_edit(&user_id, &resource, &data);
    if permitted { println!("EDIT PERMITTED"); } else { println!("Edit NOT Permitted"); }

    permitted = authzn.allows_delete(&user_id, &resource, &data);
    if permitted { println!("DELETE PERMITTED"); } else { println!("Delete NOT Permitted"); }
```
___