Authentication and Authorization in LiveView Web (How to Share Resources)

Table of Contents

• Overview
• Best Practices and Recommended Approach

Overview

The authentication and authorization functionality of Spotfire LiveView™ Web was revised as of release 1.1.1.  To take advantage of the latest features, you must place a 1.1.1 version of the lvweb.war file into your LiveView Web project's lv-user-webapps folder in StreamBase Studio. By enabling LiveView Web authentication and authorization, LiveView Web administrators can restrict or enable user access to resources, by dashboard, page, or card with very fine-grained control.

The discussion in this topic, authentication and authorization in LiveView Web, only applies when the underlying Live Datamart project is itself configured to use authorization.  That is, to use authorization features for LiveView Web access, you must start with a Live Datamart project that is also configured for authentication and authorization.

Live Datamart supports two security realms:

• Properties File: Users, passwords, roles, and permissions are configured in a ... properties file, liveview.auth.properties, located in your LiveView project's top-level directory
• Active Directory Server:  Users and roles (groups) are retrieved from an Active Directory server, while the mapping of roles to LiveView permissions is retrieved from liveview.auth.properties.

For the purpose of this article, we will use Live Datamart's file-based authentication option (not Active Directory).

Live Datamart authentication and authorization controls access to the Live Datamart server from any client, including Spotfire LiveView™ Desktop, LiveView Web, the lv-client command-line utility, and custom applications you have written using the LiveView Client APIs for Java, .NET, or JavaScript.

By contrast, LiveView Web provides another layer of authentication and authorization that controls access and authorization only for LiveView Web users. LiveView Web authentication and authorization works alongside the project's underlying Live Datamart authentication, and builds on it with its own, separate authorization realm.

The user is authenticated via an entry in the liveview.auth.properties file - this allows initial entry or rejection into the LiveView Web project.  Then, subsequent access to a given resource in the project (a page, a card, or a link between charts) is authorized via the LiveView Web realm.  Without any authentication on the LiveView project, anyone can access ANY resource in a running project. 

IT SHOULD ALSO BE NOTED - if your project contains any LiveView adapter, you must configure the project to supply credentials so that the adapters can authenticate with the server.  For more details on this particular nuance, please see the attached sbd-common.sbconf file for a sample, or contact support.

Best Practices and Recommended Approach

Regardless of whether you choose the file or Active Directory realm for your Live Datamart authentication, we recommend that you NOT have a well known login configured with superuser permissions.  Many times, users authenticate a Live Datamart project by assigning to user "admin" the password "admin" and the role of LVAdmin.  The LVAdmin role is defined by default with superuser (*) permissions.

This practice IS HIGHLY DISCOURAGED when authenticating a Live Datamart project to be used with LiveView Web. The superuser permission designated with a single asterisk is a special condition in LiveView Web.  This superuser role grants open access permissions to every LiveView Web resource available (all dashboards, pages, cards and links between cards).  We believe it is highly unlikely that a system would want to assign such wide-ranging permissions to any real-world user.  In the worst case scenario, someone could log into the system with the well-known authentication pair (admin/admin) and then delete or overwrite a large amount of work done by someone else. Thus, for LiveView Web, we are naming the superuser role with "*" permissions as an anti-pattern. 

Instead, we recommend the use of a system property to name a privileged user other than "admin" and to explicitly grant this privileged user limited bootstrap permissions. The privileged user should be not a common or well-known login name. This user will have full access to all resources to allow the initial creation of dashboards and other resources. The steps below show how to set up a privileged user named "rockstar" and show the recommended set of bootstrap permissions for a LiveView Web privileged user.

Let's look at how to accomplish the recommended pattern.

OVERVIEW OF STEPS REQUIRED

1. Ensure no easy access to all privileges
2. Add a non-standard privileged user
3. Examine and identify resources available in a project
4. Create a permissions file to enable access to some resources
5. Grant permissions from step 4 to a named user

Given a liveview.auth.properties file with the following users and assigned roles:

• User lvmanager / LVAdmin
• User lvintern / LVInternal - NO dashboard permissions
• User lvguest / LVuser - read only - will see new/empty dashboard
• User bizuser / LVuser - read only - will see new/empty dashboard

The file with the above set of users and roles is attached for reference or reuse.  Note there is no admin/admin user, nor any role with "*" as the granted permission level.  Rather, the LVAdmin role is defined with what we referred to above as "boostrap permissions" for the LiveView Web resources:

 role.LVAdmin = connect:*, shutdown:*, table:*, tuple:*, alert:*, alertaction:*, workspace:*, session:*, query:*, publisher:*, dashboard:create, page:create, card:create,  linkage:create

NOTE: depending on your browser, you may or may not see a scroll bar immediately above.  The line of text to enable priviledges is long and scrolls to the right.  In particular, the LiveView Web priviledges for the "bootstrap permissions" to be added to the Live Datamart priviledges are:

 dashboard:create, page:create, card:create, linkage:create

The next step of our best practices is to have one user who will be the equivalent of root or superuser within LiveView Web.  We will need to add this user into the liveview.auth.properties file so the user name is known AND then grant that named user the privileged user status.  It is important to note, the privileged user status is assigned via a property in sbd.sbconf or sbd-common.sbconf and it overrides the role assigned to the user in the liveview.auth.properties file.  In the defined role in the liveview.auth.properties file we will NOT give full permissions.  In this way, if someone were to replicate the role, or assign the role to another user, that user would NOT have full permissions.  This is the desired behavior.  We wish to limit the number of users who have full access to all the resources on the project.  Let's add our privileged user before we grant any other access to any other user.

To do this, we add to the liveview.auth.properties file a user named "rockstar" and we give that user the role of LVUser.  The user name must be in the liveview.auth.properties file before being named as a privileged user.  Once named a privileged user, the assigned role will then be overridden.  In the liveview.auth.properties file, add:

•  user.rockstar=rockstar,LVUser

   

To add the privileged user property, open your sbd.sbconf, or sbd-common.sbconf file and add the property for the named user

 <sysproperty name="liveview.web.privileged.principals" value="rockstar"/>

The value can be a comma delimited list.  A sample sbd-common.sbconf file is attached to this wiki page for reference or reuse.  (The attached sbconf also contains syntax to support authentication for LiveView adapters, which is a separate issue.)

As a privileged user, the rockstar user has full access to all resources in the Live Datamart project and when accessing the server through LiveView Web.

The next step is to examine and identify resources available in the project via the command line utilities available in v1.1.1 of LiveView Web.  See the documentation file LiveViewWeb_Authorization.pdf that accompanies the 1.1.1 release for the basics on running these commands.

To list the resources in the project, run the command:

lvweb-list -c

This command shows all resources including the ID for each resource.  We need to know the resource ID of a given resource to grant permissions to it.

• On Windows, open a StreamBase Command Prompt. On MacOS, open a Terminal that has been configured with the sb-config --env command, as described in the StreamBase Installation Guide.
• At this time, the utilities only operate from their shipped directory.  As such, you need to navigate to the bin subdirectory of your LiveView Web installation directory.  For example:  
  •  cd c:\TIBCO\sb-cep\lvWeb1.1.1\bin
• The tools require you to specify the FULL PATH to the project workspace directory that holds the resources where you are granting permissions.  If your project path name has spaces, you can use double quotes.  We suggest you use an environmental variable to define the path to the project.  For instance:

  • set ProjDir=c:\tibco\workspaces\wiki_demo\Wikipedia_Monitoring

  • export ProjDir=~/workspaces/wiki_demo/Wikipedia_Monitoring

• Run the utility. On Windows:

lvweb-list -p %ProjDir% -c

On MacOS:

lvweb-list -p $ProjDir -c

For any given project, there may be a large number of resources, and thus you may prefer to redirect the output of the list command to a file by appending the following to either of the commands above:

>> Wiki_Resources.txt

Examine the file to obtain the IDs of the resources in the project to identify the ones you want to grant permission for other users to read or edit.

The next step is to create a new permissions file that we will use for a named user.  Permissions files follow the syntax of Java properties files:

ResourceType/ResourceId=<comma-separated list of allowed permissions>

Lines beginning with a # are comment lines

ResourceType can be DASHBOARD, PAGE, CARD, LINKAGE, or ANY

ResourceId is the ID of the resource give from the lvweb-list command or -1 to designate any resource.

Given a project with a card number 2, and page numbers 4, 7, and 10 on that card, to grant READ access to those resources, a permissions file would be:

page/2 = read

If by some chance you wanted a user to only see two of the three cards on the page, then the permissions file would be:

page/2 = read

card/4 = read

card/7 = read

Save your permissions file as user1.permissions. Import that permissions file for the named user into the project:

• lvweb-permissions -p %ProjDir% -i -f user1.permissions -u user1 -d
• lvweb-permissions -p %ProjDir% -i -f biz.perms -u bizuser -d

Output from the permissions granting command:

C:\TIBCO\sb-cep\lvWeb1.1.1\bin>.\lvweb-permissions -p %ProjDir% -i -f biz.perms -u bizuser -d

Using c:\tibco\workspaces\wiki_demo\Wikipedia_Monitoring as project output folder with persistence type as H2

2016-07-07 16:52:42.734-0400 [main] INFO  c.s.l.server.core.EmbeddedH2DB - Starting persistence JDBC Server on port 10081

Importing 4 permissions(s) to bizuser from biz.perms

Created 4, updated 0 and deleted 0 permissions from biz.perms for bizuser

Created dashboard for bizuser with 1 pages

Now run the project and log in as bizuser. This username sees exactly the one page that was permissioned for him or her.  If you use the permission file with a subset of all possible cards on a given page, then bizuser would see an empty spot on the page for that missing cards. This is an important distinction. The page knows that it was designed with some number, N cards. When a user has only been enabled to see less than N, then the page will reserve the spot for the missing, or non-enabled cards. 

In such a scenario the LiveView Web exception viewer reports that it is forbidden to access a resource. The resource it cannot access is that of the cards on the page that were not permissioned to this user.  For the sake of this example, we purposely set up this scenario - so you can see that the permissions can be fine-tuned and that the permissions granted are upheld.  If you had a scenario where you wanted some users to see only a subset of cards, then a best practice would be to make a new page with just that subset of cards that you want viewed by others.  Then grant access to that new, smaller page to those users.  Users who are allowed to see all the cards can be permissioned to see the page that has all the cards.

An online video tutorial covering this same material is available. All available LiveView Web video tutorials can be found here.

liveviewweb_authorization.pdf

liveview.auth_.properties.txt

sbd-common.sbconf.txt