2 Understanding the Policy Model

A policy is a set of criteria that, when evaluated by Oracle Entitlements Server, specifies whether a user will be granted access to a particular protected resource or assignment to a particular role. This chapter contains an overview of the Oracle Entitlements Server policy model, the elements that comprise a policy and how the elements are organized in the policy store. It contains the following sections.

2.1 Understanding Oracle Entitlements Server Policies

Oracle Entitlements Server supports the creation of the following types of policies. The referenced sections contain detailed information regarding these policy types including how they are used.

2.1.1 Understanding the Authorization Policy

An Authorization Policy is created to grant or deny access to a particular resource based on the profile of the requesting user. From a high level, the Authorization Policy defines an association between an effect (GRANT or DENY), a principal (requesting user), the target resource, the resource's allowed actions and an optional condition. An Authorization Policy is applicable to a request for access if the parameters in the request match those specified in the policy. Consider this Authorization Policy definition:

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

This Authorization Policy will GRANT any user that is a member of the SupportManagerEast role access to the Incidents servlet for the purpose of modifying it. The policy is also constrained by an optional condition - the request must be made from IP address 229.188.21.21. Thus, if the parameters in the request match the parameters in the policy (a member of the SupportManagerEast role wants to modify the Incidents servlet), and the request is made from IP address 229.188.21.21, the request is granted. If the parameters in the request match the parameters in the policy (a member of the SupportManagerEast role wants to modify the Incidents servlet) but the request is NOT made from IP address 229.188.21.21, the policy is ignored. The following list of terms and values are extracted from this policy definition and comprise the components of the Authorization Policy.

  • Effect: GRANT

  • Action: MODIFY

  • Resource: Incidents servlet

  • Principal: member of SupportManagerEast role

  • Condition/Constraint: IP address 229.188.21.21

Figure 2-1 illustrates how the components of this policy map to the Oracle Entitlements Server Authorization Policy objects.

Figure 2-1 Policy Components Mapped to Authorization Policy Objects

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

For information on how to create, update and delete Authorization Policies, see Section 4.5.5, "Managing Authorization Policies."

2.1.2 Understanding Role Assignments and the Role Mapping Policy

An Application Role is a collection of users, groups, or other Application Roles; it is defined using Oracle Entitlements Server and stored in the policy store. It can be mapped to a user, group, or external role in an identity store, or another Application Role in the Oracle Entitlements Server policy store.

Note:

Assigning one Application Role to another Application Role allows you to build an Application Role hierarchy.

Application Roles can be assigned to a user in either of the following ways:

  • By statically granting a specific user membership in the role.

  • By referencing the Application Role in a Role Mapping Policy that will be used to dynamically assign role membership at runtime.

A Role Mapping Policy allows you to dynamically assign (GRANT) role membership to a user or dynamically revoke (DENY) role membership from a user. Consider the following Role Mapping Policy definition:

GRANT the Employee group application role SupportManageEast 
   if the request is made from an IP address of 229.188.21.21

This policy grants the SupportManagerEast Application Role to any user that is a member of the group Employee. It is also constrained by an optional condition - the request must be made from IP address 229.188.21.21. Thus, if the parameters in the request match the parameters in the Role Mapping Policy (the requesting user is a member of the Employee group), and the request is made from IP address 229.188.21.21, the Application Role is granted. If the request is not made from the defined IP address, the Role Mapping Policy is ignored. The target is also an optional addition to a Role Mapping Policy. The following terms and values are applicable to this Role Mapping Policy definition.

  • Effect: GRANT

  • Application Role: SupportManagerEast

  • Principal: member of Employee group

  • Condition/Constraint: IP address 229.188.21.21

If a Resource or Resource Name Expression is defined as a Target for a Role Mapping Policy, the Role Mapping Policy will only be applied if it matches the resource defined in the request. Figure 2-2 illustrates how the components of this example policy might map to Oracle Entitlements Server Role Mapping Policy objects.

Figure 2-2 Policy Components Mapped to Role Mapping Policy Objects

Description of Figure 2-2 follows
Description of "Figure 2-2 Policy Components Mapped to Role Mapping Policy Objects"

A Role Mapping Policy can also be used to prevent specific users from being assigned an Application Role. Consider the following Role Mapping Policy definition:

DENY the Customers group the application role GoldCircle 
   if the account balance is less then $10,000

This policy denies the GoldCircle Application Role to any members of the group Customers IF their account balance is less then $10,000. For information on how to create, update and delete Role Mapping Policies, see Section 4.5.7, "Managing Role Mapping Policies."

2.2 How Oracle Entitlements Server Evaluates Policies

During Oracle Entitlements Server runtime evaluation, the following occurs:

  1. Based on the subject, a list of Application Roles is determined by:

    1. Retrieving the user's static role membership.

    2. Evaluating all applicable Role Mapping Policies with a GRANT effect and adding them to the list of roles previously determined.

    3. Evaluating all applicable Role Mapping Policies with a DENY effect and removing them from the list of roles previously determined.

  2. Based on the subject and list of retrieved Application Roles, a list of Authorization Policies is evaluated to find any that might be applicable based on the grantee, target matching and conditions. (The actions allowed on the resource are defined by the Authorization Policy.)

  3. A final authorization decision is based on the "DENY overrides" combining algorithm and returned to the calling application.

Section 1.4, "How Oracle Entitlements Server Processes Authorization Policies" contains additional details on this process.

2.3 The Policy Object Glossary

The policy objects defined in this section can be created, provisioned or managed using the Authorization Policy Manager Administration Console.

  • Application

    An Application is a high-level container for managing roles, policies, resource definitions, and other policy objects; in effect, all items needed to define secure access to a particular resource. An Application may correspond to a single deployed software application, a set of deployed software applications, or components of a software application (such as an Enterprise Java Bean). You can manage more than one Application with Oracle Entitlements Server. For more information, see Section 4.5.1, "Managing Applications."

  • Application Role

    An Application Role defines criteria for mapping users, groups, External Roles or other Application Roles to a particular Oracle Entitlements Server Application object. The Application Role can be granted to an external user, group, or role in an identity store, or another Application Role in the policy store. When creating an Application Role (in a Role Catalog) you might grant it all privileges necessary to access a given target Resource. Then, the Application Role can be assigned statically by explicitly granting membership to it, or the Application Role can be assigned dynamically by referencing it as the subject in a Role Mapping Policy. One target Application may have several different Application Roles, with each one assigned a different set of privileges offering more fine-grained access.

    One External Role can be mapped to many Application Roles. For example, the External Role employee (stored in LDAP-based identity store) can be mapped to the Application Role customersupport member (defined in one Application) and to the Application Role IT member (defined in another Application). A Role Catalog is the container in which Application Roles are kept. For more information, see Section 4.5.6, "Managing Application Roles in the Role Catalog."

    Note:

    An Application's Role Catalog provides the means to organize Application Roles. Search for Application Roles in the Role Catalog node of the Oracle Entitlements Server Administration Console. See Chapter 5, "Querying Security Objects" for more information.

  • Attribute

    An Attribute represents data that can be used in a policy condition, or returned with the policy determination as an obligation. It can be a built-in attribute (where its value is always defined - as in current time or current user), a Resource attribute (which is associated with, and managed within, a configured Oracle Entitlements Server Resource) or a Dynamic attribute. An attribute is defined by its name, the type of data it takes as a value, and whether the value is single or multiple. An attribute value can either be passed by the protected application as part of an authorization request, or retrieved by Oracle Entitlements Server using an attribute retriever. For more information, see Section 4.5.9, "Managing Attributes and Functions as Extensions."

  • Authorization Policy

    An Authorization Policy specifies a set of rights that an entity (the grantee, a principal or code source) is allowed on a protected resource. This might include viewing a web page or modifying a report. In short, it specifies who can do what to a resource protected by Oracle Entitlements Server. For more information, see Section 4.5.5, "Managing Authorization Policies."

    Note:

    Search for Authorization Policies in the Default Policy Domain node (or a custom Policy Domain node, if applicable) of a configured Application. See Chapter 5, "Querying Security Objects" for more information.

  • Condition

    A Condition is one or more boolean expressions that must evaluate to true in order for the policy to be included in the authorization decision. Adding a Condition to a policy is optional and when used, further restricts access to the protected resource. In general, a condition's boolean expression tests the value of some user, resource, or system attribute. Individual conditions can be combined with the following logical operators: AND, OR, and NOT. Conditions can define constraints based on date, time, a time range, a day of week, and so forth. For more information, see Section 4.6, "Using the Condition Builder."

  • Entitlement

    An Entitlement (also known as a permission set) represents a small set of Resources and the associated actions needed to perform a task. It groups related Resources, possibly of different types, needed to perform a business function. An Entitlement is a reusable collection of access rights that can be granted to multiple principals. For more information, see Section 4.5.4, "Managing Entitlements."

  • External Role

    An External Role is defined in an external identity store such as an LDAP server or a database. The term external role is often synonymous with the terms enterprise role or enterprise group; they are typically implemented as LDAP groups in the identity store. For information on adding an External Role to a policy, see Section 4.5.5.1, "Creating an Authorization Policy" or Section 4.5.7.1, "Creating a Role Mapping Policy."

    Note:

    Within Oracle Entitlements Server, external roles and users are read-only. They are managed with a different tool, such as Oracle Identity Manager. For more information, see Oracle Fusion Middleware System Administrator's Guide for Oracle Identity Manager.

  • Function

    A Function represents code that can be invoked as part of the evaluation of a policy condition; the returned value will affect the evaluation of the condition. You can extend the functions supplied with Oracle Entitlements Server by creating additional, custom ones. For more information, see Section 4.5.9, "Managing Attributes and Functions as Extensions."

  • Obligation

    An Obligation specifies optional information that is to be returned with a GRANT or DENY authorization decision. When used in a policy, an Obligation may impose an additional requirement for the policy enforcing component, or simply request useful information. For example, the reason a request for access has been denied might be returned as an Obligation. For information on adding an Obligation to a policy, see Section 4.5.5.1, "Creating an Authorization Policy."

  • Policy Domain

    A Policy Domain is a container under an Application object that can serve as a partition to facilitate management of Resources, Entitlements and Authorization Policies. The Policy Domain is an optional management construct that can restrict an administrator's right to a particular subset of Resource, Entitlements, and Authorization Policies. The Policy Domain has no effect upon runtime policy evaluation. Multiple Policy Domains can be created and can be hierarchical. A default policy domain is added to each Application upon its creation. For more information, see Section 11.4, "Using Policy Domains to Delegate."

  • Policy Store

    The Policy Store is where all Oracle Entitlements Server policy objects (including, but not limited to, Applications, Resources and various role types) are stored. A Policy Store can be a relational database (preferred) or an LDAP-based directory. For more information, see Section 3.2.3, "Accessing the Policy Store."

  • Principal

    A Principal is the identity to which the access rights defined in a policy are granted. A principal can be a user, a group, an External Role, or an Application Role. Most frequently, it is an Application Role. For information on adding a principal to an Oracle Entitlements Server policy, see Section 4.5.5.1, "Creating an Authorization Policy" or Section 4.5.7.1, "Creating a Role Mapping Policy."

  • Resource

    A Resource is a protected component or object to which access is granted or denied. A Resource represents the application component or business object that is secured by an Authorization Policy. At runtime, the application passes the Resource name to check for access definitions that will determine whether a Principal is authorized access. A Resource requires an associated Resource Type. For more information, see Section 4.5.3, "Managing Resources."

  • Resource Type

    A Resource Type represents the type of a secured object. Protected software application components that share common characteristics can be represented by particular Resource Type. For example, a set of pages can be represented by one Resource Type and bank accounts by another Resource Type. A Resource Type defines eligible resource attributes and possible valid actions that are applicable to the protected component. For more information, see Section 4.5.2, "Managing Resource Types."

  • Role Category

    A Role Category is an optional tag that can be associated with an Application Role; it can be used for searching. Role Categories allow administrators to organize roles in arbitrary flat collections. They have no effect upon runtime policy evaluation. For more information, see Section 4.5.8, "Managing a Role Category."

  • Role Mapping Policy

    A Role Mapping Policy is used to determine what external subjects (users, groups or External Roles) are assigned to the applicable Application Role. The Application Role, when referenced in an Authorization Policy, defines the principals affected by the Authorization Policy. Role Mapping Policies may also include conditions. For more information, see Section 4.5.7, "Managing Role Mapping Policies."

    Note:

    Search for Role Mapping Policies under the Role Catalog node of the Oracle Entitlements Server Administration Console. See Chapter 5, "Querying Security Objects" for more information.

2.4 Implementing a Policy Use Case

Oracle Entitlements Server provides the ability to externalize policy management and policy decision making logic from an organization's resources. It secures access to the organization's resources by implementing policies that specify the users, groups, and roles that can access them. Resources can be application software components (URLs, Enterprise JavaBeans, JavaServer Pages) or enterprise business objects (customer accounts, patient records). This use case considers how the policy model can be used to secure the financial services offered by Acme Investment Bank. It is based on the concept of hierarchical resources; namely, that resources are organized as a tree and inherit from their parent elements.

Note:

Oracle Entitlements Server also supports the concept of non-hierarchical (flat) resources. See Section 4.5.2, "Managing Resource Types" for more information.

In this use case, the following conditions apply:

  • A customer may open a family account and is considered an owner of the account.

  • The customer may open a child account for family members and set transfer limits for each member. Transfer limits must be lower than the customer's own transfer limit.

  • Each account has a bank employee that acts as an account manager and sets the transfer limits for the account.

  • Both a Summary report and an Account Manager report are associated with each family account.

Figure 2-3 illustrates the financial services scenario by organizing the protected resources into business objects and software components. Paul is a bank employee who is an account manager and can set transfer limits up to $100,000 on the accounts that he manages. Paul manages account owner Bob's family account which has a transfer limit of $10,000. Bob manages his family account and a child account he created for Mary who may not transfer money. These accounts are considered business objects and are protected as such.

Account owner Bob has access to a Summary report generated for his family account. Account manager Paul has access to Bob's Summary report and his own Account Manager report. Child account holder Mary has access to no reports. These reports, generated as JavaServer Pages, are considered software components and are protected as such.

Figure 2-3 Use Case for Software Components and Business Objects

Description of Figure 2-3 follows
Description of "Figure 2-3 Use Case for Software Components and Business Objects"

For any given user, a request for access to a financial services account (business object) or account report (software component) generates a decision based on the following questions:

  1. Is this user an account holder, account owner or an account manager?

  2. Can this user transfer funds from this account (subject to the role, transfer limit, and time of transaction)?

  3. What reports can this user access?

The first two questions can be decided using policies created to protect business objects, while the last can be decided using policies created to protect software components. The following sections illustrate how to conceptualize the policies.

2.4.1 Protecting Software Components

The Account Reports node in Figure 2-3, "Use Case for Software Components and Business Objects" represents the reporting application. Summary.jsp and Detailed.jsp are the software components. There are several options from which to choose when deciding how to model policies for securing these software components. One option is to set an Authorization Policy for the top node reporting application by using group membership. The following example illustrates how access is explicitly granted by naming the resource and the group of users that can access it.

GRANT the BankManagers group access to the AccountReports node

This top down Authorization Policy grants access to the Account Reports node for anyone in the BankManagers group. Because these resources are hierarchical, anyone in the allowed group has access to both the Summary and Detailed reports. But this access may be restricted using system-based or attribute-based conditions. For example, adding a condition based on time or based on the value of a specific user, group, or resource attribute would further limit access. The following example illustrates how a time-based condition restricts access of the reports to typical office hours.

GRANT the BankManagers group access to the AccountReports node 
  IF the request is made between 09:00 and 17:00

Another option can set the top down Authorization Policy by defining the principal as a role rather than a group. A role is comprised of users or groups. (An LDAP role would be granted enterprise wide whereas an Application Role is specific to the Application for which it was configured.)

Note:

A user can be assigned to a role through membership or a Role Mapping Policy as discussed in Section 2.1, "Understanding Oracle Entitlements Server Policies."

In the following example, the resource is explicitly named and access is implicitly granted to a user if the user is assigned the defined role.

GRANT access to AccountReports node if user has BankManagers role

You can also dynamically assign the BankManagers role to users accessing the reporting application if they are a member of the BankManagers group (as illustrated below).

GRANT BankManagers role to members of BankManagers group
  FOR access to AccountReports node



Another way to define the previous Authorization Policy is to assign the role based on a user attribute value rather than group membership. (In a large enterprise, it is typically more efficient to assign users based on attributes than on group membership.) The following example assigns the BankManagers role to the requesting user if the value of the UserType attribute in the user's profile is BankManager.


GRANT BankManagers role to anyone defined by UserType 'BankManager'
  FOR access to the AccountReports node



The previous examples represent Authorization Policies that scope from the top node reporting application down to the reports but Authorization Policies can also be defined for the specific report nodes. The following example grants access to the Summary.jsp report to all assignees of the BankManagers and AccountOwners roles. The additional condition is that the principal requesting access must be listed on the account to which the report pertains.


GRANT Summary.jsp access to all members of BankManagers and AccountOwners role
  IF the requesting assignee is listed as OWNER or MANAGER on specified account



Another example illustrates how access to the Detailed.jsp report can be granted to anyone who is assigned the BankManager role.


GRANT Detailed.jsp access to all assignees of BankManagers role



The previous examples show how an Authorization Policy can be modeled for specific application software components. In a real enterprise scenario, each application may have tens or hundreds of resources so it might not be practical to write an Authorization Policy for each one. The concept of resource attributes has been implemented by Oracle Entitlements Server to address this proliferation of application software component resources and associated Authorization Policies.


By associating a resource with an attribute, you can grant access based on the value of the attribute. For example, filetype could be a resource attribute that is used to define an HTML page, an image, or a PDF. By defining a condition as if filetype=pdf, you can grant access to all PDF files that are associated with the resource. The following example uses a resource attribute; it allows users assigned the BankManagers and AccountOwners role access to all reports although access is granted only if the report type being requested matches the value of the UserReportType attribute in the specific user's profile.


GRANT users assigned BankManagers or AccountOwners roles 
     access to AccountReports
   IF requested ReportType matches UserReportType attribute value 
     in user profile



This policy grants BankManagers and AccountOwners access to all reports although access is constrained based on matching resource attribute values with user attribute values. An advantage of this approach is that the policy governing access need not change as resources are added to, or removed from, an application. As resources change, the ReportType resource attribute attached to the application continues to govern access.








2.4.2 Protecting Business Objects


There are several options from which to choose when deciding how to model Authorization Policies for securing business objects. In this banking scenario, business objects are bank accounts. Figure 2-3, "Use Case for Software Components and Business Objects" illustrates the Acme bank account structure.


Each bank account can have a manager, an owner, and a holder with each scope assigned a certain set of privileges (or entitlements). The policy evaluating what a user can do on the bank account is then based on the user's attributes rather than the resource. The following example allows anyone to transfer money but that privilege is only granted if the user is defined as owner of the account requested and the amount of money being transferred is less than or equal to the limit defined for the user.


GRANT anyone transfer privileges only
   IF the user is listed as OWNER on specified account
  AND transfer amount is equal to or less than the transfer limit



There is another option to acquire a user's entitlements. Rather than comparing a transfer request to a transfer limit, Oracle Entitlements Server can return the transfer limit amount as the output of evaluation. In this scenario, the user's ability to access the account is verified but the transfer amount is returned to the caller (in a Java object) as an obligation. This leaves verification that the transfer amount is within the transfer limit up to the application. The following example illustrates this model.


GRANT anyone transfer privileges only
   IF the user is listed as OWNER on specified account
  THEN RETURN transfer limit to calling application



A model where the bank account corresponds to an individual resource instance can also be used; however, this would yield a proliferation of policies (one for each account) and become unmanageable. For example, if Acme Investment Bank had 100,000 accounts, it would need at least 100,000 policies just to manage transfers. For more information on adding obligations, see Section 4.5.5, "Managing Authorization Policies."