|Oracle® Fusion Middleware Developer's Guide for Oracle Entitlements Server
11g Release 1 (11.1.1)
Part Number E14097-04
System administrative rights and policy management permissions can be delegated from one administrator to another by creating Administration Roles with restricted rights, or by granting an existing Administration Role to a user. Administration Roles consist of a subject (the person to whom the role is granted), the resources (the objects to which the role pertains) and actions (view, manage). This chapter documents information on how to delegate policy and system administrative tasks. It contains the following sections:
Administration is when one or more authorized rights are granted to someone to do a certain job. Delegation is the ability for that someone to transfer the authorized right that has been granted them to another. In combination, we can define delegating administration as the transference of authorized rights from one to another. In Oracle Entitlements Server, administrators who are authorized to perform a task on policy objects and entities may transfer this right to others.
Delegated administration in Oracle Entitlements Server is modelled using the Role-Based Access Control (RBAC) approach. This approach allows users to transfer the administration of applications, domains, and other policy objects using roles. The core concept behind RBAC is that privileges (approvals to perform an action) are coupled with the objects on which the action can be performed and modelled as permissions. These permissions are then assigned to roles. When users are assigned the roles, the user is granted the appropriate permissions.
Figure 5-1 The Administration Role Model
As illustrated in Figure 5-1, an Administration Role is created for a particular operation on a policy related object. The permissions to perform the operation specific to that job are defined in that role. Users are then assigned the role and through those assignments acquire the permissions to perform the job. As users are not directly assigned permissions, management of individual user privileges is a matter of assigning the appropriate roles to the appropriate users. Administration Roles are used to determine who may manage policy objects.
Delegated administration is all about transferring management of resources and policy objects from one person to another. The scope of the delegation (or range of objects covered by the delegation) is defined in levels. The granularity of administration defines the type of objects managed at each scope. A default Administration Role is automatically created when each scope is created; additional Administration Roles can be created later. From highest to lowest, the scopes and applicable granularity are as follows:
The top-level System Administrator has privileges to manage system-level resources as well as policy-related objects at the top-level Policy Store scope. System resources include Administrator Roles and system configurations and bindings. Objects at the Policy Store level are the
ApplicationPolicy objects and global objects.
System Administrators have rights to the entire Policy Store, including all
ApplicationPolicy objects and child
PolicyDomain objects but they are primarily intended to manage configurations,
ApplicationPolicy objects, and the bindings between the two.
Application Policy administrators have privileges to manage all objects in the
ApplicationPolicy object to which it is assigned. One Application Policy Administrator is generated for each Application Policy that is created. They are primarily intended to delegate the management of policy objects within the Application Policy (including the Policy Domain objects and its children, such as Functions, Attributes, Application Roles and Resource Types).
Policy Domain administrators have privileges to manage all child objects in the Policy Domain object to which it is assigned. One Policy Domain Administrator is generated for each Policy Domain that is created. They are primarily intended to define the policies, permission sets, and resources within the applicable Policy Domain.
Administration Roles can be assigned permissions with Manage or View actions. The privileges of these actions are:
Administrator Roles with Manage privileges may call all methods on objects in the assigned administrative scope including any child objects. For example, an Application Policy administrator with Manage rights may call all methods on objects in both the Application Policy and its Policy Domain objects. An administrator with Manage rights may also view any required objects in a parent scope. For example, an administrator with Manage rights in a Policy Domain can view all Resources Types, Functions, and Attributes in its parent Application Policy because these objects are used when defining policies.
Administrators with View privileges may call only
get methods in the assigned administrative scope including any child objects. For example, a Global administrator with View privileges may view all objects in all Application Policy objects and its Policy Domain objects.
Administration Roles are used to delegate system administrative rights. An Administration Role can be created for purposes of managing data at different scopes. For example, Application Policy and Policy Domain administrators can be defined by creating an Administration Role at the appropriate level and assigning the role to a user or a group.
Administration Roles delegate system privileges through scoping and are not hierarchical. See Section 5.2, "Managing Scope and Delegating Granularity" for more information.
Creating administration roles involves a number of specifics. Use the following steps as a blueprint to grant View or Manage permissions on specific administration resources.
Retrieve the object within which the Administration Role will be created and an instance of the
AdminManager as documented in Section 5.4.1, "Creating An Administration Role."
Define the resource and appropriate actions as documented in Section 5.4.2, "Assigning Actions and Resources (Permissions) to an Administration Role."
Assign users (principals) as documented in Section 5.4.3, "Assigning Principals to an Administration Role."
Section 5.4.4, "Retrieving a Principal's Administration Resources" contains information on how to retrieve the administration roles that a principal has been assigned.
To create an Administration Role, retrieve the object that comprises the desired management scope (Policy Store, Application Policy or Policy Domain), use the
getAdminManager() method to retrieve an instance of the
AdminManager, and then use the
createAdminRole() method to create the
adminRole role. The following code illustrates the creation of an administrator named AppAdmin for the TRADING Application Policy.
//Get the Application Policy and AdminManager ApplicationPolicy app = ps.getApplicationPolicy(“TRADING”); AdminManager appAdminManager = app.getAdminManager(); AdminRoleEntry adminRole = appAdminManager.createAdminRole (“AppAdmin", "AppAdmin Role", "Role for application admins.");
The values of the
createAdminRole() parameters are defined as follows:
Name - AppAdmin is the name of the Administration Role.
Display Name - AppAdmin Role is an optional, human-readable name for the Administration Role.
Description - Role for application admins. is an optional description of the Administration Role.
Privileges are assigned to an Administration Role by creating an
ArrayList into which the resource(s) being managed and the permitted actions are added (using a
BasicAdminResourceActionEntry). In the following code, the previously created AppAdmin role is assigned Manage rights on Resource Types and Application Roles in the TRADING application.
//Construct the permission to be granted List<AdminResourceActionEntry> adminResourceActions = new ArrayList <AdminResourceActionEntry>(); //Add operations (Manage) and objects (resources) to the permission adminResourceActions.add(new BasicAdminResourceActionEntry (AdminResource.RESOURCE_TYPE, Action.MANAGE)); adminResourceActions.add(new BasicAdminResourceActionEntry (AdminResource.APPLICATION_ROLE, Action.MANAGE)); //Grant AppAdmin the rights admManager.grant(adminRole, adminResourceActions);
To remove privileges from a role, use the
revoke() method rather than the
grant() method. The allowed resource name options for the Policy Store, Application Policy, and Policy Domain scopes are described in Table 5-1.
Table 5-1 Resource Name Options
Allows management of Administration Role membership and permissions
Allows management of Administration Roles
Allows management of Application Policy objects
Allows management of Application Roles
Allows management of Security Modules
DISTRIBUTE_ APPLICATION_ POLICY
Allows administrator to initiate policy distribution
Allows administrator to enroll a Security Module instance
Allows management of Functions and Attributes
Allows management of Permission Sets
Allows management of Policies
Allows management of Resource Types
Allows management of Resources
Allows management of Role Categories
Allows management of child Policy Domain objects
One or more principals are assigned to the Administration Role by creating a second
ArrayList with the appropriate user entries and passing the list to the
grantAdminRole() method. In the following code, the previously created
adminRole role is granted to the user SMITH.
//Construct the list of users to be granted List<PrincipalEntry> principals = new ArrayList<PrincipalEntry>(); principals.add(new BasicPrincipalEntry ("weblogic.security.principal.WLSUserImpl", "SMITH")); //Grant the users in the list the role adminManager.grantAdminRole(adminRole, principals);
To remove principals from a role, use the
To determine what resources an administrative user can access, get an instance of the
AdminManager at the appropriate scope (Policy Store, Application Policy, or Policy Domain) and use the
getAdminRole() method and name of the Administration Role to retrieve the administrator. Then by invoking the
getGrantedAdminResources() method, all
AdminResourceActionEntry objects applicable to the administrator will be returned. (A AdminResourceActionEntry object pairs an entity that can be managed by the administrator with the action that can be performed on it.)
Section 5.4, "Creating Administration Roles" documented how to create an
AdminRoleEntry object. Administration Roles can be created at all scope levels (including the
PolicyDomain) by retrieving an instance of the
AdminManager from within the desired scope. You can also delete and retrieve
AdminRoleEntry objects from any of these scopes by getting an instance of the
AdminManager. Example 5-1 illustrates the delete action by getting the
AdminManager in an
Example 5-1 Using deleteAdminRole() Method
//Get the Application Policy and AdminManager ApplicationPolicy app = ps.getApplicationPolicy(“TRADING”); AdminManager appAdminManager = app.getAdminManager(); //delete the Administration Role AdminRoleEntry adminRole = appAdminManager.deleteAdminRole (“AppAdmin");
TRADING is the name of the
ApplicationPolicy under which the
AdminRoleEntry object was created. AppAdmin is the unique identifier of the role being deleted.
getAdminRole() method can be used to retrieve an
AdminRoleEntry, also by Name. Example 5-2 illustrates this.
Example 5-2 Using getAdminRole() Method
//Get the Application Policy and AdminManager ApplicationPolicy app = ps.getApplicationPolicy(“TRADING”); AdminManager appAdminManager = app.getAdminManager(); //Get the Administration Role AdminRoleEntry adminRole = appAdminManager.getAdminRole (“AppAdmin");
You can retrieve many
AdminRoleEntry objects by calling the
getAdminRoles() method and passing search criteria to it using the
ResourceTypeSearchQuery class. Also available in the
AdminManager interface are methods that do the following:
Add or remove a
PrincipalEntry object as an administration role member.
Return a list of
PrincipalEntry objects granted the named administration role.
Grant or revoke actions and resources (
AdminResourceActionEntry) for the named administration role.
Retrieve the actions and resources (
AdminResourceActionEntry) defined for the current administrator.
Modify the administration role.
After installing Oracle Entitlements Server, the Policy Store will contain a default Administration Role called SystemAdmin with full view and manage rights at the Policy Store level. This and other default administration roles are described in the following list. Only the members of these default Administration Roles can create and manage other Administration Roles. The default Administration Roles cannot be deleted and their rights cannot be changed.
SystemAdmin — This is the default Policy Store administrator with Manage rights in the entire Policy Store. This role is assigned to the WebLogic Server Administrators group, and has all the rights needed to manage policies in all Application Policy objects and Policy Domain objects.
PolicyDomainAdmin — A role by this name is automatically created with each new Policy Domain object. It has Manage rights in the Policy Domain and any nested Policy Domain objects. It also has View rights on objects in its parent Application Policy.
A Policy Domain contains the components of completed policy definitions. It is the amalgamation of a target Resource (an instance of the Resource Type), a Permission Set (the actions that can be performed on the Resource), and a Policy (a rule that assembles the controls and the principals they affect). Policy Domains are created for purposes of delegating administration. One (or more) of these domains can be created to delegate policy management to different administrators.
Because the creation of a Policy Domain is optional, an
ApplicationPolicy object can serve as a default Policy Domain under which a Resource, a Permission Set, and a Policy can be created. Creation of subsequent Policy Domains is dependent on the organization's plan for delegation.
Administration of the policies securing one protected application may be delegated using one or more Policy Domains. The use of multiple Policy Domains allows policies to be partitioned according to defined logic, such as the architecture of the protected application or how administration of the policies will be delegated. For example, one Policy Domain can be used to maintain all policies securing a Resource or multiple Policy Domains can be used to reflect a particular characteristic of the Resource. Different administrators can then be placed in charge of different Policy Domains. If there is no need to delegate policy administration, there is no need to create any Policy Domains. In this case, all child objects associated with a Policy Domain can be created by calling the applicable child object manager using the
The Policy Domain is programmatically represented as a
PolicyDomainEntry object. Within an
ApplicationPolicy object, one or more (optional)
PolicyDomainEntry objects can be created. A
PolicyDomainEntry object may contain one or more child objects. These objects need to be defined before creating the Policy Domain.
PolicyDomainEntry object deletes all child objects created within it.
To create a
PolicyDomainEntry, obtain an instance of the
getPolicyDomainManager(). (You can invoke
getPolicyDomainManager() for an
ApplicationPolicy or for a
PolicyDomainEntry itself to create nested Policy Domains.) Use the
createPolicyDomain() method of the
PolicyDomainManager interface to create the object. Example 5-3 creates a
PolicyDomainEntry object named East_Trading by retrieving the
PolicyDomainManager from the Trading
Example 5-3 Using createPolicyDomain() Method
PolicyDomainManager domainMgr = Trading.getPolicyDomainManager(); PolicyDomainEntry domain = domainMgr.createPolicyDomain ("East_Trading", "East_Trading Domain", "East_Trading Domain");
The values of the
createPolicyDomain() parameters are defined as:
Name - East_Trading is a unique identifier for the
Display Name - East_Trading Domain is an optional, human-readable name for the PolicyDomainEntry object.
Description - East_Trading Domain is optional information describing the PolicyDomainEntry object.
After creating a
PolicyDomainEntry object, the necessary child objects can be added to it thus allowing the administrator the control in creating policy definition components. The following list documents the child objects of a
PolicyDomainEntry with pointers to the appropriate descriptive section in Chapter 2, "Constructing A Policy Programmatically."
PermissionSetEntry (one or more
ResourceActionsEntry objects that associate a specific resource with the actions that can be performed on it). See Section 2.3.4, "Defining Permission Sets" for more information.
PolicyEntry (includes one
AppRoleEntry and, optionally, one
ObligationEntry). See Section 2.2.8, "Defining the Policy" for more information.
AdminRoleEntry (to define management of the domain). See Section 2.2.4, "Instantiating a Resource" for more information.
The same target Resource can not be shared between Policy Domains.