Admin Security

The Broadleaf Commerce Admin provides the ability to granularly control the access rights for admin users.

Definitions

Admin User

Represents a user with a login and password to access admin functionality. A user can be assigned one-or-more Roles as well as one-or-more Permissions.

Role

A role represents a group of Permissions. Generally, a user is assigned a role like "Content Editor". The role would be setup to contain all of the permissions necessary to complete that role.

Permission

A permission represents a privilige to do some functionality within the admin. Examples could include "View Customers" or "Manage Products". While this basic permission model is easy to understand, Broadleaf provides a couple of additional technical details that are important for those adding custom permissions and capabilities to understand that are discussed below.

There are two types of permissions in the system - Friendly Permissions and Child Permissions

Friendly Permissions

Friendly Permissions are those permissions that appear in the Permissions UI of the Admin. These permissions are usually prefixed with "View" or "Maintain". While these permissions can used to influence a users privileges within the Admin, the typical configuration is to only have these represent groups of Child Permissions.

Child Permissions

Child Permissions are the permissions that actually control the admin user privileges within the application. These permissions are usually prefixed with "Read" or "All".

Once example of how the Friendly and Child Permissions may be setup is for Products and Categories. The Product permissions will have a Friendly Permission of "Maintain Products" which multiple Child Permissions "All Products", "All Sku", "Read Product Options", etc. Notice that there are permissions with read/write capability and permissions with only read capability. Likewise, Category permissions will have the Friendly Permission of "Maintain Categories" with Child Permissions of "All Categories", "Read Product", "Read SearchFacet", Etc.

Each Friendly Permission should encompass all the Child Permissions to allow the user to perform the required Admin UI functions.

The menu items that an Admin User sees are related to the permissions that they have.

For example, consider the following SQL that was pulled from the load_admin_menu.sql file.

-- Here is SQL the defines permissions for Viewing and Maintaining categories.   
-- Note:  There is more to this ... see "more details about permissions" below ...
INSERT INTO BLC_ADMIN_PERMISSION (ADMIN_PERMISSION_ID, DESCRIPTION, NAME, PERMISSION_TYPE, IS_FRIENDLY)
  VALUES (-100,'View Categories','PERMISSION_CATEGORY', 'READ', TRUE);

INSERT INTO BLC_ADMIN_PERMISSION (ADMIN_PERMISSION_ID, DESCRIPTION, NAME, PERMISSION_TYPE, IS_FRIENDLY) 
  VALUES (-101,'Maintain Categories','PERMISSION_CATEGORY', 'ALL', TRUE);


-- The following SQL inserts an Admin Module which represent the top level menu items like 'Content', 'Catalog'
INSERT INTO BLC_ADMIN_MODULE (ADMIN_MODULE_ID, NAME, MODULE_KEY, ICON, DISPLAY_ORDER) 
  VALUES (-1,'Catalog','BLCMerchandising', 'icon-barcode', 100);

-- The Menu Items (Sections) are added to a module with SQL like the following
INSERT INTO BLC_ADMIN_SECTION (ADMIN_SECTION_ID, DISPLAY_ORDER, ADMIN_MODULE_ID, NAME, SECTION_KEY, URL, CEILING_ENTITY)   VALUES (-1, 1000, -1, 'Category', 'Category', '/category', 'org.broadleafcommerce.core.catalog.domain.Category');

-- Finally, the section is associated with permissions that allow the user to see that menu item.
-- The example below associates the Category Menu Item with permissions with ID -100 or -101
INSERT INTO BLC_ADMIN_SEC_PERM_XREF (ADMIN_SECTION_ID, ADMIN_PERMISSION_ID) VALUES (-1,-100);
INSERT INTO BLC_ADMIN_SEC_PERM_XREF (ADMIN_SECTION_ID, ADMIN_PERMISSION_ID) VALUES (-1,-101);

In this example, having either the "View Categories" or the "Maintain Categories" allows the "Category" menu section to be visible for the Admin Users who has one of these Friendly Permissions.

Permissions and Entities

The Broadleaf Admin provides a lot of functionality with a very tight security model. When a user is given a "Permission", the system needs to understand what underlying Entities (think tables) that they can view or modify.

This can sometimes be quite involved. For example, consider a user that can edit products but not categories. In this example, the user would need "Edit" access to Products but "View" access to categories since one of the properties on a product is it's default category.

To handle this (and much more complex scenarios), Broadleaf has the following logical permission model.

Some notes about the above diagram.

Both "Friendly" and "Child" Permissions live in the BLC_ADMIN_PERMISSION table.
Child Permissions have a permissionType which can be READ, ALL, DELETE, UPDATE, CREATE. Broadleaf only uses READ and ALL but the others are available for custom solutions.
Each Child permission is associated with 1 or more EntityPermissions
EntityPermissions directly relate to the underlying JPA objects (like CategoryImpl.java).

Permission and Roles

Broadleaf supports the concept of Roles. A Role is a grouping of Friendly Permissions. It is recommended that you use Roles as your means for assigning Permissions to Admin Users. It makes the management of Admin Users much easier. Broadleaf does show with a pre-configuration set of Roles that can be associated to Admin Users.

Getting a view of what Permissions are setup

Below is a helpful query that will provide a view into how Roles and Permissions are currently setup in your system.

SELECT ar.description role_description, friendly.description friendly_description, friendly.name friendly_name, 
friendly.is_friendly friendly_is_friendly, friendly.permission_type friendly_permission_type, 
child.description child_description, child.name child_name, child.is_friendly child_is_friendly, 
child.permission_type child_perm_type
FROM BLC_ADMIN_ROLE ar 
  INNER JOIN BLC_ADMIN_ROLE_PERMISSION_XREF rolexref on ar.admin_role_id = rolexref.admin_role_id 
  INNER JOIN BLC_ADMIN_PERMISSION friendly on rolexref.admin_permission_id = friendly.admin_permission_id 
  LEFT OUTER JOIN BLC_ADMIN_PERMISSION_XREF xref on friendly.admin_permission_id = xref.admin_permission_id
  LEFT OUTER JOIN BLC_ADMIN_PERMISSION child on xref.child_permission_id = child.admin_permission_id
ORDER BY role_description, friendly_description;

Adding EntityPermissions to that query, you can see which Entities are in play for a given Role/Permission. Note that by adding the EntityPermission the Role/Permissions will show as duplicates in the SQL output - that is because a given Permission can be assocaited with more then one EntityPermission

SELECT ar.description role_description, parent.description parent_description, parent.name parent_name, 
parent.is_friendly parent_friendly, parent.permission_type parent_permission_type, 
child.description child_description, child.name child_name, child.is_friendly child_friendly, 
child.permission_type child_perm_type, enty.ceiling_entity entity_permission
FROM BLC_ADMIN_ROLE ar 
  INNER JOIN BLC_ADMIN_ROLE_PERMISSION_XREF rolexref on ar.admin_role_id = rolexref.admin_role_id 
  INNER JOIN BLC_ADMIN_PERMISSION parent on rolexref.admin_permission_id = parent.admin_permission_id 
  LEFT OUTER JOIN BLC_ADMIN_PERMISSION_XREF xref on parent.admin_permission_id = xref.admin_permission_id
  LEFT OUTER JOIN BLC_ADMIN_PERMISSION child on xref.child_permission_id = child.admin_permission_id
  INNER JOIN BLC_ADMIN_PERMISSION_ENTITY enty on child.admin_permission_id = enty.admin_permission_id
ORDER BY role_description, parent_description;

Out of the box Permissions

In lieu of executing the above queries, we have listed below is an example of some of the Friendly Permissions, Child Permissions, and EntityPermission setup out of the box. Each example contains the following structure. Note that this is not an exhaustive list of the Permissions available.

Friendly Permission & Type (View or Manage)
- Permission & Type (Read or All)
  - Entity Permission

Enumeration

[View | Manage] Enumeration
- Enumeration [Read | All]
  - DataDrivenEnumeration
  - DataDrivenEnumerationValue

Translation

[View | Manage] Translation
- Translation [Read | All]
  - Translation

Site Map Generation Configuration

[View | Manage] Site Map Gen Config
- Site Map Gen Config [Read | All]
  - SiteMapGeneratorConfiguration
  - SiteMapURLEntry

Sku

[View | Manage] Sku
- Sku [Read | All]
  - Sku

Currency

[View | Manage] Currency
- Currency [Read | All]
  - BroadleafCurrency

Admin Security

Definitions

Admin User

Role

Permission

Friendly Permissions

Child Permissions

How Permissions Relate To Menu Sections

Permissions and Entities

Permission and Roles

Getting a view of what Permissions are setup

Out of the box Permissions

Menu Section

Category

Product

Product Option

Offer

Page

Asset

Structured Content

Url Redirect

Order

Customer

User

System Property

Search Redirect

Module Configuration

Enumeration

Translation

Site Map Generation Configuration

Sku

Currency