Unblu 4.1

Advanced Authorization

1. Introduction

Unblu by default uses implicit authorization policies for authorizing users. Implicit policies are rather coarse-grained and basically only distinguish three roles (WEBUSER, REGISTERED_USER and SUPER_ADMIN). Based on these roles unblu decides whether a certain action is permitted or not.

For advanced authorization requirements, unblu supports fine grained control over user permissions using custom authorization policies.

2. Unblu Authorization Model

Unblu uses a role based access control ( based authorization model built on operations, permissions, roles and users. This means that for all operations that support authrization, unblu defines a permission that the user must have in order to perform the operation. Permissions are then assigned to users or roles based on a policy. This model is very flexible because the distribution of permissions to users (based on user and roles for instance) can be changed independently without changing the unblu product implementation. Unblu does not check if the user has a certain role but if the user has a certain permission.

By default unblu uses an internal policy that assigns permissions based on a set of standard roles (WEBUSER, REGISTERED_USER and SUPER_ADMIN).

3. Default policy

In short the default policy assigns permissions in a way that users with the WEBUSER role can act as a visitor (end user using the collaboration features of unblu), users with the REGISTERED_USER role can act as an agent (authenticated user using the collaboration features of unblu, representative of the company) and users with the SUPER_ADMIN role can perform administrative operations.

If the integration does not manage user role assignment explicitly, then the the WEBUSER, REGISTERED_USER and SUPER_ADMIN roles are assigned based on System Entry Path Concept. Requests that enter the system via the "/unblu/" entry path get the REGISTERE_USER role assigned, requests that enter via "/co-unblu/" get the REGISTERED_USER role assigned and requests that enter trough "/sys-unblu" get the SUPER_ADMIN role assigned.

4. Using custom policies

Because writing a custom authorization policy from scratch would include redefining the assignment of all existing required permissions using custom rules and because this would require the author of a policy to know about all permissions unblu internally requires in order to work properly, unblu supports selective changing the default policy instead of writing a completely new policy.

Using a custom policy involves the following steps:

  1. Disable the default policy for the permissions that will be covered by the custom policy
  2. Provide a permission overlay (external policy) that assigns permissions based on user and roles according to the required policy

The permission overlay file path (or url) is configured using the "com.unblu.authz.permissionOverlay" configuration setting.

Permission overlay support dynamic reconfiguration (Advanced Unblu Server Configuration#Dynamicreconfiguration), everytime dynamic reconfiguration takes place, permission overlays are also reloaded.

5. Permission overlay file format

Permission overlays (external policies) are defined in an xml based file format.

The permission overlay file has the following general format

<?xml version="1.0" encoding="UTF-8"?>

	<role name="ROLE1">
	<role name="ROLE2">

	<user id="abcde">

The xml file must be a valid xml file starting with a <?xml version="1.0" encoding="<character-encoding>"?> line. We recommend using UTF-8 (like in the sample above) but all other character encodings supported by the java virtual machine in use are also supported.

The document element MUST be named "permissionOverlay".

The document element can contain any number of "user" and "role" elements, every "user" or "role" element must be unique within the file (based on the "name" attribute for "roles" elements and based on the "id" attribute for "user" elements).

Every "user" or "role" element MUST contain exactly one "permissions" element.

The "permissions" element CAN contain any number of PERMISSION elements.

Permission elements must be valid permissions as described separately (example permission element: <coBrowseDomain origin=""/>)

Permission elements MUST be unique within the "permissions" element, equality is defined separately per permission type.