Many of the application programming interfaces (API) documented in Chapter 2, "Constructing A Policy Programmatically" contain methods that allow for managing policy objects programmatically. This chapter contains information on how to use those methods. It contains the following sections:
Section 3.2, "Managing Objects Created at the PolicyStore Scope"
Section 3.3, "Managing Objects Within the ApplicationPolicy Scope"
Section 3.4, "Managing Objects within the PolicyDomainEntry Scope"
The policy store contains three scoping levels under which policies are managed: the top-level Policy Store itself, the Application (Application Policy), and the Policy Domain.
A PolicyStore
object represents the entire policy store. Application policies and system administration policies are managed at this scope. Any policy management activity must be preceded by retrieving an instance of the PolicyStore
object as documented in Section 2.2.1, "Accessing the Policy Store." The policy store location, the account and the account password used to access it are defined in the jps-config.xml
configuration file. Example 3-1 illustrates how this information is defined in jps-config.xml
during installation.
Example 3-1 Definition of a Policy Store in jps-config.xml
<jpsConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http:// xmlns.oracle.com/oracleas/schema/jps-config-11_0.xsd"> <serviceProviders> <serviceProvider type="POLICY_STORE" name="policy.db" class="oracle.security.jps.internal.policystore.OPSSPolicyStoreProvider" /> </serviceProviders> <serviceInstances> <serviceInstance name="policystore.db" provider="policy.db"> <property name="repository.type" value="database"/> <property name="jdbc.url" value="jdbc:oracle:thin:@10.182.219.120:1521:mc"/> <property name="jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/> <property name="jdbc.user" value="wcai"/> <property name="jdbc.password" value="password"/> <property name="root.dn" value="cn=farm,cn=JPSContext,cn=jpsroot"/> <property name="pd.timer.enabled" value="false"/> </serviceInstance> </serviceInstances> <jpsContexts default="default"> <jpsContext name="default"> <serviceInstanceRef ref="policystore.db"/> </jpsContext> </jpsContexts> </jpsConfig>
Note:
See the Oracle Fusion Middleware Security Guide for more information on the jps-config.xml
configuration file. Parameters specific to Oracle Entitlements Server are documented in the Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server.
An ApplicationPolicy
object represents an application being secured by Oracle Entitlements Server. Within an ApplicationPolicy
, programmatic objects used to define policies (Resource Types, Functions, Attributes, Application Roles and Role Policies) are managed.
Note:
Optionally, these programmatic objects can also be managed by creating one (or multiple) PolicyDomainEntry
objects within the ApplicationPolicy
as described in Chapter 5, "Delegating Policy Administration."
An optional PolicyDomainEntry
object can be created to partition, and serve as a management point for, Resources, Permission Sets and completed policy definitions. One PolicyDomainEntry
can be used to maintain all policies securing an application or multiples can be used to organize policy components as needed. Policies are defined using objects created in its parent ApplicationPolicy
object. Policy Domains are invisible to each other, even those in a parent-child relationships. Thus, the Resources, Permission Sets and Policies managed in a Policy Domain can only be used in that Policy Domain. More information on the Policy Domain can be found in Chapter 5, "Delegating Policy Administration."
Note:
Administration Roles are managed at all scope levels depending on where they were created. For information on creating and managing Administration Roles, see Chapter 5, "Delegating Policy Administration."
Within the PolicyStore
object, policy components securing different applications are organized within one or more second level ApplicationPolicy
objects. Section 2.2.2, "Creating an Application Policy" documented how to create an ApplicationPolicy
object. You can also delete and retrieve ApplicationPolicy
objects with the methods found in the PolicyStore
interface.
Note:
The ApplicationPolicy
object is represented in the Oracle Entitlements Server Administration Console as an Application.
Example 3-2 illustrates how to delete an ApplicationPolicy
object named Trading using the deleteApplicationPolicy()
method.
Example 3-2 Using deleteApplicationPolicy() Method
PolicyStore ps = ctx.getServiceInstance(PolicyStore.class); ApplicationPolicy ap = ps.deleteApplicationPolicy("Trading");
The value of the deleteApplicationPolicy()
parameter is Trading, the unique identifier defined as the Name when the object was initially created. The getApplicationPolicy()
method will retrieve the ApplicationPolicy
object using the same Name value. Additionally, you can retrieve many ApplicationPolicy
objects by calling the getApplicationPolicies()
method and passing search criteria to it using the ApplicationPolicySearchQuery
class.
Caution:
Deleting an ApplicationPolicy
object deletes all child objects created within it.
Within the ApplicationPolicy
object, policy components are organized within one or more PolicyDomainEntry
objects. Other components managed at the ApplicationPolicy
level include Resource Types, Application Roles, Role Policies and Extensions (Functions and Attributes). The following sections have more information.
Section 3.3.4, "Managing Role Mapping Policy (RolePolicyEntry) Objects"
Section 3.3.5, "Managing AttributeEntry and FunctionEntry Objects"
Section 5.7, "Delegating with a Policy Domain" documents how to create an optional PolicyDomainEntry
object that can be used to help partition policy definition components. You can also delete and retrieve PolicyDomainEntry
objects with the methods found in the ApplicationPolicy
interface. To manage a Policy Domain, obtain an instance of the PolicyDomainManager
and call the appropriate method. Example 3-3 illustrates how to delete a PolicyDomainEntry
created within the Trading ApplicationPolicy
. mydomain
is the unique identifier defined as the Name when the object was initially created.
Example 3-3 Using deletePolicyDomain() Method
PolicyDomainManager domainMgr = Trading.getPolicyDomainManager(); PolicyDomainEntry pdEntry = domainMgr.deletePolicyDomain("mydomain");
Example 3-4 illustrates how to modify the Display Name and Description of the PolicyDomainEntry
using the setDescription()
and setDisplayName()
methods available through that interface.
Example 3-4 Using modifyPolicyDomain() Method
PolicyDomainManager domainMgr = Trading.getPolicyDomainManager(); PolicyDomainManager domainMgr = Trading.getPolicyDomainManager(); PolicyDomainEntry pdEntry = domainMgr.getPolicyDomain("mydomain"); // modify PolicyDomainEntry displayName and description pdEntry.setDescription("This is description."); pdEntry.setDisplayName("Domain Display Name"); // persist the change domainMgr.modifyPolicyDomain(pdEntry);
Example 3-5 illustrates how to retrieve a PolicyDomainEntry
using mydomain
, the unique identifier defined as the Name when the object was initially created.
Example 3-5 Using getPolicyDomain() Method
PolicyDomainManager domainMgr = Trading.getPolicyDomainManager(); PolicyDomainEntry PDEntry = domainMgr.getPolicyDomain("mydomain");
Additionally, you can retrieve many PolicyDomainEntry
objects by calling the getPolicyDomains()
method and passing search criteria to it using the PolicyDomainSearchQuery
class.
Section 2.2.3, "Defining Resource Types" documented how to create a ResourceTypeEntry
object. You can also delete, modify and retrieve ResourceTypeEntry
objects by getting an instance of the ResourceTypeManager
(using getResourceTypeManager()
in the ApplicationPolicy
interface) and calling the appropriate method.
Note:
The ResourceTypeEntry
object is represented in the Oracle Entitlements Server Administration Console as a Resource Type.
Example 3-6 deletes a ResourceTypeEntry
named TradingResType within the Trading ApplicationPolicy
object.
Example 3-6 Using the deleteResourceType() Method
//get the ResourceTypeManager ResourceTypeManager resourceTypeManager = Trading.getResourceTypeManager(); //delete the Resource Type resourceTypeManager.deleteResourceType("TradingResType", "true");
Trading is the name of the ApplicationPolicy
under which the ResourceType
object was created. TradingResType is the name of the ResourceType
object being deleted. The values of the deleteResourceType()
parameters are defined as:
Name - TradingResType is the unique identifier defined as the Name when the object was initially created.
cascadeDelete - This parameter takes a value of true or false and governs how the ResourceType
and related objects would be removed. If true, the ResourceType
and all instantiated ResourceEntry
objects are deleted. If false, and any ResourceEntry
instances exist, the operation fails and PolicyStoreOperationNotAllowedException
is thrown.
The getResourceType()
method can be used to retrieve a ResourceTypeEntry
, also by Name. You can retrieve many ResourceTypeEntry
objects by calling the getResourceTypes()
method and passing search criteria to it using the ResourceTypeSearchQuery
class.
Section 2.3.1, "Creating Application Roles" documents how to create an AppRoleEntry
object and assign users to it. (When the AppRoleEntry
object is then specified as a principal for a particular policy, all users assigned to the role are governed by that policy.) You can also delete, modify and retrieve AppRoleEntry
objects by getting an instance of the AppRoleManager
(using getAppRoleManager()
in the ApplicationPolicy
interface) and calling the appropriate method.
Note:
The AppRoleEntry
object is represented in the Oracle Entitlements Server Administration Console as an Application Role. Application Roles are searched for, and consolidated, under the Role Catalog branch of the Administration Console navigation tree. A Role Catalog is a user interface grouping of all activities related to managing Application Roles and its characteristics. A Role Category is a tag you can assign to a role for ease of management.
Example 3-7 removes an AppRoleEntry
named TradingAppRole from the policy store. TradingApp is the name of the ApplicationPolicy
under which the AppRoleEntry
object was created.
Example 3-7 Using deleteAppRole() Method
//get the AppRoleManager AppRoleManager appRoleManager = Trading.getAppRoleManager(); //delete the AppRoleEntry appRoleManager.deleteAppRole("TradingAppRole", "true");
The values of the deleteAppRole()
parameters are defined as:
Name - TradingAppRole is the unique identifier defined as the Name when the object was initially created.
cascadeDelete - This parameter takes a value of true or false and governs how the AppRoleEntry
and related objects would be removed. If true, the AppRoleEntry
is deleted and removed from all policies referencing it. (If it is the only role referenced by a policy, the policy is also removed.) If false, and the role is referenced in any policy, the operation fails and a PolicyStoreOperationNotAllowedException
is thrown.
The getAppRole()
method can be used to retrieve an AppRoleEntry
by passing to it the Name. You can retrieve many AppRoleEntry
objects by calling the getAppRoles()
method and passing search criteria to it using the AppRoleSearchQuery
class. Additionally, you can modify an AppRoleEntry
with the modifyAppRole()
method, retrieve members granted directly to an Application Role with the getDirectAppRoleMembers()
method, and retrieve Application Role hierarchies for a principal with the getDirectGrantedAppRoles()
method.
Granting of the AppRoleEntry
to one or more PrincipalEntry
objects can be achieved statically using the grantAppRole()
method or dynamically using a Role Mapping Policy.
Note:
A Role Mapping Policy may define a grantee (User, Group), a target (resource, resource name expression), and an (optional) Condition. Authorization Policies are used to map Application Roles to access rights. An Authorization Policy may define a principal (User, Group, Application Role), a target (resource, entitlement set, resource name expression), a condition, and an obligation. See Section 3.3.4, "Managing Role Mapping Policy (RolePolicyEntry) Objects" for more information.
Revocation of the AppRoleEntry
can be done using the revokeAppRole()
method.
Application Roles also use inheritance and hierarchy. Roles can be created in a hierarchy such that a Principal assigned to a role (using a Role Mapping Policy) also inherits any child roles (as long as it is not prohibited by other configured policies). Users who are granted actions based on a child role inherit the actions from that role's parents. Users denied actions based on a parent role are also denied actions for that role's children.
Section 2.3.2, "Creating Role Mapping Policies" documents how to create a RolePolicyEntry
object. You can also delete, modify and retrieve RolePolicyEntry
objects by getting an instance of the RolePolicyManager
(using getRolePolicyManager()
in the ApplicationPolicy
interface) and calling the appropriate method. Example 3-8 illustrates how to remove a RolePolicyEntry
named TellerRoleMapping within the TellerApp ApplicationPolicy
object.
Example 3-8 Using the deleteRolePolicy() Method
//get the RolePolicyManager RolePolicyManager rolePolicyManager = tellerApp.getRolePolicyManager(); //delete the RolePolicyEntry rolePolicyManager.deleteRolePolicy("TellerRoleMapping");
Example 3-9 illustrates how to revise a RolePolicyEntry
by passing a revised instance of the object to the modifyRolePolicy()
method.
Example 3-9 Using the modifyRolePolicy() Method
//get the RolePolicyManager RolePolicyManager rolePolicyManager = tellerApp.getRolePolicyManager(); // get the policy RolePolicyEntry rolePolicy = rolePolicyManager.getRolePolicy("TellerRoleMapping"); // change description rolePolicy.setDescription("the policy is changed!"); //persist the change rolePolicyManager.modifyRolePolicy(rolePolicy);
The getRolePolicy()
method can be used to retrieve a RolePolicyEntry
by passing to it the Name. You can retrieve many RolePolicyEntry
objects by calling the getRolePolicies()
method and passing to it an array of search criteria using the RolePolicySearchQuery
class.
Section 2.3.3, "Creating Attribute and Function Definitions" documents how to create an AttributeEntry
definition and a FunctionEntry
definition for (optional) use in policy Conditions and Obligations. You can also delete, modify and retrieve these objects by calling the ExtensionManager
. The following sections contain more information.
Example 3-10 retrieves an AttributeEntry
object named Phone from the policy store. bankApplication refers to the ApplicationPolicy
object from which the ExtensionManager
is instantiated. Phone
refers to the unique identifier defined as the Name when the AttributeEntry
object was initially created.
Example 3-10 Using the getAttribute() Method
//get the ExtensionManager ExtensionManager extMgr = bankApplication.getExtensionManager(); //retrieve the attribute AttributeEntry<? extends DataType> oneAttrEntry = extMgr.getAttribute("Phone");
You can also retrieve many AttributeEntry
objects by calling the getAttributes()
method and passing search criteria to it using the AttributeSearchQuery
class. Example 3-11 deletes the AttributeEntry
object from the ApplicationPolicy
.
Example 3-11 Using the deleteAttribute() Method
//get the ExtensionManager ExtensionManager extMgr = bankApplication.getExtensionManager(); //retrieve the attribute AttributeEntry<? extends DataType> oneAttrEntry = extMgr.deleteAttribute("myattr", false);
Caution:
Remove the applicable AttributeEntry
from any policies in which it is referenced before running the deleteAttribute()
method. If the attribute is in use, it will not be deleted and a PolicyStoreOperationNotAllowedException
will be thrown. For this release, the cascadeDelete
parameter must be false.
To modify an AttributeEntry
object, pass to the ExtensionManager
the object with new, modified values using the modifyAttribute()
method. Use the methods available in the AttributeEntry
interface to set the new, modified values before passing the object.
Example 3-12 retrieves a FunctionEntry
object named ClientType from the policy store. bankApplication refers to the ApplicationPolicy
object from which the ExtensionManager
is instantiated. ClientType
refers to the unique identifier defined as the Name when the FunctionEntry
object was initially created.
Example 3-12 Using the getFunction() Method
//get the ExtensionManager ExtensionManager extMgr = bankApplication.getExtensionManager(); //retrieve the function FunctionEntry oneFuncEntry = extMgr.getFunction("ClientType");
You can also retrieve many FunctionEntry
objects by calling the getFunctions()
method and passing search criteria to it using the FunctionSearchQuery
class. Example 3-13 deletes the FunctionEntry
object from the ApplicationPolicy
.
Example 3-13 Using the deleteFunction() Method
//get the ExtensionManager ExtensionManager extMgr = bankApplication.getExtensionManager(); //remove the function extMgr.deleteFunction("ClientType", false);
To modify a FunctionEntry
object, pass to the ExtensionManager
the object with new, modified values using the modifyFunction()
method. Use the methods available in the FunctionEntry
interface to set the new, modified values before passing the object.
Section 2.2.4, "Instantiating a Resource" documents how to instantiate a ResourceEntry
object from a ResourceTypeEntry
object. You can also delete, modify and retrieve ResourceEntry
objects by getting an instance of the ResourceManager
(using getResourceManager()
in the ApplicationPolicy
interface, or in the PolicyDomainEntry
interface if using Policy Domains to delegate administration) and calling the appropriate method.
Note:
The ResourceEntry
object is represented in the Oracle Entitlements Server Administration Console as a Resource.
Example 3-14 illustrates how to retrieve a ResourceEntry
object. The getResource()
method is defined in the ResourceFinder
interface which is extended by the ResourceManager
interface. By passing to the method the defined name of a resource type and the resource, a ResourceEntry
will be returned.
Example 3-14 Using the getResource() Method
//get the ResourceManager ResourceManager resMgr = domain.getResourceManager(); //retrieve the Resource ResourceEntry checkingRes = resMgr.getResource ("WidgetType", "WidgetResource")
Example 3-15 removes a checking account ResourceEntry
. domain
refers to the PolicyDomainEntry
object from which the ResourceManager
is being retrieved. By passing to the method the defined name of a resource type and the resource, a ResourceEntry
will be returned.
Example 3-15 Using deleteResource() Method
//get the ResourceManager ResourceManager resMgr = domain.getResourceManager(); //remove the Resource resMgr.deleteResource("WidgetType", "WidgetResource", true);
The values of the deleteResource()
parameters are defined as:
Resource Type Name - WidgetType is the unique identifier defined as the Name when the ResourceTypeEntry
was initially created.
Name - WidgetResource is the unique identifier defined as the Name when the ResourceEntry
was initially created.
cascadeDelete - This parameter takes a value of true or false and governs how the ResourceEntry
and related objects would be removed. If true, the ResourceEntry
is removed from any policies that reference it. If it is the only object being referenced by a policy, the policy is also deleted. If false, and ResourceEntry
instances exist, the operation fails and PolicyStoreOperationNotAllowedException
is thrown.
You can also modify a ResourceEntry
object by calling the modifyResource()
method and passing to it a handle to the object itself in the form of an EntryReference
and an array of modifications. Example 3-16 illustrates this.
Example 3-16 Using modifyResource() Method
//get the ResourceManager ResourceManager resMgr = domain.getResourceManager(); // get resource object ResourceEntry resEntry = resMgr.get("WidgetType", "WidgetResource"); // create attrName Attribute with value of 'test' AttributeEntry attrEntry1 = new BasicAttributeEntry("testAttr", new OpssString("test")); resEntry.addResourceAttribute(attrEntry1); // persist the change resMgr.modifyResource(resEntry);
Section 2.3.4, "Defining Permission Sets" documents how to organize one or more ResourceActionsEntry
objects in a PermissionSetEntry
object by calling the PermissionSetManager
and using the createPermissionSet()
method. You can also delete, modify and retrieve PermissionSetEntry
objects by getting an instance of the PermissionSetManager
(using getPermissionSetManager()
in the ApplicationPolicy
interface, or in the PolicyDomainEntry
interface if using Policy Domains to delegate administration) and calling the appropriate method.
Note:
The PermissionSetEntry
object is represented in the Oracle Entitlements Server Administration Console as an Entitlement.
Example 3-17 illustrates how to modify a PermissionSetEntry
by removing two ResourceActionsEntry
objects. domain
refers to the Policy Domain under which the policy was created, and from which the PermissionSetManager
is retrieved.
Example 3-17 Modifying a PermissionSetEntry
// get the PermissionSetManager PermissionSetManager psMgr = domain.getPermissionSetManager(); // get the PermissionSet PermissionSetEntry permSetEntry = psMgr.getPermissionSet("myPermSet"); // get the ResourceActionEntries from PermissionSet List<ResourceActionsEntry> resultResActions = permSetEntry.getResourceActionsList(); // delete the first ResourceActionsEntry object permSetEntry.deleteResourceActions(resultResActions.get(0)); // persist the change psMgr.modifyPermissionSet(permSetEntry);
Example 3-18 illustrates how to remove a PermissionSetEntry
object.
Example 3-18 Using the deletePermissionSet() Method
//get the PermissionSetManager PermissionSetManager psMgr = domain.getPermissionSetManager(); //remove PermissionSetEntry psMgr.deletePermissionSet("RptsPermSet", "true");
The values of the deletePermissionSet()
parameters are defined as:
Name - RptsPermSet is the unique identifier defined as the Name when the object was initially created.
cascadeDelete - This parameter takes a value of true or false and governs how the PermissionSetEntry
and related objects would be removed. If true, the PermissionSetEntry
is removed from any policies that reference it. If it is the only object being referenced by a policy, the policy is also deleted. If false, and PermissionSetEntry
instances are referenced, the operation fails and PolicyStoreOperationNotAllowedException
is thrown.
The getPermissionSet()
method can be used to retrieve a PermissionSetEntry
, also by Name. You can retrieve many PermissionSetEntry
objects by calling the getPermissionSets()
method and passing search criteria to it using the PermissionSetSearchQuery
class. modifyPermissionSet()
will persist any changes defined in the PermissionSet
object used as input.
Section 2.2.8, "Defining the Policy" documents how to create a PolicyEntry
object by consolidating all the pieces needed to create the access control - including, but not limited to, a PolicyRuleEntry
, a ResourceActionsEntry
, and a PrincipalEntry
; after obtaining an instance of the PolicyManager
, use the createPolicy()
method. You can also delete, modify and retrieve PolicyEntry
objects by getting an instance of the PolicyManager
(using getPolicyManager()
in the ApplicationPolicy
interface, or in the PolicyDomainEntry
interface if using Policy Domains to delegate administration) and calling the appropriate method.
Example 3-19 illustrates how to modify the values of the Display Name and Description parameters of the PolicyEntry
. domain
refers to the Policy Domain under which the policy was created, and from which the PolicyManager
is retrieved.
Example 3-19 Using modifyPolicy() Method
// get the Policy PolicyManager policyMgr = domain.getPolicyManager(); PolicyEntry policyEntry = policyMgr.getPolicy("mypolicy"); // update PolicyEntry description and displayName policyEntry.setDescription("updated description"); policyEntry.setDisplayName("updated display name"); // persist the change policyMgr.modifyPolicy(policyEntry);
Example 3-20 illustrates how to use the deletePolicy()
method. Bank Policy refers to the unique identifier defined as the value of the Name parameter when the PolicyEntry
was created.
Example 3-20 Using deletePolicy() Method
PolicyManager policyMgr = domain.getPolicyManager(); policyManager.deletePolicy("BankPolicy");
The getPolicy()
method can be used to retrieve a PolicyEntry
, also by the value of its Name parameter. You can retrieve many PolicyEntry
objects by calling the getPolicies()
method and passing search criteria to it using the PolicySearchQuery
class. modifyPolicy()
will persist any changes defined in the PolicyEntry
object used as input.
To search for PolicyEntry
objects, use the PolicySearchQuery
class. You can build a query to search based on the following:
Name
Display Name
Description
Principal
Permission Set
Obigation
Attribute
Function
For more information, see the Oracle Entitlements Server Java API Reference.
Components of policy definitions can be organized within one or more PolicyDomainEntry
objects if partitioning of policies is required. These components include Resources, Permission Sets and Policies.
Note:
The creation of a PolicyDomainEntry is optional. If partitioning of policies is not required, manage policy definition components at the ApplicationPolicy
scope.
The following sections document how components can be managed in the ApplicationPolicy
scope. These sames components can be managed at the PolicyDomainEntry
scope if a PolicyDomainEntry
has been created for further partitioning.
For information on using the PolicyDomainEntry
, see Section 5.7, "Delegating with a Policy Domain."