5 Delegating Policy Administration

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:

5.1 Delegating Administration

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

Description of Figure 5-1 follows
Description of "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.

5.2 Managing Scope and Delegating Granularity

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.

    Note:

    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.

Note:

See Chapter 1, "Using the Policy Model" for more information on the ApplicationPolicy objects and Section 5.7, "Delegating with a Policy Domain" for information on the PolicyDomain objects.

5.3 Assigning Permissions

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.

5.4 Creating Administration Roles

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.

Note:

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.

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

  2. Define the resource and appropriate actions as documented in Section 5.4.2, "Assigning Actions and Resources (Permissions) to an Administration Role."

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

5.4.1 Creating An Administration Role

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.

5.4.2 Assigning Actions and Resources (Permissions) to an 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

Name Description

ADMIN_POLICY

Allows management of Administration Role membership and permissions

ADMIN_ROLE

Allows management of Administration Roles

APPLICATION_ POLICY

Allows management of Application Policy objects

APPLICATION_ ROLE

Allows management of Application Roles

CONFIGURATION

Allows management of Security Modules

DISTRIBUTE_ APPLICATION_ POLICY

Allows administrator to initiate policy distribution

ENROLL

Allows administrator to enroll a Security Module instance

EXTENSION

Allows management of Functions and Attributes

PERMISSION_SET

Allows management of Permission Sets

POLICY

Allows management of Policies

RESOURCE_TYPE

Allows management of Resource Types

RESOURCE

Allows management of Resources

ROLE_CATEGORY

Allows management of Role Categories

SUB_POLICY_DOMAIN

Allows management of child Policy Domain objects

5.4.3 Assigning Principals to an Administration Role

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 revokeAdminRole() method.

5.4.4 Retrieving a Principal's Administration Resources

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

5.5 Managing Administration Roles

Section 5.4, "Creating Administration Roles" documented how to create an AdminRoleEntry object. Administration Roles can be created at all scope levels (including the PolicyStore, ApplicationPolicy and 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 ApplicationPolicy.

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.

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

5.6 Using the Default Administration Roles

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.

  • ApplicationPolicyAdmin — A role by this name is automatically created with each new Application Policy object. It has Manage rights in the Application Policy and its nested 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.

5.7 Delegating with a Policy Domain

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.

Note:

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 ApplicationPolicy interface.

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.

Caution:

Deleting a PolicyDomainEntry object deletes all child objects created within it.

To create a PolicyDomainEntry, obtain an instance of the PolicyDomainManager using 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 ApplicationPolicy.

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

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

Note:

The same target Resource can not be shared between Policy Domains.