Customizing the Permission Model

To allow greater flexibility and to customize the permissions according to the organizations requirements, the ES Permission Model allows extension developers to override existing permissions and create new permissions.

This section explains how to customize a permission model. It is important to identify the points of the permission model that are extensible and replaceable and the permission context, which provides useful properties and utility methods required for working with the permission model.

Extension points

The extension points of the permission model are as follows:

The tenantLoad method of the permission.js script.
This script can be bundled inside an app extension or an asset extension and the permission overriding behaviour varies as follows:
- If the permission script is bundled in an asset extension, it will override the existing permissions and add the permissions that are defined newly to a single asset type.
- If the permission script is bundled in an app extension, it will override the asset specific and app specific permissions.
The configureRegistryPermissions callback in the asset.configure method, which is found in the asset.js file allows permissions and roles to be configured on a per asset type basis.

Permission Context

The permission context consists of a set of properties and utility methods that are provided whenever a permission method, such as dynamic permission, tenantLoad method or configureRegistryPermissions method is executed.

Properties

The following properties are defined when a permission method is executed:

Name	Description
username	The current user’s username.
type	The asset type. The asset type is only present if the context is created for evaluating an asset specific permission.
userManager	An instance of the User Manager for the tenant who is currently logged into ES.
tenantId	The tenant ID of the tenant who is currently logged into ES. You can use the carbon module to resolve the domain given by the tenantId.
systemRegistry	An instance of the system registry for the tenant who is currently logged into ES.
rxtManager	An instance of the rxtManager for the tenant who is currently logged into ES.
serverConfigs	An instance of the server configuration object. It contains the contents of the `publisher.json` or `store.json` found in the configuration registry.
permissions	The permissions map Any permission added to this map is automatically created in the WSO2 permission tree.

Utility Methods

This section provides a set of utility methods that can be accessed using the ctx.utils property.

All the permissions can also be accessed using the rxt module as follows:

var permissionAPI = require(‘rxt’).permissions;
permissionAPI.registerPermissions(permissions);

The namespace of the rxt module has the registry actions mapped to a set of named properties.

Name	Description
`registerPermissions`	Creates the provided permissions in the WSO2 permission tree.
`assetFeaturePermissionString`	Generates a permission string for an asset permission.
`appFeaturePermissionString`	Generates a permission string for an application permission.
`addPermissionToRole`	Accepts a permission map and assigns the provided permission to a given role.
`addRole`	Checks if the respective role exists in the system, if it does not exist adds the new role.
`assetFeaturePermissionKey`	Generates an asset specific permission key.
`appFeaturePermissionKey`	Generates an app specific permission key.
`anonRole`	Returns the anonymous role. The default anon role is mapped to `es.store.anon.user`
`authorizeActionsForEveryone`	Assigns the provided registry actions to a given resource for the Internal/everyone role. The registry action can be assigned to a user role or for a resource path. The available registry actions are as follows: `+get` `+write` `+delete` `+authorize`
`authorizeActionsForRole`	Assigns the provided registry actions to a given a resource for the provided role. The registry action can be assigned to a user role or for a resource path. The available registry actions are as follows: `+get` `+write` `+delete` `+authorize`
`denyActionsForEveryone`	Removes the provided registry actions for the Internal/everyone role. The registry action can be assigned to a user role or for a resource path. The available registry actions are as follows: `+get` `+write` `+delete` `+authorize`
`denyActionsForRole`	Removes the registry actions defined for the provided user role. The registry action can be assigned to a user role or for a resource path. The available registry actions are as follows: `+get` `+write` `+delete` `+authorize`
`governanceRooted`	Returns the governance registry rooted path for a given a registry path.

Adding new permissions

New permissions can be added by registering the permission against a key in the respective permission object.

Follow the guidelines given below when adding new permissions:

When adding a new permission the permissions map must start with the /permissions root as shown in the examples below.
It is recommended that extension developers make use of the assetFeaturePermissionString and appFeaturePermissionString to generate their custom permissions.
These methods will generate a permission string that is aligned with the existing permission string conventions.

Example:

 var tenantLoad = function(ctx) {
	var Permissions = ctx.permissions;
	Permissions.GADGET_ASSET_CREATE = ‘/permissions/gadget/add’;
	//Recommened method of generating a permission string
	Permissions.GADGET_MYPERMISSION = ctx.
    utils.assetFeaturePermissionString(‘mypermission’,’gadget’);
}

Remapping permissions

Existing permissions can be remapped to a new static permission or dynamic permission. This is done by assigning a value to the permissions map, which is passed in with the context to the tenantLoad method as shown in the below example:

Example:

var tenantLoad = function(ctx) {
	var Permissions = ctx.permissions;
	//Mapping to a static permission
	Permissions.ASSET_CREATE = ‘/permissions/site/add’;
	//Mapping to a dynamic permission
	Permissions.ASSET_CREATE = function(ctx) {
		return ‘/permissions/’+ctx.type+’/mynewpermission’;
	};
}