1.7 Secure Map Rendering

You can implement secure map rendering based on a web user's identity.

Users with different roles or permissions will see different feature sets when viewing the same theme. The basic idea is that the map visualization component will always invoke a specified PL/SQL package to set the web user's identity in the database whenever accessing the database for any themes. This user information can be used by the database to enforce data access control.

Note:

In this section, the terms user and authenticated user refer to the application or web user that logs into Oracle Fusion Middleware or Oracle Single Sign-On (SSO). It is not the same as the database user. that the map visualization component itself will connect directly to a database schema that stores all the geospatial data.

The map visualization component will connect directly to a database schema that stores all the geospatial data. To enforce access control for the map visualization component on the data in this schema, you must perform the following steps:

1. Create a PL/SQL package in the database schema. The package must have at least two named procedures: set_user(username) and clear_user().

2. Create views, set access rights on database objects, and perform other tasks, based on the user identity stored in the PL/SQL package (which is set by the map visualization component through the set_user procedure for each database session).

3. Create a map visualization component data source to the schema, providing the name of the PL/SQL package as part of the data source definition. This is considered a secured data source.

4. Create map visualization component themes that are based on the views created in step 2.

5. Establish web authentication for users accessing your map visualization component application page or pages, so that when a map request reaches the map visualization component servlet, the web session object should contain an authenticated user's identity.

6. Issue map and FOI (feature of interest) requests that view the themes defined in step 4, either directly or through the use of base maps and Oracle Maps.

   The map visualization component will automatically pass the user identity to the database using the PL/SQL package before it executes any query for these themes. Only those rows that are visible to the identified user will be returned from the database and rendered by the map visualization component.

How Secure Map Rendering Works explains how secure map rendering works and provides implementation details and examples. Options for Authenticating Users describes some options for authenticating users.

• How Secure Map Rendering Works
  
• Getting the User Name from a Cookie
  
• Options for Authenticating Users
  

1.7.1 How Secure Map Rendering Works

The map visualization component, as a Java EE application, can obtain the identity of a web user that has been authenticated to Oracle Fusion Middleware or Oracle Single Sign-On (SSO). This user information can then be preserved and propagated to the database, where secure access to map layers and tables can be set up based on the user identity. For example, a database administrator (DBA) can create a view of a base table that selects only those spatial features visible to a specific user.

To pass the web user identity from Oracle Fusion Middleware or Oracle Single Sign-On (SSO) to the database, use a secure PL/SQL package that sets the user identity in the database. This PL/SQL package is created by a DBA or application developer and installed in the data source schema. Such a package can have any number of procedures and functions, but it must contain at least the following two procedures:

• set_user(username)

• clear_user()

Whenever a theme is requested from a secured data source, The map visualization component invokes the set_user procedure in the associated PL/SQL package before it executes any data query for the theme, and it invokes the clear_user procedure when the querying process is complete for the theme.

After you have installed the PL/SQL package, you can pass the name of this package to the map visualization component as part of the definition of a data source by using the plsql_package attribute, as shown in Example 1-5.

When you specify a PL/SQL package name in a data source definition, the map visualization component flags the data source as a secure data source, and it automatically invokes the package's set_user and clear_user procedures whenever performing any theme queries on the data source.

Example 1-3 PL/SQL Package for Secure Map Rendering

Example 1-3 shows a PL/SQL package that you can use for secure map rendering. You can create this package in the example MVDEMO schema.

In Example 1-3, set_user and clear_user are two required methods, and get_user is a convenience function that can be used in creating views or for other data access control purposes

After you create the package (which essentially contains the user identity for the current database session), you can set up an elaborate virtual private database that uses this user information (see Oracle Database Security Guide for information about using Oracle Virtual Private Database, or VPD). For simplicity, however, this section does not discuss VPD creation, but shows that you can create views that use this user information to enforce data access control.

For example, in the example MVDEMO schema you can add a column named ACCOUNT_MGR to the existing CUSTOMERS table, and assign an account manager to each customer stored in this table. You can then create a view that returns only customer rows for a specific account manager, as shown in Example 1-4.

CREATE OR REPLACE PACKAGE web_user_info
AS
    PROCEDURE set_user (p_name IN VARCHAR2);
    PROCEDURE clear_user;
    FUNCTION  get_user
        RETURN VARCHAR2;
END;
CREATE OR REPLACE PACKAGE BODY web_user_info
AS
    w_name VARCHAR2 (32767);
 
  PROCEDURE set_user (p_name IN VARCHAR2)
  AS
  BEGIN
     w_name := LOWER (p_name);
  END;
 
  PROCEDURE clear_user
  AS
  BEGIN
      w_name := null;
  END;
 
  FUNCTION get_user
    RETURN VARCHAR2
  AS
  BEGIN
    RETURN w_name;
  END;
END;
/

Example 1-4 View for Secure Map Rendering

CREATE OR REPLACE VIEW customers_view
AS
  SELECT * FROM customers
  WHERE account_mgr = web_user_info.get_user;

You can now define a map visualization component theme based on this view, so that whenever account managers log in and want to view customer data on a map, each will only see his or her own customers.

Example 1-5 Data Source Definition for Secure Map Rendering

<map_data_source name="mvdemo"
                 jdbc_host="system32.example.com"
                 jdbc_sid="mv"
                 jdbc_port="15214"
                 jdbc_user="mvdemo"
                 jdbc_password="password"
                 jdbc_mode="thin"
                 number_of_mappers="3"
                 allow_jdbc_theme_based_foi="true"
                 plsql_package="web_user_info"
   />

1.7.2 Getting the User Name from a Cookie

Sometimes the authenticated user's name is not passed to the map visualization component through a Java EE or OSSO session. such as when you integrate the map visualization component within Application Express (APEX), where authentication is carried out by APEX and the user name is not available through a Java EE or OSSO session. To enable you to work around this issue, The map visualization component also supports getting the user name from a cookie. It is your responsibility to set up the cookie within APEX to hold the authenticated user name.

To ensure that the map visualization component picks up the user name from a named cookie, you must specify the web_user_type attribute in the data source definition (in addition to the mandatory plsql_package attribute). For example, if you want the map visualization component to pick up the user name from a cookie named MON_USER, your secure data source definition should look like Example 1-6.

Example 1-6 Data Source Definition Specifying Cookie Name

<map_data_source name="mvdemo"
                  jdbc_host="system32.example.com"
                  jdbc_sid="mv"
                  jdbc_port="25650"
                  jdbc_user="mvdemo"
                  jdbc_password="LfCDQ6NH59nuV7zbeY5QY06sqN7XhiUQ"
                  jdbc_mode="thin"
                  number_of_mappers="3"
                  allow_jdbc_theme_based_foi="true"
                  plsql_package="web_user_info"
                  web_user_type="MON_USER"
  />

The possible values for the web_user_type attribute are:

• J2EE_USER: tells the map visualization component to get the authenticated user name from a Java EE session

• OSSO_USER: tells the map visualization component to get the authenticated user from an OSSO session.

• <cookie-name>: tells the map visualization component to get the authenticated user from a cookie with the specified name. The cookie name is not case sensitive.

If web_user_type is not specified, the map visualization component first looks for the user name in the Java EE session; and if none is found, it looks for the user name in the OSSO session (if present).

1.7.3 Options for Authenticating Users

How, when, and where users are authenticated depend on the requirements of your application and the setup of your installation. For example, your options include the following:

• Deploy the map visualization component as part of an enterprise portal site, so that end users always first log onto the portal before performing any mapping functions through the map visualization component.

• Deploy the map visualization component on a separate system, and have users authenticate to a central Oracle SSO server.

As long as the HTTP requests reaching the map visualization component contain the authenticated user information, the map visualization component will be able to pass the requests on to the database, and the secure data access approach will work as expected.