13 Management Tasks

This chapter contains information on several management and configuration tasks including configuring Security Modules and the cache, auditing, and migrating policies from different types of policy stores. It contains the following sections.

Section 13.1, "Moving from a Test Environment to Production (T2P)"
Section 13.2, "Using the Policy Simulator"
Section 13.3, "Using FIPS-compliant Security Providers"
Section 13.4, "Managing Audit Tasks"
Section 13.5, "Migrating Policies"
Section 13.6, "Configuring Cache"
Section 13.7, "Logging"
Section 13.8, "Debugging"

13.1 Moving from a Test Environment to Production (T2P)

Test to Production (T2P) is the process of migrating the Oracle Entitlements Server Administration Console from a test environment to a production environment. The T2P process is only applicable to the console component (an application running in a WebLogic Server domain) as Security Modules do not maintain their own data. The following procedure documents the T2P process.

Move the Database, Middleware Homes, and Domain Configuration to the new production environment as documented in Oracle Fusion Middleware Administrator's Guide.
Install Oracle Entitlements Server in the new production environment.
Move Oracle Platform Security Services to the new production environment as documented in Oracle Fusion Middleware Administrator's Guide.

13.2 Using the Policy Simulator

Oracle Entitlements Server provides a feature to simulate a policy from the Administration Console. Policy simulation allows you to troubleshoot, test, analyze the effect of policy changes, and understand how policies on a given application are enforced. The following sections contain more information.

Section 13.2.1, "Understanding Policy Simulation"
Section 13.2.2, "Choosing the Policy Simulation Mode"
Section 13.2.3, "Running the Policy Simulator"

13.2.1 Understanding Policy Simulation

In the simplest policy simulation case, a user and resource-action pair are specified and the following information is retrieved, based on the parameters:

External Roles that would be granted to the principal, and a list of static role grants and Role Mapping Policies.
List of attributes required to evaluate any relevant role or authorization policy.
Value of any evaluation functions that were executed as part of a relevant role or authorization policy.
Value of any dynamic attributes that is part of a relevant role, authorization policy, or obligation. If a dynamic attribute value is unknown, it should be returned as blank so the user can explicitly set it.
The final authorization decision returned (grant or deny), obligations, and the Authorization Policies that were involved.

If attribute values are evaluated as part of the authorization decision, you can perform additional simulations using different values. The sequence of events is:

Specify a principal, resource and action.

The Principal can be a user, a set of External Roles or a set of Application Roles. If External Roles and Application Roles are explicitly specified with the user, role resolution will not be performed.
Simulate the policy.
Specify which attribute to override and provide values for the ones that they want to override.
Re-run the Policy Simulator to see any changed results.

13.2.2 Choosing the Policy Simulation Mode

The Policy Simulator has two modes: Simple and Advanced. The modes have different purposes. Simple mode is typically used for debugging purposes to determine the authorization result for a given Subject and Resource combination. It allows security administrators to understand why a particular user has (or does not have) access to the specified Resource. Advanced mode is for policy simulation - to see what happens, for example, if a user is made a member of a particular set of External Roles and Application Roles. Based on the simulation, security administrators can add or revoke a user's role membership based on the runtime authorization decisions for the specified Resource. Defining values in Simple Mode and clicking Check Access will:

Display the results of the policy evaluation including the authorization decision, obligations (if any), and a list of attributes required to evaluate any relevant role or policy. If an attribute value cannot be retrieved, it will be returned as blank.
Display the set of External Roles to which the specified user belongs. This list facilitates selecting a user's External Roles for running the Policy Simulator in Advanced mode.
Display the Application Roles granted to (or denied) the specified user and the Role Mapping Policies in which the user is specified. The roles may include static and dynamic roles granted by Role Mapping Policies directly or indirectly (through inheritance).
Display the Authorization Policies used for evaluating access.

Defining values in Advanced Mode involves providing 0 or 1 user, a set of External Roles, a set of Application Roles or any combination of the three as Principal. The results displayed are as in Simple Mode except if External Roles and Application Roles are specified; in this case, group resolution will not be computed.

13.2.3 Running the Policy Simulator

The Policy Simulator is displayed as a tab when a configured Application is open for the Administration Console. The tab is only enabled after an Application object has been created and only for the administrator with modify privileges for the Application. The following sections document how to run the Policy Simulator.

Section 13.2.3.1, "Running the Policy Simulator in Simple Mode"
Section 13.2.3.2, "Running the Policy Simulator in Advanced Mode"

13.2.3.1 Running the Policy Simulator in Simple Mode

Figure 13-1 is a screenshot of the Policy Simulator in Simple Mode. Use the procedure in this section to run the Policy Simulator in Simple Mode.

Figure 13-1 Policy Simulator User Interface in Simple Mode

Description of "Figure 13-1 Policy Simulator User Interface in Simple Mode"

Select the Application name that contains the policies and click Open.
Click the Simulation tab.
Click the Simple radio button.

A Simple run is used when defining one user as a Principal.
Search for and select one Principal.
1. Enter Search criteria in the User Name box and click the Search arrow.
  
  The User Search results are displayed.
2. Select the appropriate row in the User Search and click Add to select the user as a Principal.
Search for and select a Resource.
1. Choose the Resource Type (of which the Resource is an instance) from the drop down menu.
2. Choose the appropriate Action Name from the drop down menu.
3. Enter search criteria for the Resource instance name and click the search arrow.
  
  The Resources are displayed. Optionally, further refine the search results by selecting a Policy Domain, entering additional search criteria and clicking the Search arrow.
Add an attribute to the Policy Simulation test.

Attributes are used in Conditions. To evaluate a policy, values are needed for the attributes. If the attribute has a default value, it will be used. (The default value can be overrode here as well.) If no default value, the Simulator will prompt for one.
1. Click the Green Plus to add an attribute.
  
  Use the search pop-up to select a defined attribute and specify the value based on its data type.
2. Enter a Name.
3. Enter a New Value.
Click Check Access.

The Policy Simulator executes. See Section 13.2.2, "Choosing the Policy Simulation Mode" for details on the results.

13.2.3.2 Running the Policy Simulator in Advanced Mode

Figure 13-2 is a screenshot of the Policy Simulator in Advanced Mode. In Advanced Mode, you can define only one user, as well as Application Roles or External Roles. Use the procedure in this section to run the Policy Simulator in Advanced Mode.

Figure 13-2 Policy Simulator User Interface in Advanced Mode

Description of "Figure 13-2 Policy Simulator User Interface in Advanced Mode"

Select the Application name that contains the policies and click Open.
Click the Simulation tab.
Click the Advanced radio button.
Search for and select a User Name, an External Role or an Application Role as the Principal.

At least one of a User Name, External Role or Application Role must de defined.
1. Enter Search criteria in the User Name box and click the Search arrow.
  
  The User Search results are displayed.
2. Select the appropriate row in the User Search and click Add to select the user as a Principal.
3. Click the Green Plus to add an External Role.
  
  The External Roles Search dialog is displayed.
4. Enter Search criteria and click the Search.
  
  The Search Results are displayed.
5. Select the appropriate row(s) in the Search Results and click Add Selected or click Add All to add all results.
  
  The roles are added. In Advanced Mode, the Policy Simulator will not compute the user's External Roles. If that computation is needed, you must specifically add them.
6. Click the Green Plus to add an Application Role.
  
  The Application Roles Search dialog is displayed.
7. Enter Search criteria and click the Search.
  
  The Search Results are displayed.
8. Select the appropriate row(s) in the Search Results and click Add Selected or click Add All to add all results.
  
  The roles are added. In Advanced Mode, the Policy Simulator will not compute the user's Application Roles. If that computation is needed, you must specifically add them.
Search for and select a Resource.
1. Choose the Resource Type (of which the Resource is an instance) from the drop down menu.
2. Choose the appropriate Action Name from the drop down menu.
3. Enter search criteria for the Resource instance name and click the search arrow.
  
  The results are displayed. Optionally, further refine the search results in the Resource Finder by selecting a Policy Domain, entering additional search criteria and clicking the Search arrow.
Add an attribute to the Policy Simulation test.

Attributes are used in Conditions. To evaluate a policy, values are needed for the attributes. If the attribute has a default value, it will be used. (The default value can be overrode here as well.) If no default value, the Simulator will prompt for one.
1. Click the Green Plus to add an attribute.
  
  Use the search pop-up to select a defined attribute and specify the value based on its data type.
2. Enter a Name.
3. Enter a New Value.
Click Check Access.

The Policy Simulator executes. See Section 13.2.2, "Choosing the Policy Simulation Mode" for details on the results.

13.3 Using FIPS-compliant Security Providers

The Federal Information Processing Standard (FIPS) is developed by the United States government to standardize security requirements for cryptography modules. Support for the FIPS allows integration of Oracle Entitlements Server with disparate Java Cryptography Extension (JCE) security providers.

Note:

Security services were limited to the container's default security providers in previous releases.

13.3.1 Installing the JCE Provider

Before configuring the JCE provider, it must be installed and registered. Detailed information on how to do this can be found in the Java Cryptography Extension API Specification and Reference.

Note:

Java Cryptography Extension (JCE) documentation can be downloaded from Oracle Technology Network (OTN) web site by navigating to the following URL:

http://www.oracle.com/technetwork/index.html

13.3.2 Configuring JCE

The following jps-config.xml parameters are used for configuring the JCE security provider. Back up the policy cache files before modifying these JCE provider parameters.

oracle.security.jps.runtime.pd.client.localpolicy.JCEProviderName indicates the JCE provider being used. It is optional and if not specified, the default JDK provider will be used. No default value is defined and any value used is case-sensitive.
oracle.security.jps.runtime.pd.client.localpolicy.CipherKeyLength indicates the key length used for the Cipher class from the specified JCE provider. It is optional and the default value is 128. Only three key lengths (128, 192 and 256) are supported.
oracle.security.jps.runtime.pd.client.localpolicy.CipherModePadding indicates the cipher algorithm name, mode and padding schema used for the Cipher class from the specified JCE provider. The format should be algorithm-name/mode/padding. It is optional, not case-sensitive and the default value is AES/CBC/PKCS5Padding.

13.4 Managing Audit Tasks

Oracle Entitlements Server audits all administrative activities and authorization requests, optionally recording the information to a file. The auditing framework is based on the framework developed for Oracle Platform Security Services. An overview of the Oracle Platform Security Services auditing framework can be found in Oracle Fusion Middleware Application Security Guide. The following information is specific to the auditing functionality in Oracle Entitlements Server.

Section 13.4.1, "Auditing Oracle Entitlements Server Events"
Section 13.4.2, "Configuring Oracle Entitlements Server Administration Server for Auditing"
Section 13.4.3, "Configuring Oracle Entitlements Server Security Modules for Auditing"
Section 13.4.4, "Additional Auditing Information"

Note:

Oracle Entitlements Server will audit decisions resulting from policies configured by itself, Oracle Platform Security Services or any combination thereof.

13.4.1 Auditing Oracle Entitlements Server Events

Table 13-1 lists the events (organized by functional category) that are audited by Oracle Entitlements Server.

Table 13-1 Events Audited in Oracle Entitlements Server

Functional Category	Functional Task
Administration Role Management	AdminRoleCreation AdminRoleDeletion AdminRoleGrant AdminRoleRevoke AdminRoleResActionGrant AdminRoleResActionRevoke
Application Management	ApplicationDeletion
Grant Management	PermissionSetGrant PermissionSetRevocation
PermissionSetManagement	PermissionSetCreation PermissionSetModification PermissionSetDeletion
PolicyDomainManagement	PolicyDomainCreation PolicyDomainDeletion
PolicyManagement	PolicyCreation PolicyModification PolicyDeletion PolicyGrant PolicyRevoke
ResourceManagement	ResourceCreation ResourceModification ResourceDeletion
Role Management	RoleCreation RoleModification RoleDeletion RoleMembershipAdd RoleMembershipRemove
RolePolicyManagement	RolePolicyCreation RolePolicyModification RolePolicyDeletion
Authorization	CheckPermission IsAccessAllowed CheckSubject
ConfigurationBindingManagement	SecurityModuleBinding SecurityModuleUnbinding
ConfigurationManagement	SecurityModuleCreation SecurityModuleModification SecurityModuleDeletion
PolicyDistributionManagement	PolicyDistribution PdpDeregistration purgeDistributionStatus

13.4.2 Configuring Oracle Entitlements Server Administration Server for Auditing

Audit logging is disabled by default. Auditing is configured in jps-config.xml, the configuration file used by Java EE containers that is located in the $DOMAIN_HOME/config/fmwconfig directory. Example 13-1 illustrates how auditing might be configured in jps-config.xml.

Example 13-1 Audit Service Configuration Parameters in jps-config.xml

<!-- Audit Service Instance-->
<serviceInstance name="audit" provider="audit.provider" 
    location="./audit-store.xml">
  <description>Audit Service</description>
  <property name="audit.filterPreset" value="None"/>
  <property name="audit.maxDirSize" value="0"/>
  <property name="audit.maxFileSize" value="104857600"/>
  <property name="audit.loader.jndi" value="jdbc/AuditDB"/>
  <property name="audit.loader.interval" value="15"/>
  <property name="audit.loader.repositoryType" value="File"/>
  <property name="auditstore.type" value="file"/>
</serviceInstance>

Restart the Oracle Entitlements Server Administration Server after making any modifications to the jps-config.xml file. Table 13-2 contains details about the configuration parameters.

Table 13-2 Auditing Parameters in jps-config.xml

Parameter	Description
audit.filterPreset	Enable auditing by choosing from the following values: None (default), Low, Medium, All or Custom
audit.maxDirSize	Controls the size of the directory in which the audit files are written. Takes an integer in bytes.
audit.maxFileSize	Controls the size of the bus stop file in which audit events are written. Takes an integer in bytes.
audit.loader.jndi	When a database is in use, takes a path to the JNDI data source to which audit events are uploaded.
audit.loader.interval	When a database is in use, controls the frequency of the audit loader's upload. Takes an integer in seconds.
audit.loader.RepositoryType	Defines the audit repository type. Takes a value of File or Db. Use `Db` if loading audit records from a file to a data base. If type is database (Db), `audit.loader.jndi` must also be defined. Use `File` if loading audit records from a data base to a file.
auditstore.type	Takes as a value `file` or `db` depending on the audit store type.

13.4.3 Configuring Oracle Entitlements Server Security Modules for Auditing

To configure auditing for Oracle Entitlements Server Security Modules, first apply the Oracle Entitlements Server Bundle Patch 1 (BP1) and then create the audit database.

Note:

See the Oracle Fusion Middleware Release Notes for Microsoft Windows x64 (64-Bit) for information on completing Oracle Entitlements Server audit schema definitions. The procedure can be done before or after creating the audit database.

After completing these steps, use one of the following procedures depending on the deployed Security Module.

Section 13.4.3.1, "Configuring the WebLogic Server Security Module"
Section 13.4.3.2, "Configuring Other Security Modules"

13.4.3.1 Configuring the WebLogic Server Security Module

Create and configure the data source to the audit database, and deploy the data source to the server using the WebLogic Server console.

See Oracle Fusion Middleware Application Security Guide for details.
Restart the server.

Add the following content before the final </serviceInstances> tag in the jps-config.xml file.

In a non JRF domain, jps-config.xml is located in the WLSSM_Client_Domain\config\oeswlssmconfig\AdminServer\ directory. In a JRF domain, jps-config.xml is located in the WLSSM_Client_Domain\config\fmwconfig\ directory.

<serviceInstance name="audit" provider="audit.provider">
  <property name="audit.filterPreset" value="All"/>
  <property name="audit.maxDirSize" value ="0"/>
  <property name="audit.maxFileSize" value ="104857600"/>
  <property name="audit.loader.jndi" value="auditdb"/>
  <property name="audit.loader.interval" value="15" />
  <property name="audit.loader.repositoryType" value="Db" />
</serviceInstance>

Restart the servers.

audit.log is created under the WLSSM_Client_Domain/servers/AdminServer/logs/auditlogs/JPS/ directory.
Run the database set password command to set a password for the audit database.

When prompted, enter the password for your audit schema. See Oracle Fusion Middleware Application Security Guide for details.
Run the audit loader to load the events and actions from the audit.log file to the audit database.

A message that confirms the number of events transferred is displayed after a successful action. See Oracle Fusion Middleware Application Security Guide for details.

13.4.3.2 Configuring Other Security Modules

Add the following content before the final </serviceInstances> tag in the jps-config.xml file (located in the OES_Client11115\oes_sm_instances\SM_Name\config\ directory) to set up the audit database loader.
```
<serviceInstance name="audit" provider="audit.provider" 
    location="./audit-store.xml">
  <description>Audit Service</description>
<property name="audit.loader.jndi" value="jdbc/AuditDB"/>
<property name="audit.loader.interval" value="15"/>
<property name="audit.loader.repositoryType" value="Db"/>
```
where:
- The value of audit.loader.repositoryType must be Db.
- The database schema for the audit loader should be created using the Repository Creation Utility (RCU).
- The datasource being connected to the database should be configured as the value of audit.loader.jndi.
Run the database set password command to set a password for the audit database.

When prompted, enter the password for your audit schema. See Oracle Fusion Middleware Application Security Guide for details.
Run the audit loader to load the events and actions from the audit.log file to the audit database.

A message that confirms the number of events transferred is displayed after a successful action. Be sure to define the -Doracle.instance parameter with the path to the Security Module instance and database details. See Oracle Fusion Middleware Application Security Guide for details.

13.4.4 Additional Auditing Information

The following list collects chapter links in other documents with information regarding the auditing framework.

Introductory material can be found in Oracle Fusion Middleware Security Guide.
You can manage audit policies with the Enterprise Manager user interface or with the WebLogic Scripting Tool (WLST) command-line interface. See Oracle Fusion Middleware Application Security Guide for guidance.
The Oracle Fusion Middleware Audit Framework Reference is in Oracle Fusion Middleware Security Guide.
Additional configuration information is in Oracle Fusion Middleware Security Guide.

13.5 Migrating Policies

This section contains information regarding migrating policies from one type of store to another. It contains procedures for the following:

Section 13.5.1, "Migrating From XML to LDAP"
Section 13.5.2, "Migrating From LDAP to XML"
Section 13.5.3, "Migrating From XML to Database"
Section 13.5.4, "Migrating From Database to XML"

13.5.1 Migrating From XML to LDAP

Following is the procedure to migrate policies from an XML-based policy store to an LDAP-based directory.

Modify jps-config.xml as described in this sub procedure.

Create a serviceInstance for both the source and destination policy stores as illustrated in Example 13-2.

The location of the source policy store instance must be defined as relative to the location of jps-config.xml defined as the value of configFile when using the migrateSecurityStore command. Example 13-2 assumes that jps-config.xml and jazn-data.xml (the source policy store) are located in the same directory.

Example 13-2 XML to LDAP serviceInstances for Source and Destination Policy Stores

<!-- Source XML-based policy store instance -->
   <serviceInstance name="src.xml" provider="policystore.xml.provider" 
      location="./jazn-data.xml">
    <description>File Based Policy Store Service Instance</description>
   </serviceInstance>
 
<!-- Destination LDAP-based policy store instance -->
   <serviceInstance provider="ldap.policystore.provider" 
      name="policystore.ldap.destination">
    <description>Replace: A. myDestDomain and myDestRootName to appropriate 
       values according to your destination LDAP directory structure; 
       B. ldap://myDestHost.com:3060 with the URL and port
       number of your destination LDAP</description>
       <property value="OID" name="policystore.type"/>
       <property value="bootstrap" name="bootstrap.security.principal.key"/>
       <property value="cn=myDestDomain" name="oracle.security.jps.farm.name"/>
       <property value="cn=myDestRootName" 
         name="oracle.security.jps.ldap.root.name"/>
       <property value="ldap://myDestHost.com:3060" name="ldap.url"/>
   </serviceInstance>

Create a serviceInstance corresponding to the bootstrap credential used to access the destination LDAP directory as illustrated in Example 13-3.

Example 13-3 XML to LDAP serviceInstance for Bootstrap Credential

<!-- Bootstrap credentials to access destination LDAP -->
   <serviceInstance location="./bootstrap" provider="credstoressp" 
       name="bootstrap.cred">
     <description>Replace location with the full path of the directory 
      where the bootstrap file cwallet.sso is located; 
      typically found in destinationDomain/config/fmwconfig/bootstrap
      </description>
   </serviceInstance>

Create a jpsContext for both source and destination stores as illustrated in Example 13-4.

Example 13-4 XML to LDAP jpsContext for Source and Destination Policy Stores

<jpsContext name="sourceContext">
   <serviceInstanceRef ref="src.xml"/>
</jpsContext>
 
<jpsContext name="destinationContext">
   <serviceInstanceRef ref="policystore.ldap.destination"/>
</jpsContext>
 
<jpsContext name="bootstrap_credstore_context">
   <serviceInstanceRef ref="bootstrap.cred"/>
</jpsContext>

Start the WebLogic Scripting Tool.

There is no need to connect the WebLogic Scripting Tool to the WebLogic Server as the migration command is an offline command.
Run the WebLogic Scripting Tool migrateSecurityStore command to migrate the policy store and application as follows.
- To migrate the policy store, run:
```
migrateSecurityStore
   (type="policyStore", src="sourceContext", 
    dst="destinationContext", 
    configFile="myDir/jps-config.xml")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
- To migrate the application, run:
```
migrateSecurityStore
   (type="appPolicies", src="sourceContext", 
    dst="destinationContext", 
    configFile="myDir/jps-config.xml", 
    srcApp="sourceApplication", dstApp="destinationApplication", 
    overWrite="true")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
  - The name of the application being migrated is the value of the srcApp parameter. srcApp is a required parameter for type="appPolicies". Without this value, an error message reading The source application is undefined but required to migrate application-specific policies. is displayed and the migration will fail.
  - The name that is assigned to the application in the destination policy store is the value of the dstApp parameter. If this parameter is not passed, the name of the application in the destination store is the same as the name used in the source store.
  - If the overWrite parameter is defined as true, policies specific to the destination application are replaced by policies from the source application. The default value of this parameter is false which migrates only the addictive changes.

13.5.2 Migrating From LDAP to XML

Following is the procedure to migrate policies from an LDAP-based directory to an XML-based policy store.

Modify jps-config.xml as described in this sub procedure.

Create a serviceInstance for both the source and destination policy stores as illustrated in Example 13-5.

Example 13-5 LDAP to XML serviceInstances for Source and Destination Policy Stores

<!-- Source LDAP-based policy store instance -->
   <serviceInstance provider="ldap.policystore.provider" 
      name="policystore.ldap.source">
    <description></description>
    <property value="OID" name="policystore.type"/>
    <property value="bootstrap" name="bootstrap.security.principal.key"/>
    <property value="cn=mySourceDomain" name="oracle.security.jps.farm.name"/>
    <property value="cn=mySourceRootName" 
      name="oracle.security.jps.ldap.root.name"/>
    <property value="ldap://mySourceHost.com:3060" name="ldap.url"/>
   </serviceInstance>
 
<!-- Destination XML-based policy store instance -->
   <serviceInstance name="dst.xml" provider="policystore.xml.provider" 
    location="/scratch/divyasin/WithPSR/jazn-data-fscm.xml">
    <description>File Based Policy Store Service Instance</description>
   </serviceInstance>

Create a serviceInstance corresponding to the bootstrap credential used to access the destination LDAP directory as illustrated in Example 13-6.

Example 13-6 LDAP to XML serviceInstance for Bootstrap Credential

<!-- Bootstrap credentials to access source LDAP -->
   <serviceInstance location="./bootstrap" provider="credstoressp" 
      name="bootstrap.cred">
   <description>Replace location with the full path of the directory where the
      bootstrap file cwallet.sso is located; typically found in
      destinationDomain/config/fmwconfig/bootstrap</description>
   </serviceInstance>

Create a jpsContext for both source and destination stores as illustrated in Example 13-7.

Example 13-7 LDAP to XML jpsContext for Source and Destination Policy Stores

<jpsContext name="sourceContext">
   <serviceInstanceRef ref="policystore.ldap.source"/>
</jpsContext>
 
<jpsContext name="destinationContext">
   <serviceInstanceRef ref="dst.xml"/>
</jpsContext>
 
<jpsContext name="bootstrap_credstore_context">
   <serviceInstanceRef ref="bootstrap.cred"/>
</jpsContext>

Start the WebLogic Scripting Tool.

There is no need to connect the WebLogic Scripting Tool to the WebLogic Server as the migration command is an offline command.
Run the WebLogic Scripting Tool migrateSecurityStore command to migrate the policy store and application as follows.
- To migrate the policy store, run:
```
migrateSecurityStore
   (type="policyStore", src="sourceContext", 
    dst="destinationContext", 
    configFile="myDir/jps-config.xml")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
- To migrate the application, run:
```
migrateSecurityStore
   (type="appPolicies", src="sourceContext", 
    dst="destinationContext", 
    configFile="myDir/jps-config.xml", 
    srcApp="sourceApplication", dstApp="destinationApplication", 
    overWrite="true")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
  - The name of the application being migrated is the value of the srcApp parameter. srcApp is a required parameter for type="appPolicies". Without this value, an error message reading The source application is undefined but required to migrate application-specific policies. is displayed and the migration will fail.
  - The name that is assigned to the application in the destination policy store is the value of the dstApp parameter. If this parameter is not passed, the name of the application in the destination store is the same as the name used in the source store.
  - If the overWrite parameter is defined as true, policies specific to the destination application are replaced by policies from the source application. The default value of this parameter is false which migrates only the addictive changes.

13.5.3 Migrating From XML to Database

Following is the procedure to migrate policies from an XML-based policy store to a database.

Note:

The value of the bootstrap.security.principal.key property needs to be populated with the key generated during reassociation of the policy, credential, and key stores from one repository type to another.

Modify jps-config.xml as described in this sub procedure.

Create a serviceInstance for both the source and destination policy stores as illustrated in Example 13-8.

Example 13-8 XML to Database serviceInstances for Source and Destination Policy Stores

<!-- Source XML-based policy store instance -->
   <serviceInstance name="src.xml" provider="policystore.xml.provider" 
     location="/scratch/divyasin/WithPSR/jazn-data-fscm.xml">
    <description>File Based Policy Store Service Instance</description>
</serviceInstance>
 
<!-- Destination DB-based policy store instance -->
   <serviceInstance provider="ldap.policystore.provider" 
     name="policystore.db.destination">
    <description>DB Based Policy Store Service Instance</description>
     <property name="policystore.type" value="DB_ORACLE"/>
     <property name="jdbc.url" 
       value="jdbc:oracle:thin:@sc.domainexample.com:1722:orcl"/>
     <property name="jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
     <property name="bootstrap.security.principal.key" 
        value="bootstrap_DWgpEJgXwhDIoLYVZ2OWd4R8wOA=" />
     <property name="oracle.security.jps.ldap.root.name" value="cn=jpsTestNode"/>
     <property name="oracle.security.jps.farm.name" value="cn=view_steph.atz"/>
   </serviceInstance>

Create a serviceInstance corresponding to the bootstrap credential used to access the destination LDAP directory as illustrated in Example 13-9.

Example 13-9 XML to Database serviceInstance for Bootstrap Credential

<!-- Bootstrap credentials to access source DB -->
   <serviceInstance location="./bootstrap" provider="credstoressp" 
     name="bootstrap.cred">
     <description>Replace location with the full path of the directory 
        where the bootstrap file cwallet.sso is located; 
        typically found in destinationDomain/config/fmwconfig/</description>
   </serviceInstance>

Create a jpsContext for both source and destination stores as illustrated in Example 13-10.

Example 13-10 XML to Database jpsContext for Source and Destination Policy Stores

<jpsContext name="sourceContext">
   <serviceInstanceRef ref="src.xml"/>
</jpsContext>
 
<jpsContext name="destinationContext">
   <serviceInstanceRef ref="policystore.db.destination"/>
</jpsContext>
 
<jpsContext name="bootstrap_credstore_context">
   <serviceInstanceRef ref="bootstrap.cred"/>
</jpsContext>

Start the WebLogic Scripting Tool.

There is no need to connect the WebLogic Scripting Tool to the WebLogic Server as the migration command is an offline command.
Run the WebLogic Scripting Tool migrateSecurityStore command to migrate the policy store and application as follows.
- To migrate the policy store, run:
```
migrateSecurityStore
   (type="policyStore", src="sourceContext", 
    dst="destinationContext", 
    configFile="/scratch/divyasin/WithPSR/jps-config.xml")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
- To migrate the application, run:
```
migrateSecurityStore
   (type="appPolicies", src="sourceContext", 
    dst="destinationContext", 
    configFile="/scratch/divyasin/WithPSR/jps-config.xml", 
    srcApp="sourceApplication", dstApp="destinationApplication", 
    overWrite="true")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
  - The name of the application being migrated is the value of the srcApp parameter. srcApp is a required parameter for type="appPolicies". Without this value, an error message reading The source application is undefined but required to migrate application-specific policies. is displayed and the migration will fail.
  - The name that is assigned to the application in the destination policy store is the value of the dstApp parameter. If this parameter is not passed, the name of the application in the destination store is the same as the name used in the source store.
  - If the overWrite parameter is defined as true, policies specific to the destination application are replaced by policies from the source application. The default value of this parameter is false which migrates only the addictive changes.

13.5.4 Migrating From Database to XML

Following is the procedure to migrate policies from a database to an XML-based policy store.

Note:

The value of the bootstrap.security.principal.key property needs to be populated with the key generated during reassociation of the policy, credential, and key stores from one repository type to another.

Modify jps-config.xml as described in this sub procedure.

Create a serviceInstance for both the source and destination policy stores as illustrated in Example 13-11.

Example 13-11 Database to XML serviceInstances for Source and Destination Policy Stores

<!-- Source DB-based policy store instance -->
   <serviceInstance provider="policystore.provider" 
     name="policystore.db.source">
    <description>DB Based Policy Store Service Instance</description>
    <property name="policystore.type" value="DB_ORACLE"/>
    <property name="jdbc.url" 
      value="jdbc:oracle:thin:@sc.domainexample.com:1722:orcl"/>
    <property name="jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>
    <property name="bootstrap.security.principal.key" 
        value="bootstrap_DWgpEJgXwhDIoLYVZ2OWd4R8wOA=" />
    <property name="oracle.security.jps.ldap.root.name" value="cn=jpsTestNode"/>
    <property name="oracle.security.jps.farm.name" value="cn=view_steph.atz"/>
</serviceInstance>
 
<!-- Destination XML-based policy store instance -->
   <serviceInstance name="dst.xml" provider="policystore.xml.provider" 
      location="/scratch/divyasin/WithPSR/jazn-data-fscm.xml">
    <description>File Based Policy Store Service Instance</description>
   </serviceInstance>

Create a serviceInstance corresponding to the bootstrap credential used to access the destination XML directory as illustrated in Example 13-12.

Example 13-12 Database to XML serviceInstance for Bootstrap Credential

<!-- Bootstrap credentials to access source and destination stores -->
   <serviceInstance location="./bootstrap" provider="credstoressp" 
      name="bootstrap.cred">
     <description>Replace location with the full path of the directory where 
       the bootstrap file cwallet.sso is located; typically found in
       destinationDomain/config/fmwconfig/</description>
   </serviceInstance>

Create a jpsContext for both source and destination stores as illustrated in Example 13-13.

Example 13-13 Database to XML jpsContext for Source and Destination Policy Stores

<jpsContext name="sourceContext">
   <serviceInstanceRef ref="policystore.db.source"/>
</jpsContext>
 
<jpsContext name="destinationContext">
   <serviceInstanceRef ref="dst.xml"/>
</jpsContext>
 
<jpsContext name="bootstrap_credstore_context">
   <serviceInstanceRef ref="bootstrap.cred"/>
</jpsContext>

Start the WebLogic Scripting Tool for the migration.

There is no need to connect the WebLogic Scripting Tool to the WebLogic Server as the migration command is an offline command.
Run the WebLogic Scripting Tool migrateSecurityStore command to migrate the policy store and application as follows.
- To migrate the policy store, run:
```
migrateSecurityStore
   (type="policyStore", src="sourceContext", 
    dst="destinationContext", 
    configFile="/scratch/divyasin/WithPSR/jps-config.xml")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
- To migrate the application, run:
```
migrateSecurityStore
   (type="appPolicies", src="sourceContext", 
    dst="destinationContext", 
    configFile="/scratch/divyasin/WithPSR/jps-config.xml", 
    srcApp="sourceApplication", dstApp="destinationApplication", 
    overWrite="true")
```
  where the following applies:
  - The name of the corresponding jpsContext (previously created in Step 1) should be passed to the src and dst parameters.
  - The name of the jps-config.xml file (previously modified in Step 1) should be passed to the configFile parameter. The value must be a fully qualified file name with complete path information.
  - The name of the application being migrated is the value of the srcApp parameter. srcApp is a required parameter for type="appPolicies". Without this value, an error message reading The source application is undefined but required to migrate application-specific policies. is displayed and the migration will fail.
  - The name that is assigned to the application in the destination policy store is the value of the dstApp parameter. If this parameter is not passed, the name of the application in the destination store will be the same as the name used in the source store.
  - If the overWrite parameter is defined as true, policies specific to the destination application are replaced by policies from the source application. The default value of this parameter is false which migrates only the addictive changes.

13.6 Configuring Cache

Oracle Entitlements Server offers caching capabilities. The cache settings are configured in the jps-config.xml file. The following sections contain the appropriate information.

Section 13.6.1, "Configuring Decision Caching"
Section 13.6.2, "Configuring Attribute Caching"

13.6.1 Configuring Decision Caching

Authorization decision caching allows Oracle Entitlements Server to cache the result of an authorization call and use that decision in the future, if an identical call is made. The decision cache consists of two hierarchical levels.

The first level (L1) caches subjects used in the authorization calls.
The second level (L2) caches authorization and role mapping decisions for the given subject.

Note:

The decision cache automatically invalidates itself if there is a change in the policy.

The key of the cache is the incoming Subject, Permission and attributes used during policy evaluation. The value of the cache is the decision and obligations.

All parameter names are prefixed with oracle.security.jps.pdp. Example 13-14 illustrates how the decision cache parameters might be set in jps-config.xml.

Example 13-14 XML To Configure Decision Caching

<serviceInstance name="pdp.service" provider="pdp.service.provider">
           …
 <property name="oracle.security.jps.pdp.AuthorizationDecisionCacheEnabled"
   value="true"/>
 <property name="oracle.security.jps.pdp.
   AuthorizationDecisionCacheEvictionCapacity"
   value="1000"/>
 <property name="oracle.security.jps.pdp.
   AuthorizationDecisionCacheEvictionPercentage" 
   value="15"/>
 <property name="oracle.security.jps.pdp.AuthorizationDecisionCacheTTL"
   value="180"/>
           …
</serviceInstance>

Table 13-3 documents the decision caching parameters.

Table 13-3 Decision Caching Parameters

Name	Description	Accepted Values
`oracle.security.jps.pdp.AuthorizationDecisionCacheEnabled`	Optional parameter that specifies whether the policy decision cache should be enabled.	true (default) false
`oracle.security.jps.pdp.AuthorizationDecisionCacheEvictionCapacity`	Optional parameter that specifies the maximum capacity of the L1 cache. If the number of entries exceeds the value, some entries are evicted.	Integer representing number of entries 500 (default)
`oracle.security.jps.pdp.AuthorizationDecisionCacheEvictionPercentage`	Optional parameter that specifies the percentage of entries in L1 cache that have to be evicted when the maximum capacity has been reached. For example, if the maximum capacity is 200 and the value of this parameter is 10 then 20 entries are evicted from the cache.	Integer representing percent of entries 10 (default equals 10%)
`oracle.security.jps.pdp.AuthorizationDecisionCacheTTL`	Optional parameter that specifies a time-to-live value (in seconds) for entries in the L2 cache. It defines how long an authorization decision is cached.	Integer representing time in seconds 60 (default equals 1 minute)

13.6.2 Configuring Attribute Caching

Each passed attribute can be cached if the cached property is defined for it. A corresponding time-to-live (TTL) value must also be defined if cached is enabled. The key of the cache is the attribute URI. The value of the cache is the attribute object. Example 13-15 illustrates how the attribute cache might be set in jps-config.xml.

Example 13-15 XML To Configure Attribute Caching

<propertySet name="ootb.pip.attribute.age.based.on.myattr.rdbms">
    <property name="ootb.pip.attr.type" value="OOTB_PIP_ATTRIBUTE"/>
    <property name="ootb.pip.ref" value="pip.service.ootb.db"/>
    <property name="name" value="myattr"/>
    <property name="query" value=
       "select myattr from test where username=%SYS_USER%"/>
    <property name="cached" value="true"/>
    <property name="TTL" value="60"/>
</propertySet>

Note:

If cached is not defined for the attribute, it will not be cached.

13.7 Logging

Oracle Entitlements Server uses the standard Java package java.util.logging for logging. The name of the logging setup file is logging.properties. It is the standard configuration file for the Java Development Kit (JDK) and it is located (by default) in $JAVA_HOME/jre/lib/.

Note:

Configure the location of logging.properties by running the following on the command line with the actual path based on your install.

-Djava.util.logging.config.file=/path/filename

Java logging defines log levels to control output ranging from FINEST (indicating a highly detailed tracing message) to SEVERE (indicating fatal program errors and the like). Enabling logging at a given level also enables logging at all higher levels. Table 13-4 contains the specific logger properties that can be set to FINE (details for debugging and diagnosing problems) to provide information for purposes of troubleshooting server issues.

Table 13-4 Logging Server Issues

To Troubleshoot...	Set These Properties To FINE
Policy management issues	`oracle.jps.policymgmt`
Basic authorization issues	`oracle.jps.authorization`
Policy distribution issues	`oracle.oes.pd` `oracle.oes.common`
Security Module issues	`oracle.oes.sm`
Specific tool issues (for example, `enroll.sh`)	`oracle.oes.tool`

After modifying logging.properties, ensure the java.util.logging.config.file system property is set by running the following command:

-Djava.util.logging.config.file=/<directory>/logging.properties

Example 13-16 is the default Oracle Entitlements Server logging.properties file.

Example 13-16 Default logging.properties Configuration File

############################################################
# Default Logging Configuration File
# You can use a different file by specifying a filename
# with the java.util.logging.config.file system property.
# For example java -Djava.util.logging.config.file=myfile
############################################################
# Global properties
############################################################
# "handlers" specifies a comma separated list of log Handler
# classes. These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers= java.util.logging.ConsoleHandler, java.util.logging.FileHandler
# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
# Default global logging level.
# This specifies which kinds of events are logged across
# all loggers. For any given facility this global level
# can be overriden by a facility specific level
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
.level= WARNING
############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = /logs/java%u.log
java.util.logging.FileHandler.limit = 50000000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = FINE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
############################################################
# Facility specific properties.
############################################################
# Provides extra control for each logger.
############################################################
# For example, set the com.xyz.foo logger to only log SEVERE
# messages:
oracle.oes.sm.level=FINE
oracle.oes.common.level=FINE
oracle.oes.tool.level=FINE
oracle.oes.pd.level=FINE
oracle.jps.policymgmt.level=FINE
oracle.jps.authorization.level=FINE
oracle.jps.common.level=FINE

13.8 Debugging

Policy debugging allows for analysis of the policy evaluation process for a given authorization call. The debugging capabilities of the Oracle Entitlements Server runtime are collected in the DebugStore which provides (among other information):

Authorization and Role Mapping Policies (and the appropriate policy objects) involved during the evaluation process
Attributes that were evaluated and their values
Results of function invocations
Roles granted or denied the requesting subject
Policy evaluation result (GRANT, DENY, NOT APPLICABLE)
Obligations and Conditions (if applicable)
Failed authentications, missing group memberships and other incorrect identity values

A client can access debugging information in either of the following ways. The first option entails configuring debugging parameters to see the information in a standard debug log. The second option entails overloading the isAccessAllowed_debug() and getRoles_debug() methods. These two methods return an additional DebugInfo parameter which is populated with debug information during policy evaluation. This second option is used by end users as well as the policy simulation tool. The following sections have more information on these options.

Section 13.8.1, "Enabling Debugging By Defining Parameters"
Section 13.8.2, "Enabling Debugging Using Methods"

Section 13.8.3, "Debugging Policy Distribution" contains information on debugging the policy distribution process.

13.8.1 Enabling Debugging By Defining Parameters

The following sections contain information on how to configure debugging parameters and read the debugging logs.

Configuring Logging for Debugging
Searching Logs to Debug Authorization Policies

13.8.1.1 Configuring Logging for Debugging

When policy outcomes are other than expected, it may be useful to enable debugging so that the Security Module's logs will capture all events related to policy decisions. The following sections contain information on how to debug Authorization Policies created using Oracle Entitlements Server and how to debug the Policy Distribution process.

Oracle Entitlements Server uses the standard Java logging framework for capturing debugging details. Logging is the process of notifying an entity of a particular event. In the case of Oracle Entitlements Server, the entity can be a file or the Administration Console, and the event can be debugging information, runtime exceptions, or a record of actions taken by a user. The logging framework is configured based on the Oracle Entitlements Server deployment. More information is in the following sections.

Section 13.8.1.1.1, "Configuring Logging for a Java Security Module"
Section 13.8.1.1.2, "Configuring Logging for a WebLogic Server Security Module"

Note:

The java.util.logging package provides the classes and interfaces of the platform's core logging facilities.

13.8.1.1.1 Configuring Logging for a Java Security Module

The following configurations must be made to enable logging when the Java Security Module is deployed.

Run the following command when you start the Security Module to specify the logging configuration file:
```
-Djava.util.logging.config.file=logging.properties
```
Set the logging level by adding the following lines to the configuration file:
```
oracle.jps.authorization.level=FINEST
oracle.jps.openaz.level=FINEST
oracle.jps.authorization.debugstore.level=FINEST
```
Keep the default level of the first property and set the level of the last two to FINEST; this configuration will log the result of a policy evaluation. Logging levels define the complexity of the logging record and include (from the least complex to the most) FINEST (simple information), FINER, FINE, CONFIG, INFO, WARNING and SEVERE (complex information).

If you don't specify a configuration file, the logging.properties file in $JAVA_HOME/jre/lib/ is used. Example 13-17 illustrates how to configure logging.properties to log information to the Administration Console.

Example 13-17 Configuration for Administration Console Logging

#The messages will we printed to the standard output
handlers=java.util.logging.ConsoleHandler

#The default level for all loggers is INFO
.level=INFO

#Override the default level for OES authorization to FINEST
oracle.jps.authorization.level=FINEST
oracle.jps.openaz.level=FINEST

#Use default formatter to print the messages
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

Example 13-18 illustrates how to configure logging.properties to log information to a file.

Example 13-18 Configuration for File Logging

#The messages will be written to a file
handlers=java.util.logging.FileHandler
 
#The default level for all loggers is INFO
.level=INFO
 
#Override the default level for OES authorization to FINEST
oracle.jps.authorization.level=FINEST
oracle.jps.openaz.level=FINEST
 
#Configure file information. %h – is the user home directory
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

13.8.1.1.2 Configuring Logging for a WebLogic Server Security Module

To enable logging when the WebLogic Server Security Module is deployed, run the following command to specify the logging configuration file when you start the WebLogic Server domain.

startWeblogic.sh -Djava.util.logging.config.file=logging.properties

Tip:

If you specify a relative path, the base directory is the domain home - not the directory where startWeblogic.sh is located

Other configurations relevant to the WebLogic Server Security Module are similar to those defined in Section 13.8.1.1.1, "Configuring Logging for a Java Security Module."

13.8.1.2 Searching Logs to Debug Authorization Policies

The following sections explain how to search for information recorded to the logging file. They include the commands to be run and, in many sections, sample output.

Section 13.8.1.2.1, "Searching for PEP Request Information"
Section 13.8.1.2.2, "Searching Against DebugStore Output"
Section 13.8.1.2.3, "Searching for Security Module Cache Configuration Parameters"
Section 13.8.1.2.4, "Searching for Principals"
Section 13.8.1.2.5, "Searching for Resources and Actions"
Section 13.8.1.2.6, "Searching for the Value of an Attribute"
Section 13.8.1.2.7, "Searching for an Authorization Decision"
Section 13.8.1.2.8, "Searching for the Value of an Obligation"
Section 13.8.1.2.9, "Searching for Static Application Roles"

13.8.1.2.1 Searching for PEP Request Information

Run the following command against the logging file to output PEP Request related information (including the Authentic Identity, the Runtime Resource, the Runtime Action and the Application Context).

grep "PepRequestImpl"

13.8.1.2.2 Searching Against DebugStore Output

Example 13-19 is sample output illustrating what you might find in a log file when the DebugStore logger is enabled. The output includes the name of the Application, the requested Resource, Action, Subject and policies that were evaluated.

Example 13-19 DebugStore Sample Logging Output

========== Start Of Policy Evaluation Info ==========
Application: Library
 Requested Resource Type: LibraryResource
 Requested Resource: books/CrimeAndPunishment
 Requested Resource Present: false
 Requested Action: borrow
 Request Subject Principals:
     class weblogic.security.principal.WLSUserImpl:John
 Effective Roles Granted: [authenticated-role, Member, PrivilegedMember]
 Role-Mapping Policies:
     1.Policy Name: GrantPrivilegedMemberPolicy
     Matched Policy Principals:
         class weblogic.security.principal.WLSUserImpl:John
     Policy Principals Semantics: OR
     Policy Roles: [PrivilegedMember]
     Matched Policy Resources: NONE
     Policy Evaluation Result: NOT_APPLICABLE
     Policy Rules:
        Rule Name: GrantPrivilegedMemberRule
        Rule Effect: GRANT
        Rule Condition: (MembershipLength >= 5)
        Evaluated Rule Attributes and Functions:
          MembershipLength(Dynamic, Integer) = 4
          Rule Evaluation Result: NOT_APPLICABLE
     2.Policy Name: DenyMemberPolicy
     Matched Policy Principals:
         class weblogic.security.principal.WLSUserImpl:John
     Policy Principals Semantics: OR
     Policy Roles: [Member]
     Matched Policy Resources: [.*]
     Policy Evaluation Result: NOT_APPLICABLE
     Policy Rules:
        Rule Name: DenyMemberRule
        Rule Effect: DENY
        Rule Condition: (MemberState = MA)
        Evaluated Rule Attributes and Functions:
          MemberState(Dynamic, String) = CA
          Rule Evaluation Result: NOT_APPLICABLE
 
 Static Role Grants:
     Principal= class oracle.security.jps.service.policystore.ApplicationRole:
         Member, Roles= [PrivilegedMember]
     Principal= class weblogic.security.principal.WLSUserImpl:John, 
         Roles= [Member]
 
 Denied Static Role Grants: NONE
 
 Authorization Policies:
     1.Policy Name: DenyBorrowLibResourcesPolicy
     Matched Policy Principals:
         class oracle.security.jps.service.policystore.ApplicationRole:Member
         class weblogic.security.principal.WLSUserImpl:John
     Policy Principals Semantics: AND
     Matched Policy Resource-Actions:
         Resource = books/.*, Action = borrow
     Policy Obligations: NONE
     Policy Evaluation Result: NOT_APPLICABLE
     Policy Rules:
         Rule Name: DenyBorrowLibResourcesRule
         Rule Effect: DENY
         Rule Condition: (NumBorrowedBooks >= 6)
         Evaluated Rule Attributes and Functions:
             NumBorrowedBooks(Dynamic, Integer) = 2
         Rule Evaluation Result: NOT_APPLICABLE
 
     2.Policy Name: GrantBorrowLibResourcesPolicy
     Matched Policy Principals:
         class oracle.security.jps.service.policystore.ApplicationRole:Member
     Policy Principals Semantics: OR
     Matched Policy Resource-Actions:
         Resource = .*books.*, Action = ANY
         Resource = .*, Action = borrow
     Policy Obligations: NONE
     Policy Evaluation Result: GRANT
     Policy Rules:
         Rule Name: GrantBorrowLibResourcesRule
         Rule Effect: GRANT
         Rule Condition: ((NumBorrowedBooks < 4) && (age() >= 12))
         Evaluated Rule Attributes and Functions:
             NumBorrowedBooks(Dynamic, Integer) = 2
             age(Function, Integer) = 24
         Rule Evaluation Result: GRANT
 ========== End Of Policy Evaluation Info ==========

13.8.1.2.3 Searching for Security Module Cache Configuration Parameters

Run the following command against the logging file to output the cache configuration parameters for a particular Security Module.

grep "AuthorizationDecisionCacheTTL"

The following properties may be returned for this search. If a property does not appear in the log, it is not specified in jps-config.xml. In cases like this, the default value of the property is used.

AuthorizationDecisionCacheTTL defines the time-to-live (in seconds) for the Authorization Decision cache. The default value is 60.
AuthorizationDecisionCacheEvictionPercentage defines the percentage of authorization decisions to drop when the Authorization Decision cache has reached maximum capacity. The default value is 10.
AuthorizationDecisionCacheEvictionCapacity defines the number used to evict the Authorization Decision cache if the decision cache size reaches this size. The default value is 500.
AuthorizationDecisionCacheEnabled specifies whether the Authorization Decision cache is enabled. The default value is true.

Example 13-20 illustrates output for this search.

Example 13-20 Sample Output for Cache Configuration Parameters Search

oracle.security.jps.az.internal.runtime.service.AbstractPDPService
 
FINE: properties : {
oracle.security.jps.pdp.AuthorizationDecisionCacheTTL=60,
oracle.security.jps.pdp.AuthorizationDecisionCacheEvictionPercentage=10,
oracle.secuirty.jps.pdp.AuthorizationDecisionCacheEvictionCapacity=1000,
oracle.security.jps.pdp.AuthorizationDecisionCacheEnabled=true}

13.8.1.2.4 Searching for Principals

Run the following command against the logging file to output the names of Principals that have been received by Oracle Entitlements Server in the form of an authorization request.

grep "Principal:"

Example 13-21 illustrates the output for a Principal search.

Example 13-21 Sample Output for Principal Search

com.bea.security.providers.authorization.asi.AuthorizationProviderImpl isAccessAllowed

FINE:subject: Subject:
     Principal: John
     Principal: Employee
     Principal: Administrator
     Principal: Principal Developer

13.8.1.2.5 Searching for Resources and Actions

Run the following command against the logging file to output the Resources and Actions that have been received by Oracle Entitlements Server in the form of an authorization request.

grep "Resource:"

Example 13-22 illustrates how the information is returned. The defined values are the name of the policy object.

Application = Lib
Resource Type = libraryresourcetype
Resource = Book
Action = borrow

Example 13-22 Sample Output for Resource and Action Search

com.bea.security.providers.authorization.asi.AuthorizationProviderImpl isAccessAllowed

FINE: Resource: resource=Lib/libraryresourcetype/Book, action=borrow

13.8.1.2.6 Searching for the Value of an Attribute

Run the following command against the logging file to output the value of an attribute that has been received by Oracle Entitlements Server in the form of an authorization request.

grep "<name-of-the-attribute>:"
EXAMPLE: grep "NumberOfBorrowedBooksAttribute:"

Example 13-23 illustrates the returned information where the name of the attribute is NumberOfBorrowedBooksAttribute and the value is 2.

Example 13-23 Sample Output for the Value of an Attribute Search

com.bea.security.providers.authorization.asi.ARME.evaluator.EvalSession logDebug
FINE: getAttributeInternal: name: NumberOfBorrowedBooksAttribute; value: 2; 
type: 3

13.8.1.2.7 Searching for an Authorization Decision

Run the following command against the logging file to retrieve an authorization decision that has been stored.

grep "AccessResultLogger"

Example 13-24 illustrates the returned information and confirm that the authorization decision was affirmative.

Example 13-24 Sample Output for Authorization Decision Search

com.bea.security.providers.authorization.asi.AccessResultLogger log
FINE: Subject Subject:
Principal: John
Principal: Employee
Principal: Administrator
Principal: Principal Developer
 privilege borrow resource //app/policy/Lib/Book result PERMIT

13.8.1.2.8 Searching for the Value of an Obligation

On a UNIX system, run the following command against the logging file to output the value of a specific obligation: grep <string_to_find> <filename>.

For example,

grep "adding response attribute:" | grep  "obligations"

Example 13-25 illustrates the returned information indicating that the obligation (named DenyObligation) denies the request when the amount of library books the Principal currently has checked out is more than three; in this case, the Principal has five books checked out.

Example 13-25 Sample Output for Obligation Value Search

com.bea.security.providers.authorization.asi.AuthorizationProviderImpl ARMEisAccessAllowed
FINE: adding response attribute: namespace=oracle.security.oes.authorization. 
 name=obligations value={DenyObligation=
   { reason_part1=Too many borrowed books (max=3), reason_part2=5, }}

13.8.1.2.9 Searching for Static Application Roles

Run the following command against the logging file to output the names of Application Roles granted statically.

grep "AbstractRoleManager" | grep "getGrantedStaticAppRoles"

Example 13-26 illustrates how two static roles are added to the list of principals: an authenticated-role – build-in role and Reader, an Application Role defined in the Application named Library.

Example 13-26 Sample Output for Static Role Search

oracle.security.jps.az.internal.runtime.entitymanager.AbstractRoleManager getGrantedStaticAppRoles(Set)
FINER: RETURN [authenticated-role, 
  ApplicationRoleLibrary/Readeruname:
  cn=Writer,cn=Roles,cn=Lib,cn=akapisni_dwps1_
  view1.atzsrg,cn=JPSContext,cn=jpsTestNode,guid:
  411EBF807CD411E0BF887FB1A0F3878F]

13.8.2 Enabling Debugging Using Methods

isAccessAllowed_Debug and getRoles_Debug are the methods that can be used in your code to return debugging information. DebugInfo is the object returned by the isAccessAllowed_Debug and getRoles_Debug calls. The following information has to be provided to the consumers of the policy debug feature (including the Policy Simulation tool) when overloading these methods:

Roles granted to the requesting subject
Roles denied the requesting subject
Effective roles granted to the requesting subject
Role Mapping and Authorization Policies that match the requesting subject(s), Resource Type, Resource and action (when applicable). Each policy must contain a name, a principal (that matches the user or role subject), a Resource or Resource Expression (that matches the input resource), action or role (depending on the policy type), policy rule (including a rule name, a GRANT or DENY effect, a string representation of the Condition, evaluated attributes and their values (including dynamic, function, and Resource Types) and a rule evaluation result (Grant, Deny, Not Applicable).
Policy evaluation result (Grant, Deny, Not Applicable)
Obligations (for Authorization Policies only)

See the Oracle Fusion Middleware Management Java API Reference for Oracle Entitlements Server for more details.

13.8.3 Debugging Policy Distribution

The Policy Distribution Component uses the policy management Logger interface. To enable debugging for the Policy Distribution Component, change the logging level of the oracle.jps.policymgmt.level property in the logging configuration file to FINEST. The procedure is documented in Section 13.8.1.1, "Configuring Logging for Debugging." The following should also be verified when debugging policy distribution.

Check that the Security Module distribution mode parameter, oracle.security.jps.runtime.pd.client.policyDistributionMode, is correctly defined. See Appendix A, "Policy Distribution Configuration."
When distributing policies in controlled-push or controlled-pull mode, check for the presence of a local cache file. The local cache directory is defined as the value of the oracle.security.jps.runtime.pd.client.localpolicy.work_folder parameter. Within this directory, see sub directories for each policy's XML_CACHE_FILE such as policyA/ and policyB/. Ensure that the time stamp in the cache file matches the time when the last distribution was initiated. See Appendix A, "Policy Distribution Configuration."
When distributing policies in controlled-push mode, ensure that the instance of the Security Module to which the policies are being distributed is displayed on the Application's Policy Distribution page, and that it is synchronized.
Verify that the correct policies are being evaluated by debugging the Security Module side.