Domain Configuration: Setting Up an Application Session Service to Work with OPSS and Oracle Fusion Middleware

This section describes the prerequisites and configuration required for an application to use an application session service.

This section includes the following topics:

Prerequisites

To use Real Application Security, both the application session service and OPSS must be deployed and configured in a Oracle Fusion Middleware’s Java EE container.

For WebLogic server, the prerequisites include:

A JRF based WLS domain (OPSS is built-in) certified with the Oracle database 12c JDBC driver. The required JDBC jars could be many, not just one driver jar depending on the features you need (UCP, I18N, SQLXML and so forth).
Oracle Database 12c Release 1 (12.1) and later

For WebLogic server 10.3.6 and 12.1.2 JRF release (part of Oracle Fusion Middleware), the JDBC driver shipped is not Oracle Database 12c compatible. You must obtain the Oracle Database 12c JDBC jars (ojdbc6.jar or ojdbc7.jar and other matched jars depending on the features you need), and add these jars to the front of your WebLogic Server’s classpath. For detailed instruction, see Administering JDBC Data Sources for Oracle WebLogic Server, Section B.

If there is version mismatch between the JDBC driver and the database, the Real Application Security filter initialization fails with an error message. For example,

If the Oracle Database 11g JDBC driver is being used with Oracle Database 12c, the following error message appears in the server log: Fail to initialize RAS session manager due to method missing.
If the Oracle Database 12c JDBC driver is being used with Oracle Database 11g, the following error message appears in the server log: ORA-00439: feature not enabled: Fusion Security.

Manual Configuration

Follow these manual configuration steps for an application to use an application session service. These steps should work for both WebLogic 10.3.6 and 12.1.2, JRF release.

Install the Real Application Security jars.

Copy the xsee.jar and xs.jar (ORACLE_HOME/jlib/) to a common directory that applications can consume. For WebLogic, a good location is DOMAIN_HOME/lib. This allows Real Application Security jars to be shared by many applications deployed in the same domain.
Create a Real Application Security session manager credential.

As discussed in “About Application Configuration of the Application Session Filter”, a session manager’s credential must be created in OPSS’s credential store. This can be done using an OPSS script. For details about how to use OPSS script, see the section about the OPSS script in Oracle Application Server Containers for J2EE Security Guide.
```
createCred(map='oracle.rdbms.ras', key='default', user='myUsr', password='myPassword')
```
The session manager’s credential is stored in the default credential store, which is configured for the domain. The map name must be oracle.rdbms.ras, which is predefined for the Real Application Security application session service. This is fixed and cannot be changed.
Grant code permission to the Real Application Security jar files.

As discussed in “About Deployment”, the CSF permission must be granted to the xsee.jar file. This is also done using OPSS script.
```
grantPermission(codeBaseURL='file:${domain.home}/lib/xsee.jar', permClass='oracle.security.jps.service.credstore.CredentialAccessPermission',  permTarget='context=SYSTEM,mapName=oracle.rdbms.ras,keyName=*', permActions='read')
```
Note that the above keyName (*) is for all keys. No further grants are needed for a non-default key, if it is created for a specific application.
Configure web.xml, invoke Real Application Security APIs (attach/detach), and build/deploy the application. See Example: Application Session Filter Sample Configuration to see how web.xml is configured.

These are standard Java EE development procedures.

If the attachSessionPrivileged API is invoked in the application code, SessionCodePermission must be granted to the application code as discussed in “About the Privilege Elevation API”. That is similar to step 3. Here is an example:
```
grantPermission(codeBaseURL='file:${domain.home}/servers/DefaultServer/tmp/_WL_user/MyWar/pi47ig/war/WEB-INF/lib/trusted.jar', permClass=' oracle.security.xs.ee.session.SessionCodePermission',  permTarget=' MY_NS_DROLE, permActions='attach')
grantPermission(codeBaseURL='file:${domain.home}/lib/xsee.jar', permClass=' oracle.security.xs.ee.session.SessionCodePermission',  permTarget=' MY_NS_DROLE, permActions='attach')
```
OPSS scripts require that the WLS administrative server is running. This manual approach only supports online configuration. Step 4 is always the responsibility of the application administrator, while Steps 1 through 3 can be automated as discussed in “About Automatic Configuration”.

About Automatic Configuration

With Oracle Fusion Middleware, you can use a configuration utility to configure common settings for a group of applications. For WebLogic, this is the domain configuration wizard. In a future WLS release (release 12.1.3), the Steps 1 through 3 (in “Manual Configuration”) could be automated by this configuration wizard. This automatic approach also has the advantage of supporting offline configuration (when the administrative server is not running).

When the configuration wizard is started (<ORACLE_HOME>/oracle_common/common/bin/config.sh), the following user interfaces (UIs) will be shown to prompt for Real Application Security configuration information.

In the first UI, the application session service is shown as one of the Oracle Fusion Middleware features for selection. Once selected, its dependency (OPSS, part of JRF) is automatically selected.
In the second UI, you are prompted to enter the default session manager’s credential.

There is no UI for granting code permission. This is automatically done by merging a predefined xml file to the domain’s system-jazn-data.xml file. The predefined xml file contains all the Real Application Security code permission grants that are needed.

If the administrator decides to use a different session manager for an application, then the administrator must complete manual Step 2 or add a special key name from the UI. The same key name must be passed to the application’s web.xml. In this case, the map name (store name) is still fixed as oracle.rdbms.ras, and you do not need to grant code permission because all keys have already been granted internally.