Wednesday, October 19, 2016

UF Dashbuilder - Custom metric displayers

A common feature users usually ask for is the ability to customize the look&feel of their metric displayers. In order to cope with those kind of scenarios, UF Dashbuilder provides an editor which allows for the edition and customization of the metric HTML code. The perspective editor's Displayer Component is in charge of providing such functionality.  In order to start the edition process just drag & drop a Displayer Component from the component sidebar on the right:




Once opened, select the Metric type from the types on the left. The system provides four predefined templates. On the center of the screen, a preview of the metric is shown along with the HTML and Javascript options, both give access to the metric's source code.




From the HTML tab, it is possible to provide a custom template using the HTML language. Some metric related variables can be injected in the template as well just by clicking on the upper right icon and selecting from the list of available variables.  Also both Bootstrap 3 and PatternFly  are supported for CSS styling.




From the Javascript tab users can provide a JS snippet which is executed every time the metric is displayed. Likewise the HTML tab, it is possible to reference some context variables as well as DOM elements from the HTML template. Altogether it allows for the implementation of nice features like for example: changing the color of the metric if its value exceeds a given threshold, apply a custom format to the value, etc.




The next video (do not forget to select HD) shows how to create and customize a new metric using the features described above. Enjoy!


Wednesday, August 24, 2016

UF Dashbuilder - Security Management

The implementation of the security management features in UF Dashbuilder is done (see the related ticket in JIRA). This is a major step towards the full migration of the old Dashbuilder tooling to GWT/Uberfire. The following video is a preview of the new security management screen in the UF Dashbuilder webapp (don't forget to select full HD for a better display).


This article describes how administrator users can manage the application's users, groups and permissions using an intuitive and friendly user interface in order to configure who can access the different resources and features available. The security management capabilities presented exceed by far the ones provided by the old Dashbuilder.

Basic concepts

In order to understand the new security management module, a few core concepts need to be introduced first.

Roles vs Groups


Users can be assigned with more than one role and/or group. It is always mandatory to assign at least one role to the user, otherwise he/she won’t be able to login. Roles are defined at application server level and they are part of the webapp’s web.xml descriptor. On the other hand, groups are a more flexible concept, since they can be defined at runtime.

Permissions


A permission is basically something the user can do within the application. Usually, an action related to a specific resource. For instance:

  • View a perspective
  • Save a project
  • View a repository
  • Delete a dashboard

A permission can be granted or denied and it can be global or resource specific. For instance:

  • Global: “Create new perspectives”
  • Specific: “View the home perspective”

As you can see, a permission is a "resource + action" pair. In the concrete case of a perspective we have: read, update, delete and create as the available actions. That means that there are four possible permissions that could be granted for perspectives.

Permissions do not necessarily need to be tied to a resource. Sometimes it is also necessary to protect access to specific features, like for instance "generate a sales report". That means, permissions can be used not only to protect access to resources but also to custom features within the application.

Authorization policy


The set of permissions assigned to every role and/or group is called the authorization (or security) policy. Every application contains a single security policy which is used every time the system checks a permission.

The authorization policy file is stored in a file called WEB-INF/classes/security-policy.properties under the application's WAR structure.


NOTE: If no policy is defined then the authorization management features are disabled and the application behaves as if all the resources & features were granted by default.

Here is an example of a security policy file:

# Role "admin"
role.admin.permission.perspective.read=true
role.admin.permission.perspective.read.Dashboard=false

# Role "user"
role.user.permission.perspective.read=false
role.user.permission.perspective.read.Home=true
role.user.permission.perspective.read.Dashboard=true

Every entry defines a single permission which is assigned to a role/group. On application start up, the policy file is loaded and stored into memory.

Security provider


A security environment is usually provided by the use of a realm. Realms are used to restrict access to the different application's resources. So realms contains the information about the users, groups, roles, permissions and any other related information.

In most typical scenarios the application's security is delegated to the container's security mechanism, which consumes a given realm at same time. It's important to consider that there exist several realm implementations, for example Wildfly provides a realm based on the application-users.properties/application-roles.properties files, Tomcat provides a realm based on the tomcat-users.xml file, etc.

So there is no single security realm to rely on, it can be different in each installation.

Due to the potential different security environments that have to be supported, the security module provides a well defined API with some default built-in security providers.

A security provider is the formal name given to a concrete user and group management service implementation for a given realm.

The user & group management features available will depend on the security provider configured.
If the built-in providers do not fit with the application's security realm, it is easy to build and register your own provider.


Installation and setup


At the time of this writing, the application provides two pre-installed security providers:

  • Wildfly 10 / EAP 7 - Both distributions use the Wildfly security provider configured for the use of the default realm files application-users.properties and application-roles.properties

Please, read each provider's documentation in order to apply the concrete settings for the target deployment environment.

On the other hand, when either using a custom security provider or using one of the availables, consider the following installation options:

  • Enable the security management feature on an existing WAR distribution
  • Setup and installation in an existing or new project

NOTE: If no security provider is installed, there will be no available user interface for managing the security realm.

Once a security provider is installed and setup, the user and group management features are automatically enabled in the security management UI (see the "Usage" section below).

Enabling user & group management


Given an existing WAR distribution, follow these steps in order to install and enable the user & group management features:

  • Ensure the following libraries are present on WEB-INF/lib:
    • WEB-INF/lib/uberfire-security-management-api-?.jar
    • WEB-INF/lib/uberfire-security-management-backend-?.jar
  • Copy the the security provider library to WEB-INF/lib:
    • e.g: WEB-INF/lib/uberfire-security-management-wildfly-?.jar
    • If the provider requires additional libraries, copy them as well 
  • Replace the whole content of the WEB-INF/classes/security-management.properties file, or if not present, create it. The settings present on this file depend on the concrete implementation used. 
  • If deploying on Wildfly or EAP, check if the WEB-INF/jboss-deployment-structure.xml requires any update.
Please, read each provider's documentation for more information.

Disabling user & group management


The user & groups management features can be disabled, and thus no services or user interface will be available, by means of either:

  • Uninstalling the security provider from the application. When no concrete security provider is installed, the user and group management features will be disabled and no services or user interface will be displayed to the user. 
  • Removing or commenting the security management configuration file. Removing or commenting all the lines in the configuration file located at WEB-INF/classes/security-management.properties is another way to disable the user and group management features.

Usage


The Security Management perspective is available under the Administration section in the top menu bar.


The next screenshot shows how this new perspective looks:



This perspective supports:
  • List all the roles, groups and users available
  • Create & delete users and groups
  • Edit users, assign roles or groups, and change user properties
  • Edit both roles & groups security settings, which include:
    • The home perspective a user will be directed to after login
    • The permissions granted or denied to the different workbench resources and features available

All of the above together provides a complete users and groups management subsystem as well as a permission configuration UI for protecting access to specific resources or features.

The next sections provide a deep insight into all these features.

NOTE: The user and group management related features can be entirely disabled. See the previous section
"Disabling user & group management". If that's the case then both the Groups and Users tabs will remain hidden from the user.

User management


By selecting the Users tab in the left sidebar, the application shows all the users present by default on the application's security realm:

  • Searching for users

In addition to listing all the users, search is also allowed. When specifying the search pattern in the search box the users listed will be reduced to only those that matches the search pattern.


Search patterns depend on the concrete security provider being used by the application.
Please, read each provider's documentation for more information.

  • Creating new users

By clicking on the "New user +" anchor, a form is displayed on the right.

This is a wizard like interface where the application asks for the new user name, a password as well as what roles/groups to assign.

  • Editing a user

After clicking on a user in the left sidebar, the user editor is opened on the screen's right.

For instance, the details screen for the admin user when using the Wildfly security provider looks like the following screenshot:



Same screen but when using the Keycloak security provider looks as:



Note that when using the Keycloak provider, a new user attributes section is displayed, but it's not present when using the Wildfly provider. This is due to the fact that the information and actions available always depend on each provider's capabilities as explained in the "Security provider capabilities" section below.

Next is the type of information handled in the user's details screen:
  • The user name
  • The user's attributes
  • The assigned groups
  • The assigned roles
  • The permissions granted or denied

In order to update or delete an existing user, click on the Edit button present near to the username in the user editor screen:


Once the editor is in edit mode, different operations can be done (provided the security provider supports 
them):

For instance, to modify the set of roles and groups assigned to the user or to change the user's password as well.

  • Permissions summary

The Permissions tab shows a summary of all the permissions assigned to this particular user. This is a very helpful view as it allows administrator users to verify if a target user has the right permission levels according to the security settings of its roles and groups.

Further details about how to assign permissions to roles and groups are in the "Security Settings Editor" section below.

  • Updating the user's attributes

User attributes can added or deleted using the actions available in the attributes table:


  • Updating assigned groups

From the Groups tab, a group selection popup is presented when clicking on the "Add to groups" button:




This popup screen allows the user to search and select or deselect the groups assigned to the user.

  • Updating assigned roles

From the Roles tab, a role selection popup is presented when clicking on "Add to roles" button:



This popup screen allows the user to search and select or deselect the roles assigned to the user.

  • Changing the user's password

A change password popup screen is presented when clicking on the "Change password" button:


  • Deleting users

The user currently being edited can be deleted from the realm by clicking on the "Delete" button.



Security provider capabilities


Each security realm can provide support for different operations. For example, consider the use of a Wildfly's realm based on properties files. The contents for the applications-users.properties is like:

admin=207b6e0cc556d7084b5e2db7d822555c
katy=fd37b5d0b82ce027bfad677a54fbccee
john=afda4373c6021f3f5841cd6c0a027244
guest=b5d048a237bfd2874b6928e1f37ee15e


Notice that it's based on key-value pairs where the key is the user name, and the value is the hashed value for the user's password. So a user is just represented by a key and its user name, it does not have a name nor an address or any other meta information.

On the other hand, consider the use of a realm provided by a Keycloak server. The user information is composed by more meta-data, such as the surname, address, etc, as in the following image:


So the different services and client side components from the User and Group Management API are based on capabilities which are used to expose or restrict the available functionality provided by the different services and client side components. Examples of capabilities are:

  • Create a user
  • Update a user
  • Delete a user
  • Update user's attributes
  • Create a group
  • Update a group
  • Assign groups to a user
  • Assign roles to a user

Each security provider must specify a set of capabilities supported. From the previous examples, it is noted that the Wildfly security provider does not support the attributes management capability - the user is only composed by the user name. On the other hand the Keycloak provider does support this capability.

The different views and user interface components rely on the capabilities supported by each provider, so if a capability is not supported by the provider in use, the UI does not provide the views for the management of that capability. As an example, consider that a concrete provider does not support deleting users - the delete user button on the user interface will be not available.

Please take a look at the concrete service provider documentation to check all the supported capabilities for each one, the default ones can be found here.

Group management


By selecting the Groups tab in the left sidebar, the application shows all the groups present by default on the application's security realm:

  • Searching for groups

In addition to listing all the groups, search is also allowed. When specifying the search pattern in the search box the groups listed will be reduced to only those that matches the search pattern.

Search patterns depend on the concrete security provider being used by the application.

Please, read each provider's documentation for more information.

  • Creating new groups

By clicking on the "New group +" anchor, a new screen will be presented on the center panel to perform a new group creation.

After typing a name and clicking Save, the next step is to assign users to it:


Clicking on the "Add selected users" button finishes the group creation.
  • Modifying a group
After clicking on a group in the left sidebar, the security settings editor for the selected group instance is opened on the screen's right. Further details at the "Security Settings Editor" section below.

  • Deleting groups
To delete an existing group just click on the Delete button.

Role management


By selecting the Roles tab in the left sidebar, the application shows all the application roles:


Unlike users and groups, roles can not be created nor deleted as they come from the application's web.xml descriptor. After clicking on a role in the left sidebar, the role editor is opened on the right, which is exactly the same security settings editor used for groups. Further details at the "Security Settings Editor" section.



That means both role and group based permissions can be defined. The main difference between roles and group are:
  • Roles are an application defined resource. They are defined as <security-role> entries in the application's web.xml descriptor.
  • Groups are dynamic and can be defined at runtime. The installed security provider determines where groups instances are stored.

They can be used together without any trouble. Groups are recommended though as they are a more flexible than roles.

  • Searching for roles

In addition to listing all the roles, search is also allowed. When specifying the search pattern in the search box the roles listed will be reduced to only those that matches the search pattern.


Search patterns depend on the concrete security provider being used by the application.

Please, read each provider's documentation for more information.


Security Settings Editor


This editor is used to set several security settings for both roles and groups.

Home perspective


This is the perspective where the user is directed after login. This makes it possible to have different home pages for different users, since users can be assigned to
different roles or groups.

Priority


It is used to determine what settings (home perspective, permissions, ...) have precedence for those users with more that one role or group assigned.

Without this setting, it won't be possible to determine what role/group should take precedence. For instance, an administrative role has higher priority than a non-administrative one. For users with both administrative and non-administrative roles granted, administrative privileges will always win, provided the administrative role's priority is greater than the other.

Permissions


Currently, only perspective permissions are supported in the UI. If access to a perspective is denied then it will not be shown in any of application menus. Update, Delete and Create permissions change the behaviour of the perspective management plugin editor.

For perspectives,  it is possible to define global permissions and add single instance exceptions afterwards. For instance, Read access can be granted to all the perspectives and deny access just to an individual perspective. This is called the grant all deny a few strategy.


The opposite, deny all grant a few strategy is also supported:


NOTE: In the example above, the Update and Delete permissions are disabled as it does not makes sense to define such permissions if the user is not even able to read perspectives.


Security Policy Storage


The security policy is stored under the workbench’s VFS. Most concrete, in a GIT repo called “security”.
The ACL table is stored in a file called “security-policy.properties” under the “authz” directory. Next is an example of the entries this file contains:

role.admin.home=HomePerspective
role.admin.priority=0
role.admin.permission.perspective.read=true
role.admin.permission.perspective.create=true
role.admin.permission.perspective.delete=true
role.admin.permission.perspective.update=true


Every time the ACL is modified from the security settings UI the changes are stored into the GIT repo.

Initially, when the application is deployed for the first time there is no security policy stored in GIT. However, the application might need to set-up a default policy with the different access profiles for each of the application roles.

In order to support default policies the system allows for declaring a security policy as part of the webapp’s content. This can be done just by placing a security-policy.properties file under the webapp’s resource classpath (the WEB-INF/classes directory inside the WAR archive is a valid one). On app start-up the following steps are executed:

  • Check if an active policy is already stored in GIT
  • If not, then check if a policy has been defined under the webapp’s classpath
  • If found, such policy is stored under GIT

The above is an auto-deploy mechanism which is used in the workbench to set-up its default security policy.

One slight variation of the deployment process is the ability to split the “security-policy.properties” file into small pieces so that it is possible, for example, to define one file per role. The split files must start by the “security-module-” prefix, for instance: “security-module-admin.properties”. The deployment mechanism will read and deploy both the "security-policy.properties" and all the optional “security-module-?.properties” found on the classpath.

Notice, despite using the split approach, the “security-policy.properties” must always be present as it is used as a marker file by the security subsystem in order to locate the other policy files. This split mechanism allows for a better organization of the whole security policy.

Authorization API


Uberfire provides a complete API around permissions. The AuthorizationManager is the main interface for checking if permissions are granted to users.
@Inject
AuthorizationManager authzManager;

Perspective perpsective1;
User user;
...
boolean result = authzManager.authorize(perspective1, user);
Using the fluent API can also be expressed as:

authorizationManager.check(perspective1, user)
    .granted(() -> ...)
    .denied(() -> ...); 

The security check calls always use the permissions defined in the security policy.

For those interested in those APIs, an entire chapter can be found in the Uberfire's documentation.

Summary


The features described above bring even more flexibility to Dashbuilder. Users and groups can be created right from the UI, new assets like perspectives can be authored (the new Perspective editor is about to be released :-) ) and, finally, permissions on perspectives can be granted or denied.

In the future, along with the improvement of the authoring capabilities, more permission types will be added. The ultimate goal is to deliver a zero/low code, very flexible and customizable tooling which allows to develop, build and deploy business dashboards in the cloud.

UF Dasbuilder is close to its 1.0 release. Only a few major features like the filter controls or the perspective builder are still in progress. The next article will introduce the perspective builder which is the main component used for dashboard design. Stay tuned!


Friday, July 1, 2016

UF Dashbuilder - Upgraded support for Elastic Search 2.x

The Dashbuilder's Elastic Search Data Provider support has been upgraded to the latest Elastic version, so you can now create your dashboards consuming both Elastic Search 1.x or 2.x.


Now it is extremely easy to create your own data sets, data visualizations and dashboards from data located in any Elastic Search node. Just give it a try!

Please, take a look at the Elastic Search Data provider documentation and also consider following this quick start guide which provides some examples and it will teach you how to create a simple showcase environment in just minutes.

Elastic Search data set authoring

Getting into more technical details, this upgrade implies a complete internal refactoring of the connector and the endpoint consumer. This is due to the upgrade to Java 8 in current Dashbuilder version in master, which allows to get rid of the Jest client used to connect to the Elastic Search node and use the native Elastic's Java client instead. A lot of marshalling/parsing code has been removed and all the remote service communication is now delegated to the Elastic's client itself, which makes Dashbuilder's code cleaner and easy to manipulate and extend according your needs.