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.
Oracle Entitlements Server allows administrators to perform create, read, update, and delete (CRUD) operations on all policy and global objects. This can be done in any of the following ways:
Using the Management API (as described in Section 3.2, "Using Scope Levels to Manage Policy Objects")
Using the Administration Console (as described in Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server)
Using the WebLogic Scripting Tool on the command line (as described in Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server)
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.3.1, "Accessing the Policy Store." The policy store location, the account and the account password used to access it are defined in jps-config.xml, the Oracle Platform Security Services 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">
<property name="policystore.type" value="DB_ORACLE"/>
<property name="repository.type" value="database"/>
</serviceProvider>
</serviceProviders>
<serviceInstances>
<serviceInstance name="policystore.db" provider="policy.db">
<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="bootstrap.security.principal.key" value="bootstrap"/>
<property name="bootstrap.security.principal.map"
value="BOOTSTRAP_JPS"/>
<property name="oracle.security.jps.ldap.root.name"
value="cn=farm,cn=JPSContext,cn=jpsroot"/>
</serviceInstance>
</serviceInstances>
<jpsContexts default="default">
<jpsContext name="default">
<serviceInstanceRef ref="policystore.db"/>
</jpsContext>
</jpsContexts>
</jpsConfig>
Note:
See Oracle Fusion Middleware Application Security Guide for more information on the jps-config.xml configuration file. Parameters specific to Oracle Entitlements Server are documented in Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server.
For more information, see Section 3.2.1, "Managing Objects Created at the PolicyStore Scope."
An ApplicationPolicy object represents an application being secured by Oracle Entitlements Server. Within an ApplicationPolicy, programmatic objects used to define policies (ResourceTypeEntry, FunctionEntry, AppRoleEntry, RolePolicyEntry and the like) are managed.
Note:
Optionally, these programmatic objects can also be managed by creating one (or multiple) PolicyDomainEntry objects within the ApplicationPolicy as described in the following bullet point and in Chapter 5, "Delegating Policy Administration."
For more information, see Section 3.2.2, "Managing Objects Within the ApplicationPolicy Scope."
An optional PolicyDomainEntry object can be created to partition, and serve as a management point for policy objects 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."
For more information, see Section 3.2.3, "Managing Objects within the PolicyDomainEntry Scope."
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."
The following sections contain more specific information.
Section 3.2.1, "Managing Objects Created at the PolicyStore Scope"
Section 3.2.2, "Managing Objects Within the ApplicationPolicy Scope"
Section 3.2.3, "Managing Objects within the PolicyDomainEntry Scope"
Within the PolicyStore object, policy components securing different applications are organized within one or more second level ApplicationPolicy objects. Section 2.3.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.2.2.3, "Managing and Granting AppRoleEntry Objects"
Section 3.2.2.4, "Managing Role Mapping Policy (RolePolicyEntry) Objects"
Section 3.2.2.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.3.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 ResourceTypeEntry and related objects would be removed. If true, the ResourceTypeEntry and all instantiated ResourceEntry objects are deleted. If false, and ResourceEntry instances exist, the operation fails and the 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.4.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.
Revocation of the AppRoleEntry can be done using the revokeAppRole() 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 principal (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.2.2.4, "Managing Role Mapping Policy (RolePolicyEntry) Objects" for more information.
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.4.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.4.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.3.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.4.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.3.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
Obligation
Attribute
Function
For more information, see the Oracle Fusion Middleware Management Java API Reference for Oracle Entitlements Server.
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 same 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."