Oracle9i Reports Services – Administration and Advanced Techniques An Oracle White Paper May 2002

1

Oracle9i Reports Services – Administration and Advanced Techniques

INTRODUCTION Internet Computing provides the benefit of universally accessible information, which is also one of the greatest causes of concern for those who administers the Web site. The Web site must scale to meet the requirements of the increased user community and also ensure that only those authorized to see the information can do so.

User satisfaction for a Web site is determined not only by the information served, but also by the speed at which it is delivered. If the site is unable to serve information in a timely manner due to increased load, users are less likely to use the site. Therefore, it is extremely important that the underlying architecture scales to meet user expectations.

In addition, user authorization is often defined not only by the privileges on the data itself (that is, database object level privilege), but also the functions performed on it. As access to a Web document is through its Uniform Resource Locator (URL), knowledge of the URL allows access to any unprotected document. To combat this, most Web servers allow for the securing of the directory in which the documents may be found, not for individual files within that directory. As reports are invoked by calling middle-tier mechanisms such as servlets or CGIs, the security schemas built into the HTTP listeners only apply to them, not the underlying report. Thus, it has been difficult for most Web sites or information Portals to implement much more than the most rudimentary of security models.

This paper focuses on the security and administration issues faced by system administrators when implementing a centralized reporting infrastructure. Specifically, it looks at the functionality available within Oracle9iAS Reports Services to address these issues, and identifies the tasks required to implement it. It does not cover the design of the Reports Server, and assumes a basic understanding of the architecture and the methods required to implement it.

For further information on Oracle9iAS Reports Services, refer to the white paper “Enterprise Reporting” available from http://otn.oracle.com.

2

SERVER CONFIGURATION To understand how to configure Oracle 9iAS – Reports Services, it is important to understand the different parts of the Reports Services. There are three elements that must configured in order to allow the service to work properly.

• The HTTP-Listener / Servlet-Engine is responsible for providing the required environment for the Reports Servlet.

• The Reports Servlet Configuration is located in the RWSERVLET.PROPERTIES file, which defines parameters that are immediately responsible for the operation of the Reports Servlet.

• The Server Configuration defines the service itself with settings that are stored in the <Servername>.conf file. This file is in XML format and describes the server and its features. Each server has his own configuration file.

Some settings can be changed using Oracle Enterprise Manager and will be picked up by the server with the next job execution. Some settings, such as the server name need the server to be restarted. If the server is running in-process with the servlet, this means, that the servlet has to be reloaded.

NOTE: Currently, the requirement for reloading a servlet means to restart the whole iAS instance as there is no selective re-loading of specific servlets.

SECURITY AND AUTHENTICATION Security in reporting, involves two areas of security :

• The report security, which describes the privileges for running a report and retrieving the output.

• The data source security, which controls the access to the data, used to create the report output

Secure Oracle9iAS Reports Services By integration with Oracle9iAS Portal security model, Oracle9i Reports is able to control user access to defined reports being run against Oracle9iAS Reports Services. As a user makes a request for a given report to be generated, Oracle9i Reports uses the information stored within Oracle9iAS Portal to verify their access rights to run the requested report at that time and on the requested server.

The security model of Oracle9iAS Portal is tightly tied to that of the Login-Server, the central authentication mechanism of Portal. That is, the definition of a single user within the Oracle9iAS Portal environment can match a schema within the Oracle9i Database but does not necessarily have to; multiple Portal users can share the same database schema. The use of groups allows you to

3

define both functional groups (e.g., DEVELOPER, CLERK) and a hierarchical security structure. The report itself is represented as a packaged procedure containing the relevant information on how to run the report.

Once users are defined within Oracle9iAS Portal, they may be included within the security framework of Oracle9i Reports. Portal’s user concept is based on the notion of lightweight users, which are users, managed by Login-Server. They are also assigned to database schemas but several users can use the same schema. These schemas are used by Portal to determine where to store objects created by each user in the database.

Oracle9i Reports uses Single Sign on capabilities to retrieve user-information for each data source based on the Single-Sign on-User to satisfy both, the report- and the data source security.

NOTE: There is a difference between a application user, managed with Login-Server and a database (data source) user. Leveraging the Single-Sign on capabilities of Login-Server, the connection-information for the data sources will be managed on a per application-user basis using login-server.

The definitions held within the Oracle9iAS Portal repository, which relate to the running of secured Oracle9i Reports, are part of the standard Oracle9iAS Portal installation.

During the installation of Oracle9iAS Portal the appropriate object definitions and menu entries as well as the RW_BASIC_USER, RW_DEVELOPER, and RW_ADMINISTRATOR groups are created. Out of the box, the server is configured to run in secure mode.

NOTE: To define Reports access security via the Oracle9i Reports Security Wizards within Oracle9iAS Portal, the user must be granted the RW_ADMINISTRATOR group (otherwise Reports Security Option will not appear as the user menu structure). In addition, the user must have “BUILD IN” privileges to any schema that will own the Reports Packaged Procedure or List of Values used within a parameter form.

To secure an un-secure server and enforce the definitions stored inside Oracle9iAS Portal there are a view steps necessary:

1. Add an alias in the TNSNAMES.ORA file on the machine where the Reports Server is located, pointing to the instance where Oracle9iAS Portal is installed.

2. Add the security Settings to the configuration files of ALL servers that should be secured. You must create a <security>-element identifying

4

the Java-class implementing the security mechanism and containing the connection information for the connection information to the Oracle9iAS Portal schema. Then, assign this security element to the <job>-element of every job type that should be secured using this security.

NOTE: For detailed information, refer to “Chapter 2 - Configuring Oracle9i AS Reports Services” in Publishing Reports to the Web and the whitepaper “Creating a secure reporting environment using Oracle9i AS Reports Services”

Once these settings are in place, the server has to be restarted to enable the security definitions and run the server in secured mode. It is now possible to define the required access security model. From the Oracle9iAS Portal Administer page, you can link to the Oracle Reports Security page. Here, it is possible to create the objects, which define the criteria of the security model.

Figure 1: Reports Security Administration

What

As a given report may reside on more than one Reports Server, the definition of a user’s access privileges must go beyond the report itself to include the available hardware on which that report may be executed/output. For example, a given report resides on both the central Reports Server and the one used by

5

senior management. Even though a given user may have the right to run the report, the user should be prevented from executing it on the management server. As such, the Oracle9i Reports Security allows for the securing of a number of different objects relating to the execution of a report.

Printer Access: • What local or network printers are available?

• Who has the appropriate privileges to use a given printer?

• When is this printer available for printing reports?

Servers Access: • What Report Servers have been registered within the Oracle9iAS Portal

repository and thus are available to accept job requests?

• What printers are available on a given Reports Server?

• Who has the appropriate privileges to submit job requests to a given Reports Server?

• When is a given Reports Server available to accept job requests?

• What is the URL required to call a given Reports Server via the Web?

• Can a given Reports Server run any available report or only those registered with Oracle9iAS Portal that have secure access control?

Report Definition File Access: • What Oracle9i Reports *.RDF, *.REP, *.JSP or *.XML files

have been registered for secure access?

• What Execution-method should be used?

• What is the name by which a given report will be known within the Oracle9iAS Portal environment?

• Who has the appropriate privileges to run a given report?

• Which Reports Servers have a given report available?

• When is a given report available for execution?

When

Often a user’s ability to access a report, server, or printer is determined by the point in time the job was submitted to execute. With the universal access afforded by the Web, the simple physical security of not being able to access the appropriate hardware (PC, printer etc.) outside a defined time period is removed; thus, the need to define an availability window as part of the report/object definition becomes paramount. For example, it has been decided that a given report may only be accessed during standard business hours. By applying the

6

availability calendar, which defines standard business hours, employees would not be able to login from home after hours and access the report.

The secure Oracle9iAS Reports Services supports the ability to define availability calendars for either:

• The individual report.

• The Reports Server on which jobs may be executed.

• The printers to which the report output may be sent.

In all cases, the availability calendar determines when the specific object is accessible for processing.

There are two different availability calendar types:

• Simple: is an availability calendar based on a single rule (e.g., between 9:00a.m. and 5:00p.m. daily).

• Combined: is a compound availability calendar determined from the addition of two or more simple calendars. The definition of a combined calendar supports both the inclusion and exclusion of the time periods specified within included simple calendars. That is, the combined availability calendar may be defined as

• Availability = (Sum of all included Calendars) - (Sum of all excluded Calendars) For example, to define a standard business hours availability calendar, it would first be necessary to create two simple calendars to be included/excluded as follows: 9:00a.m. - 5:00p.m. repeat every day. (Include) Saturday/Sunday repeat every week. (Exclude) The resultant availability calendar would only allow access during the period of 9a.m. to 5p.m., Monday to Friday.

NOTE: Combined availability calendars can also include/exclude other combined calendars. Thus, it is possible to create complex calendar definitions from a hierarchy of both simple and complex calendars.

Only one availability calendar can be applied to a given secured Reports Server object (i.e., report definition, server, or printer). Thus, if more complex time frames are required, it is necessary to build a single combined calendar (through

7

the addition or exclusion of simpler calendars), which reflects the desired time period.

How

It is often important not only to specify which report a user may access (and when), but also how that user may interact with the report. The secure Reports Server achieves this by restricting the report request options (i.e., required and optional report parameters), which are exposed to a given user at job submission. By specifying which parameters are exposed, the administrator can allow different users or groups to apply different options to the same physical report definition file.

For example, a given report may limit not only the server and printers to which it may be run, but also the possible values for DESTYPE and DESFORMAT. In this case, the administrator wants to restrict the report to Web viewing only, thus DESTYPE will be fixed at CACHE and the possible options for DESFORMAT limited to HTML and HTMLCSS.

Datasource Security - Single Sign-on Support In modern information systems, users access data from multiple sources and aggregate them to a single source of information. In most cases, each of these sources is secured separately and requires users to authenticate to release the information.

Oracle9i Reports itself is secured using the Login-Server as authenticating authority. It also uses the capabilities of Login-Server to support Single Sign on for the data sources. Each data source has by definition a specific command line parameter holding the connection information (e.g. USERID for the SQL data source). This parameter is a regular user parameter and is assigned at design time to be related to a specific data source using the Sign-On Parameter property in the Property Inspector. It is handed over to the PDS and used to authenticate and determine if the user is eligible for receiving information. To ensure that calling a report stays manageable even though there might be multiple data sources involved, Oracle Internet Directory’s extended preferences are used to store the login information for each data source on a per-user basis. In other words, once you are logged in as the application user, the reports

servlet has access to all your connection information stored in OID you have used previously and will re-use them when you request a report. The SSOCONN parameter is the indicator for the servlet that you want to use the single sign on for this report. The value for this parameter is a list of connection keys that provide the information required by the servlet to query the connection information from OID.

If you use a data source for the first time you, will be prompted for connection information. After successful authentication this information will be stored as

8

the new connect-information and used the next time you use this data source. This way you only authenticate as an application user and the data source-based authentication is handled for you by Oracle9i Reports Services.

For more information about securing your reporting environment, refer to the white paper Securing Oracle9i Report” available on http://otn.oracle.com.

9

KEEPING TRACK OF SERVER USE The move to a centralized reporting infrastructure introduces the requirement to supply certain operational information; users want to know the status of any report they have submitted.

Administrators need to know how many concurrent users there are on the Reports Server. This is useful for both sizing the environment and to ensure license compliance.

Oracle9iAS Reports Services makes it possible to respond to these requirements in different ways.

Enhanced User Interface for the server-queue Information The user interface of the HTML server queue has been enhanced to make it easier to query the job-status information.

The three different server queues (Current, Past, Scheduled) are now selectable individually using a drop down list and the entries in the list can be selected in increments of 10 to enhance the performance of the queue status.

Configuring the Server to update a database table with Queue activity Oracle9iAS Reports Services provides an interface for plugging in alternative queue-management functionality. Shipped with the product is a reference implementation that populates the database table with queue information.

NOTE: The script for creating the necessary tables can be found in %ORACLE_HOME%\reports\admin\sql\Rw_Server.sql.

To implement the queue, perform the following steps:

1. Create a schema, which will own the report queue information and have executed privileges on the server-queue API.

2. To activate the additional queue management, add the jobStatusRepository element to the server configuration file. It holds the name of the Java-class that should be used. If you omit the class attribute the default would be oracle.reports.server.JobRepositoryDB, which stores the queue information in the database table.

Every time the server maintains the main queue in his persistent file, it will call the additional management facility as well.

NOTE: You can create your own mechanisms by implementing the interface oracle.reports.server.jobRepository. These

10

management features are READ-ONLY. The interface does not provide any functionality for submitting a job.

The Server Queue Table The Reports Server will maintain the table named RW_SERVER_QUEUE with the current job queue entries and includes such data as:

• the name of the job

• who submitted the job

• what output format was chosen

• the job’s current status

• when it was queued, started, and subsequently finished

(See Appendix for a description of the RW_SERVER_QUEUE table structure.)

By granting users SELECT access to this table, users may query the job submission of interest and determine its current status. In the same manner it is possible to implement a Reports Server Queue screen directly within the Web site itself simply by creating a report based directly on this table. In this case the queue report itself would appear as a job submission by the user!

NOTE: For Oracle Forms based applications the basing of a block against the RW_SERVER_QUEUE table would allow users to track their reports without the need to leave the forms environment or resort to use of the Web.Show_Document built-in. The Queue-Table is a READ-ONLY representation of the server-queue. Inserting records into this table WILL NOT create jobs on the server.

Conversely, the real time update of the table with the status of job submissions makes it very easy for administrators to know exactly how many concurrent users have requested jobs to be executed on the Reports Server.

By counting the number of entries in the RW_SERVER_QUEUE table, which have a status code indicating that the job has been queued but not completed, it is possible to return an accurate number of the current active users on the server.

E.g.

SELECT Count(*) FROM RW_SERVER_QUEUE WHERE STATUS_CODE IN (1, -- ENQUEUED 2, -- OPENING 3 -- RUNNING) AND JOB_TYPE != ‘Scheduled’

11

NOTE: While the table contains the date and time a report was queued, run, and subsequently finished, it is not a good idea to use a query based on the that fact that a job has a defined ‘QUEUED’ and ‘STARTED’ time but no ‘FINISHED’ value. If a report terminates due to an unexpected error, such as an invalid input, the FINISHED column will remain NULL; however, the STATUS_CODE and STATUS_MESSAGE will both indicate that there has been a failure and the cause thereof. (See the Appendix for definitions of available status codes.)

In order to configure your server to use this implementation, you have to add the jobStatusRepository tag to the server config file.

The Queue-Content in XML Format In some cases, the information of the server queue may be used by other applications as input data. Thus, the queue information can also be retrieved in XML format so it can be transformed to other formats using XSLT. You can specify this format by adding the command line parameter STATUSFORMAT=XML | XMLDTD | HTML to the SHOWJOBS command, as follows.

…/RWServlet/showjobs?server=myserver&statusformat=XML

The three available modes return different output.

• XML returns just the XML stream for the server queue

• XMLDTD adds an inline-DTD to the XML stream

• HTML returns the queue information in the new HTML user interface. This option is default.

CENTRALIZED MANAGEMENT USING ORACLE9I ENTERPRISE MANAGER Oracle9iAS Reports Services is integrated into the central management facility called Oracle Enterprise Manager (OEM).

With OEM you can perform basic management functions such as starting and stopping the servers that are not running in-process, checking the queue status and modifying the server’s configuration parameters.

The OEM environment also provides some key performance indicators for your Reports Service to help you determine utilization. It is based on a light-weight, HTML-based client.

Management entities In a reporting environment, there are two management entities: a single server and a server-cluster. Each server within the environment is of either category and can run in-process or stand-alone.

12

The management framework also represents these entities by grouping clustered servers according to their cluster.

Management Functions OEM can act as your central point of management for all your reports servers. It offers help for the daily tasks you have to perform:

• start/stop/restart a server

• server queue management

• server/job tracing

• server configuration

Start/stop/restart

The management console provides you with the current status of the server and some runtime metrics such as CPU and Memory usage, average response time and an overview of the server load.

You can start and stop the server as well as restart, which does an unattended bounce of the server. As soon as the server has been shut down, it is restarted automatically, allowing you to focus on tasks other than waiting to start up the server.

Server queue management

OEM will also provide the queue information of the selected server, as you would get it using the SHOWJOBS command with the Reports Servlet. You see the three job queues (past, current and schedule). You can access the output of jobs in the past queue and you can kill jobs from the current and the schedule queues.

Server/job tracing

You can view the content in the trace file to analyze it. These trace files can be server or job traces. They are only created when you turn on the tracing option of the Reports Server.

13

Server configuration

To minimize the need for work directly on the server, you also have access to the server configuration file and can modify it from the OEM Console and save the changes back to the server. You can then restart the server to make the changes take effect.

14

CONCLUSION The move to a centralized reporting infrastructure allows organizations to both minimize their costs and maximize access to information. It does, however, introduce issues, which until now have made many system administrators reticent to adopt the new paradigm; that is the security implications of a Web-based solution and the need to scale to a larger user community.

Oracle9i Reports, in conjunction with Oracle9iAS Portal, answers these issues by allowing for the implementation of both a scaleable, clustered environment and user authentication and access control.

15

Oracle9i Reports Services – Administration and advanced Techniques April 2002 Author: Philipp Weckerle Copyright © Oracle Corporation 2002 All Rights Reserved Printed in the U.S.A. This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors herein to Oracle Corporation. Oracle Corporation does not provide any warranties covering and specifically disclaims any liability in connection with this document. Oracle is a registered trademark and Enabling the Information Age and Software Powers the Internet are trademarks of Oracle Corporation. All other company or product names are mentioned for identification purposes only, and may be trademarks of their respective owners.

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: 650.506.7000 Fax 650.506.7200 Copyright © Oracle Corporation 1995 All Rights Reserved