4 Distributing Policies

Policy distribution comprises the process used to make configured policies and policy data available to the Policy Decision Point (PDP) such that it can evaluate them and produce a GRANT or DENY authorization decision. This chapter contains the following sections.

4.1 Understanding Policy Distribution

Managing policies and distributing them are distinct operations in Oracle Entitlements Server. Policy management operations are used to define, modify and delete policies in the policy store. The Policy Distribution Component then makes the policies available to a PDP endpoint (Security Module) where the data is used to grant or deny access to a protected resource. Policies are not enforced until they are distributed. Policy distribution may include any or all of the following actions:

  • Reading policies from the policy store.

  • Caching policy objects in the in-memory policy cache maintained by the Security Module for use during authorization request processing.

  • Perserving policy objects in a file-based persistent cache, local to the Policy Distribution Component, that provides independence from the policy store.

Both the central Oracle Entitlements Server Administration Console and the locally-installed (to the protected application) Security Module contain the Policy Distribution Component. This architecture allows two deployment scenarios: the first involves a centralized Policy Distribution Component that can communicate with many Security Modules while the second involves a Policy Distribution Component that is local to, and communicates with, one Security Module. The following sections contain more information.

4.1.1 Using a Centralized Policy Distribution Component

The centralized Policy Distribution Component scenario involves the use of the Policy Distribution Component (within the Administration Console) to act as a server communicating with the Security Module's Policy Distribution Component client. Figure 4-1 illustrates how, in this scenario, the Security Module's Policy Distribution Component client does not communicate with the policy store. The distribution of policies is initiated by the Oracle Entitlements Server administrator and pushed to the Policy Distribution Component client. Currently, data can only be pushed in a controlled manner as described in Section 4.2.1, "Controlled Distribution." This scenario allows for a central Policy Distribution Component that can communicate with many Security Modules.

Figure 4-1 Using Oracle Entitlements Server Policy Distribution Component

Description of Figure 4-1 follows
Description of "Figure 4-1 Using Oracle Entitlements Server Policy Distribution Component"

4.1.2 Using a Local Policy Distribution Component

The local (to the Security Module) scenario involves the Security Module's Policy Distribution Component communicating directly with the policy store. This scenario allows for a local Policy Distribution Component to communicate with one Security Module only. The application administers management operations and decides when the Security Module instance of the Policy Distribution Component will distribute policies or policy deltas. In this deployment, as illustrated in Figure 4-2, the Policy Distribution Component pulls data from the policy store (by periodically checking the policy store for data to be distributed) and sends policy data from the policy store, making it available to the PDP after administrator-initiated policy distribution.

Figure 4-2 Using the Security Module Policy Distribution Component

Description of Figure 4-2 follows
Description of "Figure 4-2 Using the Security Module Policy Distribution Component"

Currently, data can be pulled in either a controlled manner as described in Section 4.2.1, "Controlled Distribution" or a non-controlled manner as described in Section 4.2.2, "Non-Controlled Distribution."

4.2 Defining Distribution Modes

Oracle Entitlements Server handles the task of distributing policies to individual Security Modules that protect applications and services. Policy data is distributed in either a controlled manner or a non-controlled manner. The distribution mode is defined in the jps-config.xml configuration file for each Security Module. The specified distribution mode is applicable for all ApplicationPolicy objects bound to that Security Module. The following sections have more information on the distribution modes.

4.2.1 Controlled Distribution

Controlled distribution is initiated by the Policy Distribution Component, ensuring that the PDP client (Security Module) receives policy data that has been created or modified since the last distribution. In this respect, distribution is controlled by the policy administrator who takes explicit action to distribute the new or updated policy data. (The Policy Distribution Component maintains a versioning mechanism to keep track of policy changes and distribution.) When controlled distribution is enabled, the Security Module can not request distribution of the Policy Distribution Component directly.

Note:

The exception is when a Security Module starts and registers itself with the Policy Distribution Component with a Configuration ID. The policies are distributed to the Security Module based on this registration.

Controlled distribution may be push or pull. With controlled push distribution, the Policy Distribution Component distributes new and updated policy data to the Security Module where the data is stored in a local persistent cache, a file-based cache maintained by the PDP to store policy objects and provide independence from the policy store. With controlled pull distribution, a Security Module (with local Policy Distribution Component) retrieves new and updated policy data from the policy store. Controlled push distribution is the default mode.

The Policy Distribution Component does not maintain constant live connections to its Security Module clients; it will establish a connection before distributing policy to it. Thus, the Security Module is not dependent on the policy store for making policy decisions; it can use its own local cache if the policy store is offline. When the Security Module starts, it will check if the policy store is available. If it is not available, the Security Module will use policy data from the local persistent cache.

A flush distribution of all policy data can be enforced using the flush parameter of the distributePolicy() method. Flush distribution is when the Policy Distribution Component notifies the Security Module to cleanup its locally stored policies in preparation for a new, complete re-distribution of all policy objects in the policy store. See Section 4.4, "Initiating Policy Distribution" for more information.

Caution:

Controlled distribution is supported only on database type policy stores - not on LDAP-based policy stores. If the distribution API is invoked for an LDAP policy store, it will be non-operable.

With controlled distribution, if any portion of the policy distribution operation fails, the entire distribution operation fails. See the appendix in the Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server for information on the Policy Distribution Component configuration properties.

4.2.2 Non-Controlled Distribution

When the PDP client (Security Module) periodically retrieves (or pulls) policies and policy modifications from a policy store, it is referred to as non-controlled distribution. Policy changes are saved to the policy store and non-controlled distribution retrieves them at the next defined interval. Non-controlled distribution is initiated by the Security Module and may retrieve policies that are not completely defined. The policy store must be online and constantly available for non-controlled distribution. Non-controlled distribution is supported on any policy store type.

4.3 Creating Security Module Configurations and Bindings

A Security Module acts as a Policy Decision Point (PDP), receiving a request for authorization, evaluating it based on applicable policies, reaching a decision and returning the decision to the Policy Enforcement Point (PEP), the entity which first made the authorization call. In order for this process to work, the Security Module must be able to retrieve the applicable policies. This is accomplished by binding an instance of a Security Module to the appropriate ApplicationPolicy object. All Security Module instances bound to an ApplicationPolicy object will receive policy data associated with that object when policy distribution is initiated. Each Security Module instance deployed has its configuration information stored in the policy store. The SMEntry object is a pointer to the configuration information of the instance.

Note:

When a Security Module starts, it registers itself with Oracle Entitlements Server. This registration record is added to the Policy Store as a PDPInfoEntry object. Registration records include the Security Module endpoint and the unique identifier that names it. The PDPInfoEntry interface is located in the oracle.security.jps.service.policystore.info.distribution package. This package also contains interfaces used to get information regarding distribution status (DistributionStatusEntry) and regarding distribution status to a particular Security Module (PDPStatusEntry).

To bind a Security Module with an ApplicationPolicy object, create an SMEntry object (representing the Security Module configuration) and bind it to the ApplicationPolicy object. Example 4-1 illustrates how to create an SMEntry object by retrieving an instance of the PolicyStore and getting the ConfigurationManager. This returns the SMEntry object which can be used for binding one or more ApplicationPolicy objects.

Example 4-1 Using the createSecurityModule() Method

//get the policy store and configuration manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationManager configMgr = ps.getConfigurationManager(); 

//create the SM configuration 
SMEntry sm = configMgr.createSecurityModule("MyDomainSM", 
  "MyDomainSM Configuration", "MyDomain Security Module Configuration");

The values of the createSecurityModule() parameters are defined as:

  • smName - MyDomainSM is a unique identifier for the SMEntry object. The Security Module uses this value to connect to the policy store to get the configuration information. The SMEntry object itself does not contain the configuration information; it only points to it.

  • Display Name - MyDomainSM Configuration is an optional, human-readable name for the SMEntry object.

  • Description - MyDomain Security Module Configuration is optional information describing the SMEntry object.

After creating it, bind the SMEntry object to a specific ApplicationPolicy object by calling the ConfigurationBindingManager interface and using the bindSecurityModule() method. Example 4-2 illustrates this step.

Example 4-2 Using the bindSecurityModule() Method

//get the policy store and the configuration binding manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationBindingManager configBindingMgr = 
  ps.getConfigurationBindingManager();
 
//bind Security Module to Application Policy
configBindingMgr.bindSecurityModule("MyDomainSM", "MyAppPolicy");

The values of the bindSecurityModule() parameters are defined as:

  • smName - MyDomainSM is the unique identifier defined for the SMEntry object when it was created.

  • AppID - MyAppPolicy is the unique identifier defined for the ApplicationPolicy object when it was created.

The following sections contain information on the management methods for the Security Module configurations and bindings.

4.3.1 Managing Security Module Configurations

After getting an instance of the ConfigurationManager, you can also delete, retrieve and modify SMEntry objects. Example 4-3 illustrates how to get a specific Security Module configuration by passing the unique identifier of the SMEntry object.

Example 4-3 Using the getSecurityModule() Method

//get the policy store and configuration manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationManager configMgr = ps.getConfigurationManager(); 
 
//get Security Module configuration
SMEntry sm = configMgr.getSecurityModule("MyDomainSM");

MyDomainSM is the unique identifier defined for the SMEntry object when it was created. Additionally, you can retrieve multiple SMEntry objects by calling the getSecurityModules() method and passing to it an array of search criteria using the SecurityModuleSearchQuery class. Example 4-4 illustrates how to remove a Security Module configuration.

Example 4-4 Using the deleteSecurityModule() Method

//get the policy store and configuration manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationManager configMgr = ps.getConfigurationManager(); 
 
//get Security Module configuration
configMgr.deleteSecurityModule("MyDomainSM");

Again, MyDomainSM is the unique identifier defined for the SMEntry object when it was created.

4.3.2 Managing Security Module Bindings

After getting an instance of the ConfigurationBindingManager, you can also retrieve the ApplicationPolicy objects bound to a particular Security Module, or the Security Module bound to a particular ApplicationPolicy. Example 4-5 illustrates how to use the getBoundSecurityModules() method to retrieve the identifier for all SMEntry objects bound to a particular ApplicationPolicy object.

Example 4-5 Using the getBoundSecurityModules() Method

//get the policy store and the configuration binding manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationBindingManager configBindingMgr = 
  ps.getConfigurationBindingManager();
 
//get Security Module bound to Application Policy
List<SMEntry> sms = configBindingMgr.getBoundSecurityModules("MyAppPolicy");

MyAppPolicy is the unique identifier defined for the ApplicationPolicy object when it was created. The getBoundSecurityModules() method returns a list of the unique identifiers for all SMEntry objects bound to the ApplicationPolicy. Example 4-6 illustrates the reverse: retrieving all ApplicationPolicy objects bound to a particular Security Module.

Example 4-6 Using the getBoundApplications() Method

//get the policy store and the configuration binding manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationBindingManager configBindingMgr = 
  ps.getConfigurationBindingManager();
 
//get Application Policy bound to Security Module
List<ApplicationPolicy> apps = 
  configBindingMgr.getBoundApplications("MyDomainSM");

MyDomainSM is the unique identifier defined for the SMEntry object when it was created. The getBoundApplications() method returns a list of the unique identifiers for all ApplicationPolicy objects bound to the SMEntry. Example 4-7 illustrates how to unbind an SMEntry object from its partner ApplicationPolicy object.

Example 4-7 Using the unbindSM() Method

//get the policy store and the configuration binding manager 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ConfigurationBindingManager configBindingMgr = 
  ps.getConfigurationBindingManager();
 
//unbind Application Policy from Security Module
configBindingMgr.unbindSM("MyDomainSM", "MyAppPolicy");

MyDomainSM is the unique identifier defined for the SMEntry object when it was created. MyAppPolicy is the unique identifier defined for the ApplicationPolicy object when it was created.

4.4 Initiating Policy Distribution

Programmatically, policy distribution is performed by calling the distributePolicy() method. This method distributes the policies created for an ApplicationPolicy object to the Security Module that is bound to it. A PDP endpoint receives only those policies which are bound to it. Example 4-8 illustrates how to call the PolicyDistributionManager and use the distributePolicy() method. It also includes code to check the status of the distribution and to wait until the operation is 100% complete.

Example 4-8 Using the distributePolicy() Method

//get the application policy 
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); 
ApplicationPolicy bankApplication = 
  ps.getApplicationPolicy("AcmeBank"); 
 
//get the PolicyDistributionManager 
PolicyDistributionManager pdm = 
  bankApplication.getPolicyDistributionManager(); 
 
//distribute policies 
String distID = pdm.distributePolicy(true); 
 
DistributionStatusEntry status = pd.getDistributionStatus(distID);
 
while (status.getPercentComplete() != 100) {
     Thread.currentThread().sleep(200);
     status = pdm.getDistributionStatus(distID);
}

Note the flush parameter of distributePolicy() is set to true. This indicates that the policies will be distributed in a flush manner. In other words, the Policy Distribution Component informs the Security Module to cleanup its locally stored policies in preparation for a new, complete re-distribution of all policy objects in the policy store. A value of false indicates an incremental distribution of policies when only deltas are distributed.

The distributePolicy() method returns a distribution identifier string that can be passed to the application using the getDistributionStatus() method to query the progress of the distribution.

Note:

distributePolicy() is an asynchronous method; if the application is stopped before the distribution is complete, the distribution process will be interrupted.

A second getDistributionStatus() method takes as input a start time and an end time. It returns a list of DistributionStatusEntry objects. A DistributionStatusEntry object represents the distribution status (complete or in progess) and includes a start time, an end time, the distribution initiater, and whether the distribution is successful or not for each PDP.