Oracle® Fusion Middleware Developer's Guide for Oracle Entitlements Server 11g Release 1 (11.1.1) E14097-04 |
|
Previous |
Next |
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.
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.
Section 4.1.1, "Using a Centralized Policy Distribution Component"
Section 4.1.2, "Using a Local 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
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 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."
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.
Controlled distribution is the default distribution mode. It 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. |
With controlled 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. 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 policy distribution operation fails, the entire policy distribution fails. By default, controlled distribution is disabled.
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. Non-controlled distribution makes policy changes available as soon as they are saved to the policy store. Non-controlled distribution is initiated by the Security Module and may retrieve policies that are not yet complete. The policy store must be online and constantly available for non-controlled distribution. Non-controlled distribution is supported on any policy store type.
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 (dependent on the mode of distribution) 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 |
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.
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.
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.
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:
|
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.