Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Entitlements Server
11g Release 1 (11.1.1)

Part Number E14097-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

3 Managing Policy Objects Programmatically

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:

3.1 Using Scope Levels for Management

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.

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."

3.2 Managing Objects Created at the PolicyStore Scope

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.

3.3 Managing Objects Within the ApplicationPolicy Scope

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.

3.3.1 Managing PolicyDomainEntry 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.

3.3.2 Managing ResourceTypeEntry Objects

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.

3.3.3 Managing and Granting AppRoleEntry Objects

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.

3.3.4 Managing Role Mapping Policy (RolePolicyEntry) Objects

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.

3.3.5 Managing AttributeEntry and FunctionEntry Objects

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.

3.3.5.1 Managing AttributeEntry Objects

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.

3.3.5.2 Managing FunctionEntry Objects

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.

3.3.6 Managing ResourceEntry Objects

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);

3.3.7 Managing Permission Sets

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.

3.3.8 Managing the Policy

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.

3.4 Managing Objects within the PolicyDomainEntry Scope

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."