Security

Security in EPiServer Commerce is a system which uses the Role Based Security principle. It is implemented using the Business Foundation Module architecture. The fundamental concept in Role Based Security is that privileges are assigned to defined categories of users (known as roles) rather than to individual users. When a user is assigned to one of these roles, he or she is assigned the set of privileges associated with that role. A user who is not assigned to a role does not have any privileges.

These are the basic functions that the security system performs:

• User authorization to allow certain actions
• Manage user roles
• Assign users to roles

The security model has these main components:

• User - the main party security system, the object for which you perform all the operations associated with the authorization.
• Role - definition of roles (permission level) is a list of rights associated with a role. Right is a system action under user control. For example, user with CatalogViewer role has rights to view catalogues and items within them. All user permissions are managed with roles. Role definition is a collection of rights related with a certain object.
• Security Scope - used to narrow the permission area as defined by the object. Note that the Scope column gets its value set when the role for a particular contact is confined to an organization. This is true whether the role is pre-defined or customized.
• Role assignment - is a relation between role, principals and security scopes. This is the object that is used for user authorization.

Refer also to the Security section in the EPiServer CMS SDK for more information about security features in the EPiServer platform.

Security user

The main participant in the system security is the ASP.NET MembershipUser.

Security roles

User roles in the Security system are nothing more than a named container for a list of rights. To work with the user roles use the methods provided by the IRoleManagement interface and the SecurityRole and SecurityPermission classes located under the Mediachase.Commerce.Security namespace.

Available actions for user roles

• Create a new role
• Edit an existing role
• Remove a role

To create a new role, first define the list of permissions. Then call a method IRoleManagement.CreateRole (string roleName, IEnumerable SecurityPermission permissions) passing name of the role (roleName parameter) and a list of permission rights.

// Create new role
var permissions = new string [] ("read", "write", "delete", 
"admin"). Select (x => new SecurityPermission (x)); 
SecurityRoleManagerProvider.CreateRole ("MyNewRole", permissions);

// Change the current user role
    SecurityRole role = 
    SecurityRoleManagerProvider.GetRoleByName ("MyNewRole"); role.Permissions = new 
    SecurityPermission [] (new SecurityPermission ("newPermission")); 
    SecurityRoleManagerProvider.UpdateRole (role);

// Remove an existing role
SecurityRoleManagerProvider.DeleteRole("MyNewRole");

Security role assignment

There are two types of user role assignments:

• Global assignment (Role Based Security)
• Object based assignment (Object Based Security)

Global assignment means that a given user has a role for any object in the system. Object based assignment - means that the user has a role only for a certain number of objects in the system related to the object (example: the user has an Admin role only in a given organization). Working with role assignments is accomplished by calling methods in the IRoleManagement interface.

Working with global assignments

To assign a user to a role which has global scope (role based security), you need to call IRoleManagement.AddUserToRole(MemebershipUser user, SecurityRole role):

// Create the appointment to the role of having a global domain
SecurityRole role = SecurityRoleManagerProvider.GetRoleByName("MyNewRole");
MembershipUser user = Membership.GetUser();
SecurityRoleManagerProvider.AddUserToRole(user, role);

For a list of all user assignments to roles with a global domain call a method IRoleManagement.GetAllUserRoles(MemebershipUser user, object scope) passing NULL as the parameter scope:

 MembershipUser user = Membership.GetUser ();
var globalRoles = SecurityRoleManagerProvider.GetAllUserRoles (user, null);

For a list of all assignments for the specified user, call IRoleManagement.GetAllUserRoles(MembershipUser user) which will return a list of all roles of the user (including global and object roles):

 SecurityRole role = SecurityRoleManagerProvider.GetRoleByName ("MyNewRole");
var globalRoles = SecurityRoleManagerProvider.GetAllUserRoles (user);

To delete an assignment call IRoleManagement.RemoveUserFromRole(MembershipUser user, SecurityRole role, object scope) passing NULL as the parameter scope:

 SecurityRole role = SecurityRoleManagerProvider.GetRoleByName ("MyNewRole");
MembershipUser user = Membership.GetUser ();
SecurityRoleManagerProvider. RemoveUserFromRole (user, role, null);

Working with object assignments

Working with object assignments (object based security) slightly differs from working with global assignments (role based security) since the additional "object" parameter has to be taken into account. For example, to assign a user to a limited role specific to an organization, use the following code:

 SecurityRole role = SecurityRoleManagerProvider.GetRoleByName("MyNewRole");
MembershipUser user = Membership.GetUser ();
Organization org = new Organization ("myOrg");
SecurityRoleManagerProvider.AddUserToRole (user, role, org);

User authentication

The Security system provides you with a security model that protects data integrity and privacy and supports efficient data access and collaboration. The Security system model is designed to support recommended security best practices. The goals of the model are as follows:

• To provide users with access only to the appropriate levels of information required to do their jobs.
• To categorize types of users in order to define roles and restrict access based on those roles.
• To support data sharing, so that users can be granted access to objects that they do not own for a specified collaborative effort.
• To prevent a user access to objects the user does not own or share.

The first two goals relate to role based security and the last two goals relate to object-based security.

Checking user rights

To check whether the user has a specific right use the ISecurtyCheck interface.

bool CheckPermission(MembershipUser user, string permission, IEnumerable <object> checkParams)

Checks eligibility of a given user without referencing an object:

• user - the user for which we want to check rights
• permission - name of the permission to verify
• checkParams - additional options

bool CheckPermission (MembershipUser user, string permission, object scope, IEnumerable <object> checkParams)

Checks eligibility of a given user over the specified object:

• user - the user for which rights are checked
• permission - name of the permission to verify
• scope - the object for which you are checking the rights
• checkParams - additional options

/ / Example of checking the user rights to view the object order
MembershipUser user = Membership.GetUser ();
PurchaseOrder order = OrderContext.Current.GetOrderById (1);
Bool userCanViewOrder = SecurityCheckProvider.CheckPermission (user, "order: view", order, null);

Security model integration details

In the Security module, all the functionality is based on two interfaces. These interfaces provide a comprehensive set of methods for dealing with security.

• ISecurityCheck - represents a set of operations regarding user authorization.
• IRoleManagement - represents a set of operations to manage user roles and assignments.

SecurityContext and model providers

Just like any other system in EPiServer Commerce, you will work with a system using a static class called SecurityContext.

An example of how to use a SecurityContext class:

// Query whether the current user the right to «asset: mng: view»
   SecurityContext.Current.CheckPermissionForCurentUser ("asset: mng: view")

SecurityContext uses the ISecurityCheck and IRoleManagement interfaces. The classes that implement these interfaces are specified in ecf.security.config. The concrete implementation is done inside the CustomerSecurityProvider class. It uses SQL Database to store security objects (roles & permissions). It also provides data caching to improve scalability and performance.

Rights inheritance

In EPiServer Commerce, "Organization" is used as target of object based assignments (object security role), which ("Organization") can then be related with other objects and form a tree like structures. This organization trees can then be used to calculate user rights. This functionality is called inheritance rights.

If the user has a role in the particular organization "Organization", it means that the user has the same role in other organizations "Org1" and "Org2" which are affiliated to the organization "Organization". The inheritance is determined when the user is assigned a role within an organization.

The system defines the following ways to perform role inheritance:

• Inheritance is allowed on all child objects
• Inheritance is prohibited on all child objects
• Inheritance and the assignment is prohibited by both the current object and all child objects (used to interrupt the chain of inheritance)

Working with business rules

It is possible to create custom business objects in EPiServer Commerce. To view and edit these business object we use the standard interfaces: List, View, and Edit. In order to be able to use security system for such objects, the framework automatically creates permissions for such operation. These permissions are available in the Role Edit dialog under the Business Foundation section.

All permissions for the business objects have a format "businessfoundation: class_name: action: permission" where:

• class_name - the name of the business object
• action - one of the standard values action over the business object (View, List, Edit, Delete)

ecf.security.config

The security module settings are contained in a single file ecf.security.config located in the Configs folder. Refer to the Configuration section for more information.

See also

• Additional topics in the Security section in the EPiServer Commerce SDK
• The Security section in the EPiServer CMS SDK