Managing Roles

Managing Roles

Introduction to Roles in the CMS

Roles allows you to do the following in the CMS:

• Define sections and sub-navigation areas that only certain roles have access too
• Define the columns in list views that certain roles can see
• Define which fields can be edited/viewed when editing a Model record
• Define if the role can edit or delete a record

Setting up Roles in the CMS

To setup a role in the CMS you first need to add records to the Role Model. To do this you can programmatically do it as referenced in LoopBack's documentation or you can manually add it to your database.

Setting up RoleMapping

You can manually set up RoleMapping records in the database or you can do it through the CMS. To implement role assignments you first modify your User Model (at ISBX we create a custom Account Model that uses the Base user model). Here's an extract of the Account.json from our projects:

{
  "name": "Account",
  "options": {
    "idInjection": false,
    "softDeleteProperty": "isDeleted",
    "relations": {
    ...
    }
  },
  "display": [
    "accountId",
    "email",
    "username",
    "password",
    {
      "property": "role",
      "sourceModel": "Account",
      "sourceKey": "accountId",
      "label": "Role",
      "type": "reference",
      "roles": ["SuperAdmin"], //Only SuperAdmin users can manage this roles assignment field
      "options": {
        "model": "Role",
        "key": "id",
        "relationship": "Roles",
        "searchField": "description",
        "placeholder": "Select Roles",
        "multiple": true,
        "matchTemplate": "{{ $item.description }}",
        "choiceTemplate": "{{ item.description }}",
        "junctionMeta": {
          "principalType": "USER" //important for RoleMapping Model
        }
      }
    },
    "created"
    ],
  "properties": {
  ...
  },
  "base": "User",
  "acls": [...]
}

It's important that you setup the CMS config.json properly with the authModel pointing to your custom User Model as the CMS uses this property to setup the relationships with Role and RoleMapping Models. Without the relationships setup the CMS role implementation will not work properly.

Setting up ACLs

Make sure you setup your Role ACLs so that your users can login and also read from the Role and RoleMapping` Models. For MySQL/PostgresSQL LoopBack projects at ISBX we use the base ACL Model and create an ACL Table in our MySQL/PostgresSQL Database.

Additionally, you'll want to setup ACL for your User Model. Here's an extract of the ACL in our Account.json to deny anyone from accessing the User Model except for SuperAdmin.

    {
        "accessType": "*",
        "permission": "DENY",
        "principalType": "ROLE",
        "principalId": "$everyone",
        "property": "*"
    },{
        "accessType": "*",
        "permission": "ALLOW",
        "principalType": "ROLE",
        "principalId": "SuperAdmin",
        "property": "*"
    }

Defining Role Access to sections in the CMS

In the CMS config.json nav property you can specify the roles array property to define which roles have access to the section or sub-navigation:

"nav": [
      {
        "label": "Users",
        "path": "users",
        "icon": "fa-user",
        "roles": ["SuperAdmin"],
        "subnav": [
          {
            "label": "Add",
            "route": "edit",
            "roles": ["SuperAdmin"],
            "options": {
              "model": "Account",
              "key": "accountId"
            }
          },
          {
            "label": "All Users",
            "route": "list",
            "roles": ["SuperAdmin"],
            "options": {
            ...
            }
          }
        ]
     }
  ]

Defining columns that only certain Roles should see

To limit what roles can see which columns you can add the roles array property to the column definition:

{
  "field": "eventId",
  "roles": ["SuperAdmin"],
  "displayName": "Edit",
  "headerClass": "center",
  "cellClass": "center",
  "width": 64,
  "cellTemplate": "<a ui-sref=\"..\">Edit</a>"
}

Defining fields that can be edited by a certain Role

In the Model JSON you can add the roles array property to the display property of the field:

"birthDate": {
      "type": "Date",
      "required": false,
      "length": null,
      "precision": null,
      "scale": null,
      "mysql": {
        "columnName": "birthDate",
        "dataType": "datetime",
        "dataLength": null,
        "dataPrecision": null,
        "dataScale": null,
        "nullable": "YES"
      },
      "display": {
        "label": "Birth Date",
        "roles": ["SuperAdmin", "SiteAdmin"]
        "options": {
          "format": "YYYY-MM-DD",
          "viewMode": "years"
        }
      }
    }