Creating Multi-Tenancy Tutorial

Introduction

In this tutorial, you will create two organizations. The first organization will be named California and the second will be named Washington.

Each organization will have its own private folder structure where assigned users can access and share data sources, reports, dashboards, analyses, and related objects
Anything stored in the organization’s folder structure is only accessible to its private members and superuser

You will also copy a Domain and Data Source from the sample Organization folder to the Public folder. Once configured for row-based security (explained in this tutorial), all users will have access to the Domain, but they will retrieve only their organization’s data.

Product Versions

This tutorial works with version 3.7 and later.

User

Administrator, DBA, Developer

Objectives

This guide will enable you to:

Create Organizations
Copy Resources to the Public Folder
Update the Supermart Domain
Set Row-Level Security for Public Domain
Test with Ad Hoc Reports

Pre-Requisites

JasperServer must be installed with the Supermart demo environment in order to follow this tutorial

You must have superuser access to JasperServer
You must be able to stop JasperServer, modify an xml file, and restart the server

Before You Begin: Jaspersoft 3.7 only

JasperServer Pro 3.7.0 requires the following configuration change. This is not required in later versions. You need access to the application server in order to execute this step. (Reference bug 17284 fixed in Jaspersoft 3.7.0.1.)

Open ../jasperserver-pro/WEB-INF/applicationContext-adhoc.xml in a text editor
Locate applySecurityFilterInMemory and change the value from true to false:

Restart JasperServer

Return to top

Create Organizations

You will create organizations in this step. Organizations are the foundation for multi-tenancy. Each organization will then have its own private area for storing files and resources, which are completely hidden from other organizations.
Later in this tutorial you’ll see how organizationId, which is part of the logged in user’s “principal” authentication object, can be applied to objects stored in the shared Public area.

Step	Action
1	Login as superuser/superuser.
2	From the Jaspersoft menu bar, choose Manage > Organizations.
3	With the [root] organization selected, click Add Organization, in the upper right corner.
4	Enter California for the Organization Name. Enter ca for the Organization ID.
5	Optional: This step is helpful for demonstration purposes. With the new organization selected, click Manage Users Select jasperadmin In the Details pane, click Edit Change Full Name from jasperadmin to California Admin Click Save, which is located in the control ribbon at the top of the Details panel Repeat the process for joeuser, changing Full Name from joeuser to California User Click Save
6	Repeat steps 2 – 4 for the next organization: Enter Washington for the Organization Name Enter wa for the Organization ID Optional: Change the Full Names for jasperadmin to Washington Admin and joeuser to Washington User as in step 5
7	From the Jaspersoft main menu, click View > Repository Expand [root > Organizations] Results: You should see separate folders for California and Washington Only superuser and users associated with each organization can access these folders
8	Log out. Log back in, but this time, enter: Organization: ca User: jasperadmin (or joeuser) Password: jasperadmin (or joeuser)
9	Note: Jaspersoft retains your most recently used organization/tenantId in the URL. http://localhost:8080/jasperserver-pro/login.html?showPasswordChange=nul... To change the Organization ID directly on the URL, change the value after orgId=: http://localhost:8080/jasperserver-pro/login.html?showPasswordChange=nul... To clear the Organization ID from the URL, modify the URL as follows: http://localhost:8080/jasperserver-pro/ From the Jaspersoft main menu, click View > Repository.

Return to top

Copy Resources to the Public Folder

The Jaspersoft Supermart demo includes a sample organization named Organization. Its organization/tenantId is organization_1.
You will copy resources from the sample organization to the Public area.

Step	Action
1	Log back in as superuser/superuser. You will need to clear the Organization ID from the URL before logging back in. See the Note section, above
2	For this tutorial, we are going to create a folder to which all users can save reports. Click the [root > Public] folder Right-click Add Folder Name the folder reports (case-sensitive) Click Add. With [root > Public > reports] selected, right-click and select Permissions from the context menu Grant ROLE_USER [Write + Delete + Read] privileges and click OK
3	Expand [root > Organizations > Organization > Domains] In the Refine area, change Visualization types to All types
4	Right-click Supermart Domain and click Copy.
5	In the Folder view, click [root > Public] Right-click and click Paste
6	In the Folder view: Expand [root > Organizations > Organization > Analysis Components > Analysis Data Sources] Right-click Foodmart Data Source JNDI and click Copy
7	In the Folder view, right-click [root > Public] and select Paste.

Return to top

Update the Supermart Domain

The Public folder should now contain Foodmart Data Source JNDI and Supermart Domain. Your objective now is to make sure the domain and its resources are all publicly available.

Step	Action
1	Right-click the Supermart Domain and click Edit. Result: The Edit Domain designer opens.
2	In the Data Source box, click Browse.
3	Select [Public > Foodmart Data Source JNDI] and click OK.
4	Click Save. Result: All users can now create Ad Hoc queries, charts, tables, and crosstabs using this Domain.

Return to top

Set Row-Level Security for Public Domain

Now you will activate domain-based security, and edit an XML file in a plain text editor.

Note: Don’t worry if you’re not yet comfortable with the expression language. This is an introductory tutorial for an advanced feature. For now, you can simply focus on the mechanics and the outcome.

Step	Action
1	At the top of the page, click Resources, which is located below the main menu and to the right of Edit Domain.
2	Under Security File, select supermartDomain_security and click Download.
3	You will be prompted to save or open the file For this tutorial, save the file to an easily accessible location, such as My Documents, your desktop, or home directory
4	Open supermartDomain_security.xml in a plain text editor.
5	Locate the Access Grant definitions for Sales, Inventory, Expenses, and Employees. Uncomment the resourceAccessGrant definitions within each section, using the screenshot below as a guide. The beginning of each comment is indicated with an exclamation point followed by two dashes; the end of the comment is indicated with two dashes.
6	Notice the filterExpression attributes. Here we’re filtering rows where store_state = tenantId Example: ca or wa Save the file Make sure it is a plain text file and retains the .xml file type.
7	Switch back to JasperServer Under Security File, select supermartDomain_security, and click Edit
8	On the Local File tab, click Browse and locate your updated security file from your hard disk. Click OK Click Save, located in the lower right corner of the Resources page

Return to top

Test with Ad Hoc Reports

Here you test row-based filtering based on the logged-in user’s organization/tenantId.

Step	Action
1	Log out and log back in as a California user (see Step 1.8): Organization: ca User: jasperadmin (or joeuser) Password: jasperadmin (or joeuser)
2	From the Jaspersoft main menu, click Create > Ad Hoc Report.
3	Click the Domains tab and then: Select Public > Supermart Domain Click the Crosstab icon Click Choose Data
4	Create the query: Drag Expenses to Selected Items. Click Open Report.
5	Design the report: Expand [Expenses > Stores > Store Contact]. Drag City to the Row Group. Notice you only see California cities. Drag Store Type to the Column Group. Drag Expense Amount to the Data Values area. Add more fields and further format the report, if you wish.
6	From the Ad hoc report designer toolbar, click Save Report. Click Browse and navigate to Public > reports Click OK Keep the name the same for now so you can use it later in step 8
7	Log out and log back in as a Washington user (see Step 1.8): Organization: wa User: jasperadmin (or joeuser) Password: jasperadmin (or joeuser)
8	Locate Public > reports > Adhoc Report in the repository Right-click and select Open in Designer Notice that the data is filtered to show only Washington cities

Return to top

What's Next?

Consider your entire community when applying security filters to public objects.

Example: If you log in as an organization_1 sample user, you will retrieve no data when accessing this sample domain. This is because the user’s tenant_id, organization_1, does not match any value in store_state. You can adjust for this programmatically in the <principalExpression> section preceding the <filterExpression>.
In our sample, we adjusted for superuser in the principalExpression, essentially skipping the filter when tenantId is empty (which is the case when you log in as superuser).

Valuable reference materials include:

JasperServer User Guide, Release 3.7: Section 7 Advanced Domain Features, particularly section 7.4 The Domain Security File
- This guide is included with JasperServer Pro in the /docs folder.
JasperServer Ultimate Guide, Release 3.5: Section 6 Securing Data in a Domain
- Jaspersoft subscribers can download this guide from the Jaspersoft Support Portal
- It is also for sale at http://www.jaspersoft.com.
- Note: The JasperServer Ultimate Guide for Release 3.7 is expected in March 2010.

Written By

This tutorial was written by Mary Flynn, Senior Sales Engineer, February 2010.