Security policy rule

Introduction

We already know about how to use the Access rule to control user access to worker sites, pages, and widgets. However, the result of the Access rule is a boolean value (true/false), which is not enough to control user access to data. For example, we may want to control user access to data based on the user's department or other criteria. In such cases, we need to use the Security policy rule.

The Security policy rule provides more flexibility to control user access with the following features:

Support for inheritance: The children's security policy must be inherited from the parent security policy.
The children can override the parent security policy.
The security policy can be applied to many types of resources.

Rule syntax

Keywords

You can use the following keywords to work with Security policy rules:

Name	Type	Description
@user	DslUser	The user in context.
@apiFactory	IManagedApiFactory	To construct Casewhere API objects. Read here for the full list of available APIs.
@parameter	dynamic	Dictionary of parameter objects passed into the rule for verifying context.
@parentAccessMode	AccessMode?	The security policy rule of parent resource.

A DslUser object has the following properties:

Name	Type	Description
UserId	string	The ID of the user.
Username	string	The username used for login.
Has	bool (string claimType)	A method used to determine if the user has a claim or not.
Contains	bool (string claimType, string value)	A method used to determine if the user has a claim value or not.
WorkerSite	DslWorkerSite	The worker site in context.

A DslWorkerSite object has the following properties:

Name	Type	Description
Name	string	The name of the worker site. Worker site names must be unique.
DomainName	string	The domain of the worker site.
TimezoneId	string	The standard name of the timezone object retrieved from TimeZoneInfo.GetSystemTimeZones. For example, "Romance Standard Time".
TimezoneOffset	double	A number indicating the time difference in minutes between the current time zone's standard time and Coordinated Universal Time (UTC).
ShortDate	string	The short date format. For example: "dd.MM.yyyy".
LongDate	string	The long date format. For example: "dd.MM.yyyy HH:mm".
DecimalSeparator	string	The decimal separator. It could be "," or "." depending on the configuration.
ThousandSeparator	string	The thousand separator. It could be "," or "." depending on the configuration.

In Security policy rules, we can return these access modes:

Name	Type	Description
Read	string	The user can read the resource.
Write	string	The user can read and write the resource.
Deny	string	The user cannot access to the resource

Compatibility and effect

Access rule	Security policy rule	Context	Description
true	AccessMode.Read/Write	Pages	Show on UI
false	AccessMode.Deny	Pages	Un-authorized error
true	AccessMode.Read/Write	Widget	Show on UI
false	AccessMode.Deny	Widget	Hide on UI
true	AccessMode.Write	Widget Action	Show UI and executable
	AccessMode.Read	Widget Action	Show UI and non-executable
false	AccessMode.Deny	Widget Action	Hide on UI

Examples

Example 1

Role-based access control – Only users having a specific role can access the resource.

Single line

@user.Contains("Roles", "admin") ? AccessMode.Write : AccessMode.Read;

Multi-line

#predicate
if (@user.Contains("Roles", "admin"))
{
	return AccessMode.Write;
}
// other logic
return AccessMode.Read;

Example 2

Only whitelisted users can access the resource.

#predicate
 
var dataApi = @apiFactory.Get<IDataApi>();
var filter = FilterBuilder.Create().Eq("Username", @user.Username).Eq("Active", true).Build();
var found = dataApi.Any("WhitelistedUsers", filter);
 
return found ? AccessMode.Read : AccessMode.Deny;

Example 3

Read input parameter via @parameters variable to verify users can access the resource.

#predicate

if (!@parameters.Has("UserName")) 
{
	return AccessMode.Deny;
}

var dataApi = @apiFactory.Get<IDataApi>();
var userName = @parameter["UserName"];
var filter = FilterBuilder.Create().Eq("Username", username).Eq("Active", true).Build();
var found = dataApi.Any("WhitelistedUsers", filter);
 
return found ? AccessMode.Read : AccessMode.Deny;

Example 4

Access the security policy rule result of parent resource via @parentAccessMode variable.

#predicate

if (@parentAccessMode != null && @parentAccessMode == AccessMode.Deny) 
{
	// if parent access mode is Deny, the child will be denied access to the resource.
	return AccessMode.Deny;
}

// handle other logic
// ...
return AccessMode.Read;

How to apply Security policy rules

To apply Security policy rules for Pages, Widgets and Widgets actions, you can go to Security tab in the Edit resource panel.

Apply Security policy rule

If you allow "Can inherit from parent", the children resources will inherit the parent security policy. The children resources can override the parent security policy if necessary.
You can Add new rule or Select multiple rules from the list. The rules will be combined by the logical operator AND including the result of the parent security policy if inherited.
- If any of the rules returns Deny, the user will be denied access to the resource.
- If none of the rules assign to the resource, the resource will have Write access mode.

Page

Use the security policy rule is not only to control access to the page but also to control how the page's widgets and widget actions show on UI and can be executable or not. The page's security policy rule will be applied to all widgets and widget actions on the page.

Example

A security policy rule sample to control the user can read, write or deny access to the page.

#predicate

if (@user.Contains("Roles", "Admin") ||
	@user.Contains("Roles", "Manager")) 
{
	return AccessMode.Write;
}

if (@user.Has("Roles", "User")) 
{
	return AccessMode.Read;
}

return AccessMode.Deny;

You can also access to Access Mode of Page at client site via Page script or events. This way allow you can customize the UI logic base of that access mode.

$scope.accessMode
// "Read"

Access Access mode of Page at client side

Using the security policy rule for Widgets or Widget actions is similar to using it for Pages. The widget's security policy rule will be applied to all widget actions on the widget.

It is more flexible to control the widget's security policy rule by using the widget's context. For example, you can control the use can view or do edit/delete Widget actions base on the Access mode of the Widget.

To access the widget's access mode at client side, you can use the Page events and read it from


// Access mode of Widget
$scope.widgetApis['widget-name'].getAccessMode()
// or
$scope.widgets['widget-name'].accessMode
// "Read"

// Access mode of Widget action
$scope.widgets['widget-name'].actions[0].accessMode
// "Write"