1 Using the Policy Model

Oracle Entitlements Server uses a model to define the elements that comprise a policy and how to use those elements to create a policy. The Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server has detailed information on the policy model. It includes a glossary of the model's components and a use case for implementing policy. This chapter contains information on how the Oracle Entitlements Server policy model is implemented using the Management API. It contains the following sections:

1.1 Examining Policy Elements

A policy is created to bestow an effect (GRANT or DENY) upon a request for a protected target resource based on the profile of the requesting principal. From a high level, the policy defines an association between an effect, a principal, the target resource, the resource's allowed actions and an optional condition. A policy is applicable to a request for access if the parameters in the request match those specified in the policy. Consider the syntax of this policy (also discussed in the Oracle Fusion Middleware Administrator's Guide for Oracle Entitlements Server):

GRANT the SupportManagerEast role MODIFY access to the Incidents servlet 
  if the request is made from an IP address of 229.188.21.21

Figure 1-1 illustrates how these elements map to policy-related objects (in the policy model) that can be used to create policies programmatically.

Figure 1-1 Policy Components Mapped to Policy Objects

Description of Figure 1-1 follows
Description of "Figure 1-1 Policy Components Mapped to Policy Objects"

An effect (PolicyRuleEntry.EffectType) and an optional condition (RuleExpressionEntry) are defined in a policy rule (PolicyRuleEntry). The target resource (ResourceEntry) and the actions that can be performed on it are defined in a ResourceActionsEntry. The requesting user, group or role is defined as the principal (PrincipalEntry) and the principal has been assigned a role defined in an AppRoleEntry. The optional obligation (ObligationEntry) specifies information returned to the caller with the decision. It will be evaluated during enforcement of the decision (rather than during evaluation of the decision); the information may or may not be used by the caller, or affect the decision itself. These programmatic objects are stored in an instance of a policy store (PolicyStore). For more information, see Section 1.2, "Composing A Simple Policy" and Section 2.2.1, "Accessing the Policy Store." Additionally:

1.2 Composing A Simple Policy

Composing a simple policy requires that the elements (or policy objects) be created in a particular order. For example, a ResourceEntry object can only be created after defining a ResourceTypeEntry object. A simple policy can be composed by following the sequence described below.

  1. Access the policy store.

    A PolicyStore object represents the entire policy store. All policy management activity can be initiated only by an authenticated user with the administrative rights to retrieve a handle to the policy store and manage the policies. The user must be assigned to at least one Administrative Role. Errors will be returned for any methods the role is not authorized to call. For more information, see Section 2.2.1, "Accessing the Policy Store."

    Note:

    A policy store is created and configured during installation of Oracle Entitlements Server. For information, see Oracle Fusion Middleware Installation Guide for Oracle Identity Management.

  2. Create an ApplicationPolicy.

    An ApplicationPolicy object is a child of the PolicyStore object and should be created as the overall container for policies and related information that secure the components of a particular application. You may create as many ApplicationPolicy objects as needed although it is recommended that only one is created for each application to be secured. After using the createApplicationPolicy method, the ApplicationPolicy object handle is returned. For more information, see Section 2.2.2, "Creating an Application Policy."

  3. Create a ResourceTypeEntry.

    A ResourceTypeEntry object specifies one or more resource attributes, and definitions of all possible valid actions that can be performed on a particular kind of resource. The actions can be standard actions (GET and POST to a URL) or custom actions on a business object (transfer to or from a bank account). Consider the following ResourceTypeEntry objects and their valid actions:

    • A text file may support Read, Write, Copy, Edit, and Delete.

    • A checking account application may support deposit, withdrawal, view account balance, view account history, transfer to savings, and transfer from savings.

    Actions will be granted or denied when accessing a protected ResourceEntry instance created from the ResourceTypeEntry. To create a ResourceTypeEntry, call the ResourceTypeManager which provides methods to create, read, update and modify the object. For more information, see Section 2.2.3, "Defining Resource Types."

  4. Instantiate a ResourceEntry from the ResourceTypeEntry.

    A specific protected target (ResourceEntry) will be instantiated from a ResourceTypeEntry object. The ResourceManager provides methods to create, read, update and delete a ResourceEntry. A ResourceEntry object represents a secured target (for example, an application), references a ResourceTypeEntry, and is created under a PolicyDomainEntry object. If no PolicyDomainEntry object is specified, it is created under the default PolicyDomainEntry object. For more information, see Section 2.2.4, "Instantiating a Resource."

  5. Associate the applicable actions with the instantiated ResourceEntry using the ResourceActionsEntry interface.

    Build a ResourceActionsEntry object to define the actions that can be performed on a ResourceEntry object. The set of actions for a ResourceEntry object are a subset of the set of legal actions already defined in the ResourceTypeEntry it references. A ResourceActionsEntry object can be added directly to a policy or one or more can be added to a PermissionSetEntry. For general information, see Section 1.3.4, "Populating a Permission Set." For programming details on adding ResourceActionsEntry objects to a PermissionSetEntry object, see Section 2.3.4, "Defining Permission Sets."

  6. Build the PolicyEntry.

    This includes:

    1. Specifying the effects (GRANT or DENY) in a PolicyRuleEntry object.

      See Section 2.2.6, "Specifying a Policy Rule" for more information.

    2. Specifying a User or Group as the policy principal in a PrincipalEntry object

      See Section 2.2.7, "Specifying the Principal" for more information. You can also specify an Application Role as the policy principal. See Section 1.3.1, "Creating an Application Role" for more information.

    3. Using the ResourceActionsEntry object containing the target resource instance and applicable actions.

      See Section 2.2.5, "Associating Actions with the Resource" for more information.

    4. Calling the PolicyManager and creating the PolicyEntry.

      See Section 2.2.8, "Defining the Policy" for more information.

  7. Distribute the policy.

    See Chapter 4, "Distributing Policies" for more information.

This sequence, and information on the creation of the policy objects, is reiterated in Chapter 2, "Constructing A Policy Programmatically" with additional information. Programming details regarding the management (including retrieval, modification and deletion) of policy objects is in Chapter 3, "Managing Policy Objects Programmatically."

1.3 Adding Fine Grained Objects to a Simple Policy

Section 1.2, "Composing A Simple Policy" documented the minimum components needed to create a policy. The following sections contain information on the objects that can be added to a simple policy to make it more fine grained.

Additional programmatic information regarding the creation of these objects is in Chapter 2, "Constructing A Policy Programmatically." Additional programmatic information regarding the retrieval, modification, and deletion of these objects is in Chapter 3, "Managing Policy Objects Programmatically."

1.3.1 Creating an Application Role

An Application Role is a collection of users, groups, and other Application Roles. For example, you might grant an Application Role all privileges necessary for a given target application. After the Application Role is created, it can be assigned statically to a user by granting the user membership in the role. It can also be assigned dynamically by referencing the role in a Role Mapping Policy which will, in turn, grant the policy's principals the permissions defined in the policy itself. An Application Role can be assigned to an enterprise user, group, or role in an identity store, or another Application Role in the policy store. One target application may have several different roles, with each role assigned a different set of privileges for more fine-grained access.

Application Roles are defined at the ApplicationPolicy level (thus, its name). The AppRoleEntry object represents the Application Role. The AppRoleManager provides the methods to create, delete, modify and search for application roles as well as methods to grant and revoke membership in the role. Membership can be granted statically through the use of the grantAppRole() method or dynamically with a Role Mapping Policy. A Role Mapping Policy assigns the role to users and an Authorization Policy defines the role's access rights.

Note:

For more information on Role Mapping Policies, see Section 1.3.2, "Defining A Role Mapping Policy."

Application Roles use role inheritance and hierarchy. The inheritance pattern is such that a subject assigned to a role (using a Role Mapping Policy) also inherits any child roles as long as it is not prohibited by other Role Mapping Policies. When an AppRoleEntry is referenced as a policy principal, access to the resource of all users assigned the role is governed by the policy. For more information, see Section 2.3.1, "Creating Application Roles."

1.3.2 Defining A Role Mapping Policy

Access to a protected resource can be granted by defining the resource and the specific users or groups that can access it in an Authorization Policy. But access can also be granted by defining an Application Role, setting the protected resource and Application Role in an Authorization Policy and creating a Role Mapping Policy to dynamically determine the users, prior to authorization, at runtime.

As documented in Section 1.3.1, "Creating an Application Role," membership to an Application Role can be granted statically through the use of the grantAppRole() method or dynamically with a Role Mapping Policy (RolePolicyEntry). An Application Role, referenced as a Principal in a Role Mapping Policy, could grant a user access to the defined resources but the Role Mapping Policy needs to be resolved before an authorization decision is reached. The resolution answers the question Can the user requesting access be assigned this Application Role? Once a request for access to a resource is received, the Authorization Policies that apply are retrieved and evaluated. If the policy references any Application Roles as the principal, they must be evaluated before the access decision is made.

You can also apply restrictions that limit access to the resource by defining conditions on the Role Mapping Policy and/or the Authorization Policy - such as the time of day or the day of the week. See Section 1.3.3, "Adding a Condition" for more information. Section 1.4, "Using Roles to Implement Policy" and Section 2.3.2, "Creating Role Mapping Policies" contains more information on Role Mapping Policies.

1.3.3 Adding a Condition

A Condition can be added to either an Authorization Policy or a Role Mapping Policy as a way of setting an additional constraint on the policy. A Condition is written in the form of an expression that resolves to true or false (boolean) and has one of the following outcomes:

  • If the expression resolves to true, the policy condition is satisfied and the effect defined in the PolicyRuleEntry is applicable.

  • If the expression does not resolve to true, the policy is not applicable.

A Condition must be true for the PolicyRuleEntry to evaluate to a positive effect. Conditions can be complex combinations of boolean expressions that test the value of some user, resource, or system attribute or they can be custom Java evaluation functions that evaluate complex business logic. To create a Condition, call the ExtensionManager and create an object to be referenced in the policy. The ExtensionManager provides methods to create and manage an AttributeEntry (a name/value pair that can be dynamically added to a policy rule) or a FunctionEntry (externally implemented logic). Either can be added to a PolicyRuleEntry as a means of setting a Condition during policy evaluation. For more information, see Section 2.3.5, "Defining a Condition."

1.3.4 Populating a Permission Set

A ResourceActionsEntry object associates a specific protected target (Resource) with the action(s) that can be performed on it. The ResourceActionsEntry object is specified when creating a simple policy or you can build a more complex policy by populating a PermissionSetEntry object (also referred to as the entitlement) with one or more ResourceActionEntry objects.

To populate, call the PermissionSetManager, instantiate a PermissionSetEntry and add one or more ResourceActionsEntry objects. The PermissionSetEntry is then referenced in a PolicyEntry object. For more information, see Section 2.3.4, "Defining Permission Sets."

1.3.5 Building an Obligation

An Obligation specifies optional information that is returned to the calling application with the access decision. This information may or may not be taken into account during policy enforcement based on settings defined by the application. The Obligation information is returned with the allowed policy effect (GRANT or DENY). For example, the reason a request for access has been denied might be returned as an Obligation. A different type of Obligation might involve sending a message; for example, if a certain amount of money is withdrawn from a checking account, send a text message to the account holder's registered mobile phone.

Note:

If a Condition evaluates to false, Obligations are not sent to the caller.

To specify an Obligation, build an ObligationEntry object. This object contains a set of attributes that form the arguments of the Obligation. The ObligationEntry is then referenced in a PolicyEntry object. For more information, see Section 2.3.6, "Adding Obligations."

1.4 Using Roles to Implement Policy

As documented in Section 1.3.2, "Defining A Role Mapping Policy," when users and groups are mapped to Application Roles, the mapping can be static (using direct role membership) or dynamic (using a Role Mapping Policy). A Role Mapping Policy contains the Principal (User, Group), a Target (resource, resource name expression) and (optionally) a Condition. Roles can also be mapped to access rights using an Authorization Policy. An Authorization Policy can contain the Principal (User, Group, Application Role), a Target (resource, entitlement set, resource name expression), actions that can be performed on the target, and (optionally) a Condition and Obligation. The following happens during authorization evaluation:

  1. Based on the Principal, a list of Application Roles is determined by checking static role membership and applicable Role Mapping Policies.

  2. Based on the Principal and resulting list of Application Roles, a list of Authorization Policies is evaluated to find any that are applicable. An applicable policy is based on the principal, target matching and condition evaluation.

  3. Evaluation results are based on the DENY overrides combining algorithm.

For more information, see Section 2.3.1, "Creating Application Roles" and Section 2.3.2, "Creating Role Mapping Policies."