|Oracle® Fusion Middleware Developer's Guide for Oracle Entitlements Server
11g Release 1 (11.1.1)
Part Number E14097-04
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:
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 188.8.131.52
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
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:
Authorization Policies define rules that control access to both application software components and application business objects. See Chapter 2, "Constructing A Policy Programmatically" for more information.
Role Mapping Policies are used to define rules about how principals are granted or denied roles. See Chapter 7, "Extending Functionality" for more information.
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.
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."
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.
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."
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."
A specific protected target (
ResourceEntry) will be instantiated from a
ResourceTypeEntry object. The
ResourceManager provides methods to create, read, update and delete 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."
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."
Specifying the effects (GRANT or DENY) in a
See Section 2.2.6, "Specifying a Policy Rule" for more information.
Specifying a User or Group as the policy principal in a
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.
ResourceActionsEntry object containing the target resource instance and applicable actions.
See Section 2.2.5, "Associating Actions with the Resource" for more information.
PolicyManager and creating the
See Section 2.2.8, "Defining the Policy" for more information.
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."
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."
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.
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."
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.
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."
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
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."
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.
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."
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:
Based on the Principal, a list of Application Roles is determined by checking static role membership and applicable Role Mapping Policies.
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.
Evaluation results are based on the DENY overrides combining algorithm.