TIBCO LiveView Web User Authorization Guide

Transcription

1 TIBCO LiveView Web User Authorization Guide Introduction... 2 Location and Usage of the lvweb-* Tools... 2 lvweb-copy... 4 Synopsis... 4 Description... 4 Options... 4 Examples... 4 lvweb-delete... 5 Synopsis... 5 Description... 5 Options... 5 Examples... 5 lvweb-list... 6 Synopsis... 6 Description... 6 Options... 6 Examples... 6 lvweb-permissions... 8 Synopsis... 8 Description... 8 Options... 8 Permissions File Format... 9 ResourceID Examples in a Permissions File to be Imported... 9 Usage Notes Examples lvweb-reset Synopsis Description Options Examples Shared Options LiveView Web Authorization System Initial Setup Using Permissions in 1.1.x Using 1.1.x Permissions to Emulate 1.0.x Users Using 1.1.x Permissions What is a Privileged User? Example Scenario Step 1: Admin Creates the LiveView Web Resources Step 2: Getting the IDs of the Created Resources Step 3: Import Permissions for guest... 16

2 Step 4: Import Permissions for limited_user Step 5: Import Permissions for regular_user Introduction This guide describes how to use the five lvweb-* tools included with TIBCO LiveView Web 1.1.x and later releases. These tools are used to configure user permission settings for a TIBCO Live Datamart (LDM) project to which LiveVew Web will connect as a client. These tools are only needed when the LDM project is configured to use authorization. Most samples shipped with LiveView Web have authorization disabled. In the no-authorization state, every LiveView Web user connects to an LDM server with the same effective permissions, which are the equivalent of superuser privileges. By enabling authentication and authorization, LiveView Web administrators can restrict or enable users by dashboard, page, or card with very fine-grained control. Enable authentication and authorization for your LDM project as described on the LiveView Server System Configuration page of the LiveView Administration Guide. Location and Usage of the lvweb-* Tools The lvweb-* tools are installed in the bin folder of your LiveView Web installation, along with their implementing lvweb-tools.jar file. On Windows, use the Start > All Programs > TIBCO > LiveView Web 1.1 > Install Directory menu to open a Windows Explorer window directly to the LiveView Web installation directory. The lvweb-tools.jar file must be present in the folder that the tools are executed from (or added to the CLASSPATH). The tools require that the environment variable STREAMBASE_HOME is set, pointing to the top level of your StreamBase+LDM installation. On Windows, use a StreamBase Command Prompt, which automatically configures the environment for command-line use, including setting of STREAMBASE_HOME. On macos, configure your login shell environment to use the sb-config env command, as described as a post-installation step in the OS X installation page of the StreamBase Installation Guide. The easiest way to run the lvweb-* tools is from their installed bin directory location. The disadvantage of this location is that all the tools require you to specify the full or relative path to the StreamBase Studio workspace location of your LDM project. This can be a long path, often including spaces, to have to type many times when using several lvweb-* commands in sequence. To cut down on the typing, you can set up an environment variable containing the full path to the LDM project of

3 interest, then specify that variable as the argument to the p option of each lvweb-* command. For example: (On macos) lvweb-list p $PROJ r * (On Windows) lvweb-list p %PROJ% -r * You can also add the lvweb-tools.jar file to your CLASSPATH to allow the lvweb-* tools to be run from locations other than their installed location. This Guide provides reference pages for each of the lvweb-* tools in alphabetical order, then provides an overview discussion of the workflow and expected usage of the tools, along with a comparison of authorization under previous LiveView Web releases.

4 lvweb-copy Synopsis lvweb-copy -p path-to-project [ t [h2 file]] s sourceuser d destinationuser Description Copies the permissions and resources created by and personalized by the source user to the destination user. The tool copies the resources by value (not by reference) so all the copied resources are owned by the destination user. Options -s --sourceuser s-username Specifies the s-username whose permission settings are to be copied. The s- username must already exist in the project s liveview.auth.properties file. -d --destinationuser d-username Specifies the d-username whose permission settings are to be granted. The d- username must already exist in the project s liveview.auth.properties file. For p and t, see the Shared Options section below. Examples lvweb-copy p /path/to/project s earlyuser d newuser Copies the permission settings for all resources personalized by and created by earlyuser to newuser.

5 lvweb-delete Synopsis lvweb-delete -p path-to-project [ t [h2 file]] u username Description Deletes the specified username completely from LiveView Web storage. All of username s created and personalized resources are deleted, and all permission settings associated with username are deleted. There is no recovery option for this command, so please back up your data before running this command. Options -u --user username Specifies the username that is to be deleted. The username must exist in the project s liveview.auth.properties file. For p and t, see the Shared Options section below. Examples lvweb-delete p /path/to/project u newuser Deletes all permissions and resources created by or personalized by newuser from the specified project.

6 lvweb-list Synopsis lvweb-list -p path-to-project [ t [h2 file]] [ r resource-spec] [-c] Description Returns a list of the specified resources in the specified project, showing the ID number of each resource. You must use resource IDs when specifying permission settings with the lvweb-permissions command. Thus, you must run lvweb-list to obtain the IDs of interest before running lvweb-permissions. Options -r --resource resource-spec Accepts one resource-spec, which can be: A single asterisk to specify all resource types. This is the default resource-spec if you do not specify a r option. One of dashboard/*, page/*, card/*, or linkage/* to specify all instances of the specified resource type. One of dashboard/regex, page/regex, card/regex, or linkage/regex to specify all instances of the specified resource type that matches the specified regular expression regex. Express regular expressions using the syntax of java.util.regex.pattern. -c --children Add the c option to show the children of each specified resource type, indented under each resource instance. Dashboards show all of each dashboard s pages, while pages show all of each page s cards and linkages. For p and t, see the Shared Options section below. Examples lvweb-list p /path/to/project r dashboard/* -c Returns a list of all dashboards in the specified project, with each page of each dashboard indented under its parent dashboard. Each card and linkage of each page is further indented under its parent page. lvweb-list p /path/to/project r * lvweb-list p /path/to/project Either command returns a list of all resources in the specified project. lvweb-list p /path/to/project r dashboard/* Returns a list of all dashboards in the specified project.

7 lvweb-list p /path/to/project r page/price.* Returns a list of all pages in the specified project whose name starts with Price.

8 lvweb-permissions Synopsis lvweb-permissions -p path-to-project [ t [h2 file]] u username -e -f filename lvweb-permissions -p path-to-project [ t [h2 file]] u username -i [-m] -f filename [-d] Description Exports current permission settings for username to a permissions file, or imports permission settings for username from a permissions file, optionally merging with existing settings. At import time, you can optionally update all dashboards owned or updateable by username to contain references to all pages accessible by username. There is no recovery option for this command, so please back up your data before running this command. In case of incorrectly imported permissions, you can use the lvweb-delete command to remove all permissions for username, then re-import them with another lvweb-permissions command. Options -u --user username Specifies the username whose permissions are to be modified; this option is always required. The username must already exist in the project s liveview.auth.properties file. -e --export Specifies an export operation for the specified username, extracting all current permission settings into the file specified with f. -f --file Specifies the path to a file to contain permission settings exported with e, or the path to a file that contains permission settings to be applied to username with i. This option is required when using either e or i. The format of the permission settings file is described below. -i --import Specifies an import operation to read the permission settings from the file specified with f and apply them to username. -m --mergeimport Use only with i. Specifies that the settings imported from the permissions file are to be merged with any existing settings for username for all resources.

9 -d --updatedashboards Use only with i. Specifies updating all dashboards owned or updateable by username to contain references to all pages accessible by username. This option is ignored if importing a dashboard. For p and t, see the Shared Options section below. Permissions File Format Permissions files generated by the e export option, or imported with the i option, follow the syntax of Java properties files: ResourceType/ResourceId=<comma-separated list of allowed permissions> Where: ResourceType can be one of DASHBOARD, PAGE, CARD, LINKAGE, or ANY. (Resource types are case insensitive in use, but are shown in uppercase for clarity.) ResourceId is the ID of the resource as determined with the lvweb-list command or is -1 to designate any resource. Lines beginning with # are comment lines. Permission keywords (case insensitive in use) have the following meanings: CREATE grants the ability to create this resource type. This has no meaning for existing resources with IDs, and is best used with the -1 ResourceID. READ, UPDATE, and DELETE have the obvious meanings for the specified resource type. Be careful when granting UPDATE rights for the same resource to two or more users, because their changes to the resource can conflict. PERSONALIZE grants update rights to a private copy of the resource. Use PERSONALIZE instead of UPDATE for most resources. EXPORT_DATA only applies to the CARD resource type. ANY grants a combination of all allowed permissions for the specified resource type. ANY includes UPDATE instead of PERSONALIZE; thus do not grant ANY rights lightly. It is designed for administrator user names. ResourceIds can be extended with the following syntax: ID by itself = the ID of the resource as determined with the lvweb-list command. ID/* = The resource ID and its immediate children. That is, a DASHBOARD s children are PAGEs, while a PAGE s children are CARDs and LINKAGEs. ID/**/* = The resource ID and all of its children and grandchildren. ResourceID Examples in a Permissions File to be Imported # Import dashboard ID 1 with read permission:

10 dashboard/1=read # Import dashboard ID 2 and the pages it contains with read and # personalize permissions: dashboard/2/*=read,personalize # Import dashboard ID 3 and the pages it contains along with all the # cards and linkages in each page, all with read and personalize permissions: dashboard/3/**/*=read,personalize # Import page ID 1 with read permission: page/1=read # Import page ID 2 and its cards and the linkages it references with # read permission: page/2/*=read # Allow creation of dashboards: dashboard/-1=create # Allow creation of pages: page/-1=create # Allow creation of cards: card/-1=create # Allow creation of linkages: linkage/-1=create Usage Notes The d option allows you to create a new dashboard for which the user has all permissions. The newly created dashboard will contain all the pages accessible to the user. Generally, avoid giving update permissions to a dashboard. If the dashboard is shared between multiple users, confusing configurations can arise, such as when UserA and UserB both can update dashboard 1. UserA adds a new page with ID 1, but only UserA can access page 1. Nevertheless, page 1 gets added to dashboard 1. Now when UserB accesses dashboard 1, he or she will get an unauthorized error when trying to modify page 1. You can import an existing dashboard with read permission to restrict the user to only the pages present in the dashboard, or you can import an existing dashboard with read and personalize permissions to allow the user to personalize the dashboard. The import tool does not have a deterministic order of importing. It is not necessarily the case that the order in which you define permissions in the permissions file is the order in which they will be imported.

11 Do not use the children (/*) or the grandchildren syntax (/**/*) if you want to finetune the permissions of some of your child or grandchild resources. For example, let's say you have a page with ID 1 that contains cards with ID=2 and ID=3. Your goal is to make the page and card 2 read-only, but to grant card 3 read and personalize permissions. You can use a permissions import file like the following: # Import page 1 page/1 = read # Import card 2 card/2 = read # Import card 3 to have personalize permissions card/3 = read, personalize As an alternative, you can use two import operations. The first time, use the following import file: # Import page 1 and all its children with read permissions. page/1/* = read For the second import operation, use the m option to merge the following permissions with the ones defined by the first import operation: # Import card 3 to have personalize permission. card/3 = read, personalize Examples lvweb-permissions -p /path/to/project -e -f user1.permissions -u user1 Export all the permissions of user1 into a file named user1.permissions from the specified project. lvweb-permissions -p /path/to/project -i -f user1.permissions -u user1 -d Import all the permissions defined in a file named user1.permissions for user1 and optionally create a dashboard with the accessible pages in it for the specified project. lvweb-permissions -p /path/to/project -i -f user1.permissions -u user1 -d -m Import all the permissions defined in a file named user1.permissions for user1, merging those permissions with existing permissions, if any, and optionally create a dashboard with the accessible pages in it for the specified project.

12 lvweb-reset Synopsis lvweb-reset -p path-to-project u username [ t [h2 file]] [-a] Description Resets all resources personalized by username back to their state before any such personalization. By adding the optional a argument, you can also remove all resources created by username. There is no recovery option for this command, so please back up your data before running this command. Options -u --user username Specifies the username whose permissions are to be reset. The username must already exist in the project s liveview.auth.properties file. -a --all In addition to resetting all personalized resources, delete all resources created by username. For p and t, see the Shared Options section below. Examples lvweb-reset p /path/to/project u newuser Resets all resources personalized by newuser back to their initial state in the specified project. lvweb-reset p /path/to/project u newuser a Resets all resources personalized by newuser as above, and also deletes all resources created by newuser.

13 Shared Options The following options have the same meanings for all of the lvweb-* commands. -h --help Shows usage text for this command. --version Returns the current LiveView Web version number. -p --projectdir path-to-project Specifies the relative path from the location of the this lvweb-* command, or the full, absolute path, to the Live Datamart project folder that contains the project that LiveView Web is to query. Tip: In StreamBase Studio, use the StreamBase > Open Command Prompt Here command (Windows) or the StreamBase > Open Command Terminal Here command (macos) to open a window whose current directory is the selected Studio project. Then capture the current directory into an environment variable that you can later use as an argument to the p option. -t --pstoretype h2 file Specifies whether the project specified with p stores its LiveView Web persistence data in an h2 database in the project folder, or in a debugging file format. The default and strongly recommended persistence type is h2. Do not use the t file option except under the direction of TIBCO Support personnel. If so directed, specify using the debugging file format by placing the following line in the sbd.sbconf for your Live Datamart project: <sysproperty name="liveview.web.pstore.type" value="file"/>

14 LiveView Web Authorization System This section compares the LiveView Web 1.0.x and 1.1.x systems of granting edit permissions to users, and then describes the 1.1.x workflow. Initial Setup Using Permissions in 1.1.x LiveView Web release 1.1.x introduces a new permissions and authorization feature. This section describes the initial setup that must be completed to allow users to log in and use LiveView Web in any authentication-enabled project. We also compare the permissions setup that was required in LiveView Web 1.0.x with the new 1.1.x system. Using 1.1.x Permissions to Emulate 1.0.x Users In LiveView Web 1.0.x, users were added to the system by adding entries to the liveview.auth.properties file. Once the users logged in, they would be given their own personal dashboard. To achieve similar behavior in 1.1.x, the same liveview.auth.properties file needs to be modified to include create permissions for all dashboard resources. For example, in the sample shipped with LiveView Web, the liveview.auth.properties has create permissions for the LVUser role: role.lvuser = connect, table:list, table:manage, table:*:itemssales, table:query, alert:list, alert:set:itemssales, alert:delete, alertaction:publish:itemssales, alertaction: itemssales, alertaction:sendtuple:itemssales, tuple:info:itemssales.datain, tuple:send:itemssales.datain, workspace:get:auth Sample, dashboard:create, page:create, card:create, linkage:create The following table explains some of the permissions added: Permission dashboard:create page:create card:create linkage:create Explanation Allows creating dashboards Allows creating pages Allows creating cards Allows creating linkages Note: LiveView Web does not support migration of 1.0.x resources to 1.1.x format. Using 1.1.x Permissions In LiveView Web 1.1.x, the admin user (or another user with privileged permissions, as described next) can create dashboards for other users. This style of setup allows giving an initial set of dashboards to LiveView Web users and also

15 allows greater control over how the users can interact with various levels of LiveView Web resources. What is a Privileged User? A privileged user has all permissions (current and future) on all resource types (current and future). Semantically, it can be represented as a user who has permissions configured as ANY:ANY. LiveView Web exposes a property called liveview.web.privileged.principals to enable configuration of a list of privileged users. The property takes a comma-separated list of user names to be given the ANY:ANY permission. By default, LiveView Web creates privileged permissions for the admin user, if that name is configured in the liveview.auth.properties file. Example Scenario The following sections describe the steps to create a set of users for a LiveView Web system. These steps are to be run by a user named admin, who is established as a privileged superuser in the liveview.auth.properties file. The users to be created are the following: guest, who has read-only access to the dashboard created by admin. limited_user, who can modify the dashboard created by admin but cannot add his or her own resources to it. regular_user, who can modify the dashboard created by admin as well as create his or her own resources. Step 1: Admin Creates the LiveView Web Resources Once the users have been added to liveview.auth.properties, run the project as a LiveView Server. 1. Connect to the server with LiveView Web, and log in as admin, password admin. The admin user creates a page named LVSessions which has two cards in it. One card shows the current set of LiveView sessions as a grid, and the second card shows the list of queries in each session. The second card is linked to the first card so that when you select an LVSessions table row, you will see the queries running in the selected session. 2. The admin shuts down the LDM server, then performs the next steps. Step 2: Getting the IDs of the Created Resources 1. LiveView Web tools work with the IDs of the resources. Use the lvweb-list command to determine the IDs of the dashboard, page, and two cards created so far. 2. Run the command: lvweb-list p /path/to/project-folder c 3. This command returns a number of lines like the following. Only the first few words of each line are shown here to save space: Using /path/to/project-folder as project output folder with Dashboard [id=1, name=, modifieddate=date author=admin

16 Page [id=1, name=lvsessions, modifieddate=date author=admin Card [id=1, name=lvsessions Card [id=2, name=lvsessionqueries Linkage [id=1, name=null,, sourcecardid=1, targetcardid=2 Step 3: Import Permissions for guest 1. Create a permissions file named guest.permissions, which will be imported to provide the guest user with basic permissions. See the lvwebpermissions reference to understand the syntax of permissions files. # Grant read-only permissions to all children and grandchildren # of dashboard ID 1. dashboard/1/**/*=read 2. Run the following command: lvweb-permissions p /path/to/project i f guest.permissions u guest 3. The command returns output like the following. (Long lines were trimmed for presentation.) Using /path/to/project as project output folder Importing 1 permission(s) to guest from guest.permissions Created 5, updated 0, and deleted 0 permissions from Step 4: Import Permissions for limited_user 1. Create a new permissions file named limited.permissions with the following content: # Grant read-only permission for the dashboard. dashboard/1=read # Grant read and personalize to the page and its children. page/1/*=read,personalize 2. Run the following command: lvweb-permissions p /path/to/project i f limited.permissions u limited_user Step 5: Import Permissions for regular_user 1. Create a new permissions file named regular.permissions with the following content: # Allow creation of dashboards. dashboard/-1=create # Allow creation of pages. page/-1=create # Allow creation of cards. card/-1=create # Allow creation of linkages.

17 linkage/-1=create # Grant read and personalize to the page and its children. page/1/*=read,personalize 2. Run the following command: lvweb-permissions p /path/to/project i f regular.permissions u regular_user Copyright 2016 TIBCO Software Inc. All rights reserved.