4 Managing Policies and Roles

The Oracle Entitlements Server Administration Console is used to manage authorization policies and the policy objects from which they are created. This chapter contains the following sections:

Section 4.1, "Introducing Policy and Policy Object Management"
Section 4.2, "Defining an Authorization Policy And Its Components"
Section 4.3, "Adding Fine-Grained Elements to an Authorization Policy"
Section 4.4, "Implementing An Authorization Policy Step by Step"
Section 4.5, "Managing Policy Objects in An Application"
Section 4.6, "Using the Condition Builder"

4.1 Introducing Policy and Policy Object Management

Oracle Entitlements Server allows administrators to perform create, read, update, and delete (CRUD) operations on all policy and global objects. Tasks performed in the Administration Console typically require that an administrator identify an object (by browsing or searching), select it, and choose one of the operations available for it. Objects are organized into groupings that are displayed in the Navigation Panel: Global and Applications.

Application objects include the objects used to create authorization policies (resources, application roles and the like). They apply to, and can only be used for policies within, the Application under which they are defined. The Applications node in the Navigation Panel is the branch under which all configured Applications (and their respective objects) are organized. This chapter contains information on managing Applications and their objects.
Global objects include users, external roles, and system configurations for attribute retrievers, administrators and the like. These objects may apply to all configured Applications throughout the system. The Global node in the Navigation Panel is the branch under which all systemwide objects are organized. These obejcts are discussed in Chapter 8, "Managing System Configurations."

Note:

Within Oracle Entitlements Server, external roles (and users) are read only; they are typically 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.

Oracle Entitlements Server supports the mapping of policies to individual users, External Roles, and Application Roles. However, mapping policies to Application Roles is recommended because of the following:

Managing authorization based on grants to individual users and external roles can quickly become unmanageable as the number increases.
If the identity management source changes (for example, when a move between development, test and production environments results in a new LDAP server), no changes to policy definitions are needed. All that is required is a re-mapping of the application roles to the users and external roles available in the target environment.

By default, all access to a resource is denied until an Authorization Policy is written and deployed that explicitly grants access action. If the Authorization Policy only grants an entitlement on a Resource to a role, the user must be statically assigned to it or a Role Mapping Policy must be written and deployed that assigns a user or a group to the defined role. If an Authorization Policy denies a previously granted entitlement, it takes precedence over the grant. Explicit DENY authorization policies cannot be overruled. A practical use of a DENY policy is to explicitly deny an entitlement to ensure that a user or group can never gain access to a specific resource.

4.2 Defining an Authorization Policy And Its Components

Defining a policy requires that the objects be created in a particular order. For example, a Resource can only be created after defining a Resource Type. A policy can be composed by following the sequence described below.

Create an Application.

In the Navigation Panel, an Application should be created as the overall container for policies and related information that secure the components of a particular resource. You may create as many Applications as needed although it is recommended that only one is created for each application to be secured. For more information, see Section 4.5.1, "Managing Applications."
Create a Resource Type.

A Resource Type 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 Resource Types 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.
Resource instances are created from Resource Types. Actions defined by the Resource Type are granted or denied when accessing a protected Resource instance created from the Resource Type.

Note:

A Resource instance is defined in a Policy Domain and references the Resource Type. For more information, see Section 4.5.3, "Managing Resources."

For more information, see Section 4.5.2, "Managing Resource Types."
Instantiate a Resource from the Resource Type.

A specific protected target (Resource) is instantiated from a Resource Type. A Resource represents a secured target (for example, an application) and is created under a Policy Domain in the Resource Catalog. If no Policy Domain is specified, it is created under the Default Policy Domain. For more information, see Section 4.5.3, "Managing Resources."

Note:

A Policy Domain is an optional object that is created for purposes of delegated administration and organization. See Chapter 9, "Delegating With Administrator Roles."
Build the Authorization Policy.

This entails specifying the effect (GRANT or DENY), adding a user, group or role as the policy principal and the Resource and actions as the policy target. Optionally, you can add an Obligation or build a Condition. For more information, see Section 4.5.5, "Managing Authorization Policies."

4.3 Adding Fine-Grained Elements to an Authorization Policy

Section 4.2, "Defining an Authorization Policy And Its Components" documented the minimum components needed to create an authorization policy. The following fine-grained elements can be added to a simple policy.

Entitlements

An Entitlement associates an instantiated Resource with the applicable actions that can be performed on it. The set of actions for a Resource are a subset of the set of legal actions already defined in its corresponding Resource Type. For more information, see Section 4.5.4, "Managing Entitlements."
Application Roles

An Application Role can be assigned statically or dynamically to an enterprise user, group, or external role in an identity store, or another Application Role in the policy store. One target application may have several different Application Roles, with each role assigned a different set of privileges for more fine-grained access. For more information, see Section 4.5.6, "Managing Application Roles in the Role Catalog."
Role Mapping Policy

Membership to an Application Role can be granted dynamically with a Role Mapping Policy. 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 must be resolved before an authorization decision is reached. The resolution answers the question Can the user requesting access be assigned this Application Role? During runtime evaluation of a Role Mapping Policy, the following occurs:
1. Based on the subject, a list of application roles is determined by retrieving static role membership and evaluating any applicable role mapping policies.
2. Based on the subject and list of application roles, a list of Authorization Policies is evaluated to find any that might be applicable based on the grantee, target matching and constraints evaluation. The actions allowed on the Resource are defined by the Authorization Policy.
3. Final authorization decision is based on the “DENY overrides” combining algorithm.
For more information, see Section 4.5.7, "Managing Role Mapping Policies."
A Condition can be added to a policy as a way of setting an additional contigency on the policy. It is applicable to either an Authorization Policy or a Role Mapping Policy. A Condition is written in the form of an expression that resolves to true or false 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 policy to evaluate to true. 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. For more information, see Section 4.6, "Using the Condition Builder."
An Obligation specifies optional information to be evaluated during the policy enforcement phase of authorization. The obligation is returned with the corresponding policy effect (GRANT or DENY). This information may or may not be taken into account during policy enforcement based on settings defined by the application. 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. For more information, see Section 4.5.5, "Managing Authorization Policies."

4.4 Implementing An Authorization Policy Step by Step

In Section 2.4, "Implementing a Policy Use Case," several use cases for creating a policy are discussed. This section documents the step by step procedure to create an Authorization Policy (and the policy objects from which it is comprised) using the Administration Console. This procedure assumes you have installed Oracle Entitlements Server and a Java Security Module to protect an application.

Create an Application.

The Application Name must match what is used in the application code. For example, create a HelloOESworld Application object to map to a HelloOESworld Application. See Section 4.5.1.1, "Creating an Application."
Create a Resource Type.

The Resource Type Name must match what is used in the application code. For example, create a Files Resource Type object for use in collecting files that will be protected. Associate the write and read actions with the Resource Type. See Section 4.5.2.1, "Creating a Resource Type."
Create a Resource.

A Resource Name must match what is used in the application code. Additionally, the Resource is created from the Resource Type. For example, create a FinanceFile Resource from the Files Resource Type. See Section 4.5.3.1, "Creating a Resource."
Create the Authorization Policy.

In the HelloOESworld Application, create an Authorization Policy. Add one or more Principals (Roles or Users), one or more targets (Resources or Entitlements) and confirm the actions for the target. Optional conditions or obligations can also be added before saving. See Section 4.5.5.1, "Creating an Authorization Policy."
Create a Security Module definition and bind it to the Application.

This step defines the Security Module to which this Authorization Policy is distributed once binded. See Section 8.2, "Configuring Security Module Definitions."
Distribute the Authorization Policy to the Security Module.

See Chapter 7, "Managing Policy Distribution."

4.5 Managing Policy Objects in An Application

The following sections describe how to manage policy objects specific to the Applications.

Section 4.5.1, "Managing Applications"
Section 4.5.2, "Managing Resource Types"
Section 4.5.3, "Managing Resources"
Section 4.5.4, "Managing Entitlements"
Section 4.5.5, "Managing Authorization Policies"
Section 4.5.6, "Managing Application Roles in the Role Catalog"
Section 4.5.7, "Managing Role Mapping Policies"
Section 4.5.8, "Managing a Role Category"
Section 4.5.9, "Managing Attributes and Functions as Extensions"

4.5.1 Managing Applications

An Application is created as the overall container for policies and related artifacts that secure the components of a particular application. These artifacts include (but are not limited to) roles, resources, attributes and functions. You may create as many Application instances as needed although it is recommended that only one is created for each application to be secured. The following sections describe management operations on Application instances.

Creating an Application
Modifying an Application
Deleting an Application

4.5.1.1 Creating an Application

To create an Application, proceed as follows:

Right-click Applications in the Navigation Panel and select New from the menu.

Note:

Alternately, click Create Application under Search and Create in the Home area.

An Untitled page with several tabs displays in the Home area. The General tab is active. You can only configure the Delegated Administrators and Policy Distribution details after the Application has been created. See Section 4.5.1.2, "Modifying an Application" for information.
Provide the following information for the application being created under the General tab.
- Display Name: The Display Name is optional and case insensitive. Specifying a meaningful value, though, is recommended as it is displayed in the Administration Console and can be used as a search parameter.
- Name: The name is required and case insensitive. It must match what is used in the application code.
- Description: Although optional, it is recommended to provide useful information about the Application.
Select one of the following from the Save menu.
- Save and Close saves the configuration, renames the tab with the value provided for the Application's Display Name and activates the Delegated Administrators and Policy Distribution tabs.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another Application.

4.5.1.2 Modifying an Application

To modify an Application, proceed as follows:

Expand the Applications node in the Navigation Panel.
Select the name of the Application to modify.
Right-click the Application name and select Open from the menu.

Alternately, double-click the Application name. The Application page is displayed and the General tab, the Delegated Administrators tab and the Policy Distribution tab are all active.
Select the tab you want to modify or configure and see the appropriate section for parameter details.
- General : Section 4.5.1.1, "Creating an Application"
- Delegated Administrators : Chapter 9, "Delegating With Administrator Roles"
- Policy Distribution: Chapter 7, "Managing Policy Distribution"
Apply or save as necessary.

4.5.1.3 Deleting an Application

To delete an Application instance, proceed as follows:

Find the Application to delete using an advanced search (as documented in Section 5.3.2, "Searching Applications").

The Search Applications page is displayed.
Enter query parameters and click Search.

The results are displayed.
Select the Application name from the results and click Delete.
Choose one of the following methods to search for the Application:

A Delete Warning is displayed.
Click Delete.

The Application is deleted.

Note:

Alternately, expand the Applications information tree in the Navigation Panel and double click the name of the Application to delete. The Application is displayed in the Home area. Click Delete in the upper right corner.

4.5.2 Managing Resource Types

Resource Types specify the full scope of traits for a particular kind of protected resource. It contains one or more resource attributes, and definitions of all possible valid actions that can be performed on the particular kind of resource. An action represents an activity or task in your business process that can be executed on a resource. Actions can be standard (GET and POST to a URL) or custom on a specific business object (transfer to or from a bank account). A Resource instance for a specific target is created from a Resource Type. The following sections describe management operations on Resource Types.

Creating a Resource Type
Modifying a Resource Type
Deleting a Resource Type

4.5.2.1 Creating a Resource Type

To create a Resource Type, proceed as follows:

Display the page for creating a Resource Type by choosing from the following methods:
- Expand the information tree in the Navigation Panel, right-click Resource Types under the particular Application in which the Resource Type will be created and select from the menu.
- In the Home area, select the Application Name under which the Resource Type will be created and click New under Resource Types.
An Untitled page is displayed in the Home area.
Provide the following information for the Resource Type.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful value, though, is recommended as it is displayed in the Administration Console and can be used as a search parameter.
- Name : The name is required and case insensitive.
- Resource Finder : An (optional) class that implements the oracle.security.jps.service.policystore.entitymanager.ResourceFinder interface. It allows resources managed outside of the Policy Store to be consumed. (Reserved for future use.)
- Description : Although optional, it is recommended to provide useful information. The description string is case insensitive.
Add actions allowed by the Resource Type in the Actions section.
1. Click New to display the New Action dialog
2. Enter the name of the action.
  
  The string entered must match the actions for which your application is asking for authorization. If a Permission class is added, the action must be meaningful to it.
3. Click Save.
The Action list is updated with the new action.
Choose one of the following methods to add attributes to the Resource Type being created.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available attributes by performing a simple search on configured Resource instances. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop attributes from the Search Results tab into the area labeled Attributes.
- Find Existing Attribute dialog
  1. In the Attributes section, click Add to display the Find Existing Attribute dialog.
  2. Select the attribute Type from the list.
  3. Enter an (optional) string to match in the Search text box.
  4. Click the arrow icon next to the Search text box to begin the search.
  5. Select the attributes to add and click Add.
    
    Use Ctrl+click to select multiple items from the list.
These attributes are used when instantiating a Resource. See Section 4.5.3.1, "Creating a Resource."
Configure the remaining fields.

The selection changes according to the Resource Type being created.
- Supports Resource Hiearchy - Select Yes or No to set the Resource Type as hierarchical. This means the following when the Resource Type is used to instantiate a Resource:
  - A policy applicable to a Resource created from a hierarchical Resource Type is also applicable to Resources that are its children.
  - Any attribute defined for a Resource created from a hierarchical Resource Type is inherited by Resources that are its children.
- Resource Name Delimiter - Only valid when Supports Resource Hierarchy is enabled. The default delimiter is Slash (/).
- Evaluation Logic - Evaluation logic for a Resource Type can be either a permission class or a default matching algorithm. Define the algorithm here or the permission class below.
- Permission Class - When the evaluation logic is a Permission class, a class name is required and is case sensitive.
- Action Name Delimiter - The specified character is used to separate actions in a list when the Resource Type represents a permission.
- All Action Keyword - If the policy's target contains the defined keyword as an action, the policy will match any action passed in with the authorization request. For example, assume that this parameter is set to ANY and you create the following policy:
```
GRANT user "Michael" action:"ANY" on resource:"Resource1
```
  The decision for authorization requests like Can Michael do 'write' on Resource1? or Can Michael do 'transfer' on Resource1? will return ALLOW. The use of this parameter allows you to create a single Authorization Policy that would be applicable to any valid action for that Resource Type.
Select one of the following from the Save menu.
- Save and Close saves the configuration, renames the tab with the value provided for the Application's Display Name and activates the Delegated Administrators and Policy Distribution tabs.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another Application.

4.5.2.2 Modifying a Resource Type

To modify a Resource Type, proceed as follows:

Choose from the following methods to display the desired Resource Type.
- Expand the information tree in the Navigation Panel to find the Resource Types node under the appropriate Application and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.3, "Searching Resource Types."
- Search for Resource Types using the Navigation Panel's search function and double-click the Resource Type name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Resource Type was created and click Search under Resource Types. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.3, "Searching Resource Types."
When the correct Resource Type name is displayed, select it and click Open to display the details.
Modify as necessary.
Click Apply.

4.5.2.3 Deleting a Resource Type

To delete a Resource Type, proceed as follows:

Choose from the following methods to delete the desired Resource Type.
- Expand the information tree in the Navigation Panel to find the Resource Types node under the appropriate Application and double click it. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Resource Type from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Resource Types using the Navigation Panel's search function and double-click the Resource Type name in the Search Results tab. A search dialog opens in the Home area. Enter criteria for the search and click Search. Select the appropriate Resource Type from the search results and click Delete. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- Select the appropriate Application Name in the Home area and click Search under Resource Types. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Resource Type from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
A Delete Warning is displayed.
Click Delete.

The Resource Type is deleted.

4.5.3 Managing Resources

A Resource represents a specific, secured target in a protected application. Each Resource belongs to a defined Resource Type and can represent software components managed by a container (URLs, EJBs, JSPs) or business objects in an application (reports, transactions, revenue charts).

Note:

Resources can be hierarchical (in that the child resource inherits attributes from parent resources) or non-hierarchical. When organized in a hierarchy (root down), you can add new attributes to the parent resources or overwrite any existing attributes that are inherited.

The following sections describe management operations on Resources.

Creating a Resource
Modifying a Resource
Deleting a Resource

4.5.3.1 Creating a Resource

To create a Resource, proceed as follows

Display the page for creating a Resource by choosing from the following methods:
- Navigate to the Resource Catalog by expanding the applicable Policy Domain node in the appropriate Application node using the Navigation Panel. Right-click Resources from the Resource Catalog node and select New from the menu.
- Select the Application under which you will create the Resource instance from the Home area and click New under Resources.
  
  Note:
  
  This option creates the Resource in the Application's Default Policy Domain.
An Untitled page is displayed in the Home area.
Provide the following information.
- Resource Type: Select from the list. This defines what is displayed in the Instance Attributes and Overwrites table.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
Add or remove the attributes for this Resource from those displayed in the Instance Attributes and Overwrites dialog.

The Overwrites dialog is displayed only in the case of hierarchical Resources.
Select the attributes from the list (use Ctrl+click to select multiple items from the list) and click Add.
Select one of the following from the Save menu.
- Save and Close saves the configuration, renames the tab with the value provided for the Application's Display Name and activates the Delegated Administrators and Policy Distribution tabs.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another Application.

4.5.3.2 Modifying a Resource

To modify a resource, proceed as follows:

Choose from the following methods to display the desired Resource.
- Navigate to the Resource Catalog by expanding the applicable Policy Domain node in the appropriate Application node using the Navigation Panel and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.6, "Searching Resources."
- Search for Resources using the Navigation Panel's search function and double-click the Resource name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Resource Type was created and click Search under Resources. A search dialog opens in the Home area. This search dialog will only query the Default Policy Domain. For information about searching in the Home area, see Section 5.3.6, "Searching Resources."
When the correct Resource name is displayed, select it and click Open to display the details.
Modify the Resource as necessary.
Click Apply.

4.5.3.3 Deleting a Resource

To delete a Resource, proceed as follows:

Choose from the following methods to delete the desired Resource.
- Navigate to the Resource Catalog by expanding the applicable Policy Domain node in the appropriate Application node using the Navigation Panel and double click it. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Resource from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Resources using the Navigation Panel's search function and double-click the Resource name in the Search Results tab. Select the appropriate Resource from the search results and click Delete. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Resource was created and click Search under Resources. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. (This search queries only in the Default Policy Domain.) Select the appropriate Resource from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
A Delete Warning is displayed.
Click Delete.

The Resource is deleted.

4.5.4 Managing Entitlements

After instantiating a Resource, define the actions that can be performed on it in an Entitlement. The actions are defined using the set of legal actions defined in the Resource's parent Resource Type. The following sections describe management operations on Entitlements.

Creating an Entitlement
Modifying an Entitlement
Deleting an Entitlement

Note:

An Entitlement may be created if there are plans to use the same list of Resource and Action pairs in multiple policies. Otherwise, the Resource and Action pair itself can be directly specified as a target when you create an Authorization Policy. See Section 4.5.5, "Managing Authorization Policies" for more information.

4.5.4.1 Creating an Entitlement

To create an Entitlement, proceed as follows.

Display the page for creating an Entitlement by choosing from the following methods:
- Navigate to the Resource Catalog by expanding the applicable Policy Domain node in the appropriate Application node using the Navigation Panel. Right-click Entitlements from the Resource Catalog node and select New from the menu.
- In the Home area, select the Application Name under which the Entitlement will be created and click New from Entitlements.
An Untitled page is displayed in the Home area.
Provide the following information.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Entitlement Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
Choose one of the following methods to add Resources to the Entitlement.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Resources by performing a search on Resource instances. The Resources must be searched from the same Policy Domain in which the Entitlement is being created. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop Resources from the Search Results tab into the area labeled Resources.
- Add Targets pop up search
  1. Click Add in the Targets section.
    
    The Add Targets dialog displays. This will search in the current Policy Domain.
  2. Search for available targets by entering a string.
    
    The resources matching the query are displayed in Search Results. If no search string was entered, a list of all objects of the specified type is returned.
  3. Select your choice(s) and click Add Selected.
    
    The Target(s) are added to the Selected Targets. Use Ctrl+click to select multiple items from the list.
    
    Note:
    
    Alternately, you can click the Resource Expression link under the Resources tab, select a Resource Type, enter a string expression and click Add to Targets. This will search for targets, using the defined criteria, dynamically at runtime. All Resources that belong to the selected Resource Type that contain the string expression are returned, within the context of the administrator privileges.
  4. Click Add Targets.
Add actions to the Resources as follows:
1. Select an added resource from the Resources list to display the resource details in the Resource Details section.
2. Expand the selected row to see the range of actions.
  
  Only the actions allowed for the type of the selected resource are available in this area.
3. Check the desired actions for the Resource in the Actions section.
4. Repeat this procedure for each Resource you have added to the Entitlement being created.
Select one of the following from the Save menu.
- Save and Close saves the configuration, renames the tab with the value provided for the Application's Display Name and activates the Delegated Administrators and Policy Distribution tabs.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another Application.

4.5.4.2 Modifying an Entitlement

To modify an entitlement, proceed as follows:

Choose from the following methods to display the desired Entitlement.
- Navigate to the Resource Catalog by expanding the applicable Policy Domain node in the appropriate Application node using the Navigation Panel and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.7, "Searching Entitlements."
- Search for Entitlements using the Navigation Panel's search function and double-click the Entitlement name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Entitlement was created and click Search under Entitlements. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.7, "Searching Entitlements."
When the correct Entitlement name is displayed, select it and click Open to display the details.
Modify the entitlement as necessary.
Click Apply.

4.5.4.3 Deleting an Entitlement

To delete a Resource, proceed as follows:

Choose from the following methods to delete the desired Entitlement.
- Expand the information tree in the Navigation Panel to find the Entitlement node under the appropriate Application's Resource Catalog and double click it. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Resource from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Entitlements using the Navigation Panel's search function and double-click the Entitlement name in the Search Results tab. Select the appropriate Resource from the search results and click Delete. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Entitlement was created and click Search under Entitlements. A search dialog opens in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Resource from the search results and click Delete. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
A Delete Warning is displayed.
Click Delete.

The Entitlement is deleted.

4.5.5 Managing Authorization Policies

The Authorization Policy is the mechanism that defines the access rights (Grant/Deny). A user, an Application Role or an External Role is granted the rights of the policy. An Authorization Policy must have:

At least one principal which can be a user, External Role or Application Role. Code sources are not allowed as a principal.
At least one target that can be a Resource and Action association (created within the policy) or an Entitlement (created outside the policy and added to it) but not both.A defined effect of PERMIT or DENY.

Note:

Entitlement-based policies correspond closely with business functions. They are recommended in cases in which a business function considers securing a collection of resources; an entitlement can be used in one or more grants.

The following sections describe management operations on Authorization Policies.

Creating an Authorization Policy
Modifying an Authorization Policy
Deleting an Authorization Policy

4.5.5.1 Creating an Authorization Policy

To create a policy, proceed as follows:

Display the page for creating a policy by choosing one of the following methods:
- Navigate to the Policy Domain under the appropriate Application node in the Navigation Panel and expand it. Right-click Authorization Policies from the Resource Catalog node and select New from the menu.
- In the Home area, select the Application Name under which the Authorization Policy will be created and click New from Authorization Policies. (When using this option, the policy will be created in the Default Policy Domain.)
An Untitled page is displayed in the Home area.
Provide the following information.
- Effect: Select Permit if the policy will grant rights or Deny if the policy will deny rights.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
Choose one of the following methods to add Principals to the Authorization Policy.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Principals by performing a search on Users, External Roles or Application Roles. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop Principals from the Search Results tab into the area labeled Principals.
  3. Select Any or All.
    
    If Any, the user must match at least one of the specified principals. For example, if the principals are roles, the user must be a member of at least one of the roles for the Authorization Policy to apply. If All, the user must match all of the specified principals. For example, if the principals are roles, the user must be a member of all of them for the Authorization Policy to apply.
- Add Principals pop-up search
  
  For details on how to use the pop-up search box, see Section 5.1, "Searching with the Administration Console."
  1. Click Add in the Principals section.
    
    The Add Principals dialog displays.
  2. Select the appropriate tab to search for available Principals.
    
    Options are Application Roles, External Roles and Users. You can navigate between tabs and add as many selected Principal types as desired.
  3. Search for the available Principals by entering a string.
    
    The Principals matching the query are displayed in Search Results.
  4. Select your choice(s) and click Add Selected.
    
    The Principal(s) are added to the Selected Principals. Use Ctrl+click to select multiple items from the list.
  5. Click Add Principals.
  6. Select Any or All.
    
    If Any, the user must match at least one of the specified principals. For example, if the principals are roles, the user must be a member of at least one of the roles for the Authorization Policy to apply. If All, the user must match all of the specified principals. For example, if the principals are roles, the user must be a member of all of them for the Authorization Policy to apply.
Choose one of the following methods to add Targets to the Authorization Policy.

This step adds either Resource and action associations or Entitlements or both to the Authorization Policy.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Resources or Entitlements by performing a search. (Be sure to look for these objects in the same Policy Domain to which you are adding the Authorization Policy.) For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop one or more Resources or Entitlements from the Search Results tab into the area labeled Targets. Expanding the added object in Targets allows you to associate an action with it.
- Add Targets pop up search
  
  For details on how to use the pop-up search box, see Section 5.1, "Searching with the Administration Console."
  1. Click Add in the Targets section.
    
    The Add Targets dialog displays.
  2. Select the appropriate tab to search for available Targets.
    
    Options are Entitlements and Resources. You can navigate between tabs and add as many selected Targets as desired.
  3. Search for available targets under the Entitlements tab by entering a string.
    
    The resources matching the query are displayed in Search Results. If no search string was entered, a list of all objects of the specified type is returned.
  4. Select your choice(s) and click Add Selected.
    
    The Target(s) are added to the Selected Targets. Use Ctrl+click to select multiple items from the list.
  5. Search for available targets under the Resources tab by entering a string.
    
    The resources matching the query are displayed in Search Results. If no search string is entered, a list of all objects of the specified type is returned.
    
    Alternately, you can click the Resource Expression link under the Resources tab, select a Resource Type, enter a string expression and click Add to Targets. This will search for targets, using the defined criteria, dynamically at runtime. All Resources that belong to the selected Resource Type that contain the string expression are returned, within the context of the administrator privileges.
  6. Click Add Targets.
Select the Conditions tab to add a condition.

For more information, see Section 4.6, "Using the Condition Builder."
Select the Obligations tab.

An Authorization Policy may have zero, one or more Obligations.
1. Click New to display the New Obligation dialog.
2. Provide a Name and an (optional) Display Name and Description for the New Obligation and click Add.
3. Click New in the Attributes section to add an obligation attribute.
  
  An Obligation has a set of attributes. Each attribute is a name-value pair. The value can be either static or the value of a previously defined attribute. Each obligation should have at least one attribute. See Section 4.5.9, "Managing Attributes and Functions as Extensions" for information.
4. Provide a Name for the attribute in the New Obligation Attribute dialog.
  
  If the obligation attribute is static, select either String, Integer, Boolean, Date or Time for Data Type and provide a Value. If the obligation is an attribute, select Attribute for Data Type and choose from the list of predefined attributes.
5. Click Add.
Click Save to save the Authorization Policy.

4.5.5.2 Modifying an Authorization Policy

To modify a policy, proceed as follows:

Choose from the following methods to display the desired Authorization Policy.
- Expand the information tree in the Navigation Panel to find the Authorization Policies node under the appropriate Application's Policy Domain and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.8, "Searching Authorization Policies."
- In the Home area, select the Application Name under which the Authorization Policy was created and click Search under Authorization Policies. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3.8, "Searching Authorization Policies."
When the correct Authorization Policy is displayed, select it and click Open to display the details.
Modify the policy as necessary.
- Select the Principal to modify.
  
  For more information, see Section 4.5.5.1, "Creating an Authorization Policy."
- Select (or expand) the Target to modify.
  
  For more information, see Section 4.5.5.1, "Creating an Authorization Policy."
- Click the Conditions tab to edit conditions.
  
  For more information, see Section 4.6, "Using the Condition Builder."
- Click the Obligations tab to modify the Obligation or its attributes.
  - To modify the obligation, click Edit from the Obligations table, make changes in the displayed dialog and click Update.
  - To modify an attribute, select the attribute from the Attibutes table and click Edit. Make changes in the displayed dialog and click Update.
  - To delete the Obligation, select it in the Obligations table and click Remove.
Click Apply.

4.5.5.3 Deleting an Authorization Policy

To delete an Authorization Policy, proceed as follows:

Choose from the following methods to display the Authorization Policy search screen.
- Expand the information tree in the Navigation Panel to find the Authorization Policies node under the appropriate Application's Policy Domain, right-click it and select Open. A search dialog opens in the Home area.
- In the Home area, select the Application Name under which the Authorization Policy was created and click Search under Authorization Policies. A search dialog opens in the Home area.
For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
Enter criteria for the lookup and click Search.
Select the appropriate Authorization Policy from the search results and click Delete.

4.5.6 Managing Application Roles in the Role Catalog

Application Roles are defined at the Application level (thus, its name). 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 assigned a different set of privileges for more fine-grained authorization. Membership can be granted statically or dynamically with a Role Mapping Policy.

Note:

A Role Mapping Policy assigns the role to subjects and an Authorization Policy defines the role's access rights.

You can use Application Roles to control access by establishing relationships with the following procedure:

Define Application Roles to represent the functional roles users have in the application.
Map each Application Role to External Roles or individual Users.
Create Authorization Policies to provide the level of access rights (Permit/Deny) required to meet the goals of the Application Roles.
Add the Application Role as a Principal to one or more Authorization Policies.

Application Roles use role inheritance and hierarchy. The inheritance pattern is such that a subject assigned to a role (using a Role Mapping Policy or static role assignments) also inherits any child roles if it is not prohibited by Role Mapping Policies. When an Application Role is referenced as a policy principal, access to the resource for all users assigned to the role is governed by the policy. The following sections describe management operations on Application Roles.

Creating an Application Role
Modifying an Application Role
Mapping External Roles to an Application Role
Mapping an External User to an Application Role
Deleting an Application Role or Removing External Role Mappings

4.5.6.1 Creating an Application Role

The following procedure describes the steps to create a new Application Role. You are not required to add members to the role at the same time and can return to the saved role later. To create an Application Role, proceed as follows:

Display the page for creating an Application Role by choosing one of the following methods:
- Navigate to the Role Catalog under the appropriate Application node in the Navigation Panel. Right-click the Role Catalog node and select New from the menu.
- In the Home area, select the Application Name under which the Application Role will be created and click New from Application Roles.
An Untitled page with four tabs is displayed in the Home area: General (active), Application Role Hierarchy, External Role Mapping and External User Mapping.
Provide the following information under the General tab.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Role Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
- Role Category : A Role Category is a tag you can assign to a role for ease of management. See Section 4.5.8, "Managing a Role Category."
Click Save.

The page is renamed to match the entry provided for Role Name and the Application Role Hierarchy, External Role Mapping and External User Mapping tabs become active. At this point, you can create a policy with this Application Role as the Principal or find a policy with this Application Role as the Principal by clicking Create Policies or Find Policies, respectively. To define the Application Role Hierarchy continue to the next step.
Optionally, select the Application Role Hierarchy tab to define from which roles this Application Role will inherit permissions (Inherits) and for which roles this Application Role will define permissions (Is Inherited By). Hierarchy is not required but if you choose to define it, the following example sub procedure is specific to the former option.
1. Click Inherits.
2. Click Add.
3. Select the radio button that corresponds to the role to which you are adding the hierarchy.
  
  When you add roles to the hierarchy, you can either add the roles to the role under which you are working or to a role that you can select in the Application Role Hierarchy table.
4. Complete the criteria fields in the Add a Role dialog and click Search.
  
  The results display in the Search Results table. Empty strings fetch all roles.
5. Select the role from which this role will inherit permissions in the Search Results table.
  
  Use Ctrl+click to select multiple roles.
6. Click Add.
  
  The selected roles display in the Application Role Hierarchy tab, and the Application Role inherits permissions from them.

For information about external role mapping, see Section 4.5.6.3, "Mapping External Roles to an Application Role." For information about external user mapping, see Section 4.5.6.4, "Mapping an External User to an Application Role."

4.5.6.2 Modifying an Application Role

To modify or view an Application Role, proceed as follows:

Choose from the following methods to display the desired Application Role.
- Expand the information tree in the Navigation Panel to find the Role Catalog node under the appropriate Application, right-click it and select Open. A search dialog opens in the Home area. Enter criteria for the lookup and click Search.
- In the Home area, select the Application Name under which the Application Role was created and click Search under Application Roles. A search dialog opens in the Home area. Enter criteria for the lookup and click Search.
When the correct Application Role is displayed, select it and click Open to display the details in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
Select the tab that contains the parameters you want to modify and click Add.

For information on the available tabs, see:
- Application Role Hierarchy : Creating an Application Role
- External Role Mapping : Mapping External Roles to an Application Role
- External User Mapping : Mapping an External User to an Application Role

4.5.6.3 Mapping External Roles to an Application Role

To map external roles to an application role, proceed as follows:

Choose from the following methods to display the desired Application Role.
- Expand the information tree in the Navigation Panel to find the Role Catalog node under the appropriate Application and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Application Roles using the Navigation Panel's search function and double-click the Application Role name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Application Role was created and click Search under Application Roles. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
When the correct Application Role is displayed, select it and click Open to display the details in the Home area.
Select the External Role Mapping tab.
Click Add to display the Add a Role dialog.
Complete the query fields in the Add a Role dialog and click Search.

Empty strings fetch all roles. The results display in the External Role Search table.
Select the external role to map to by clicking its name in the table.

Use Ctrl+click to select multiple roles.
Click Map Roles.

The selected roles display in the External Role Mapping tab.

4.5.6.4 Mapping an External User to an Application Role

To map an external user to an application role, proceed as follows:

Choose from the following methods to display the desired Application Role.
- Expand the information tree in the Navigation Panel to find the Role Catalog node under the appropriate Application and double click it. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Application Roles using the Navigation Panel's search function and double-click the Application Role name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
- In the Home area, select the Application Name under which the Application Role was created and click Search under Application Roles. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
When the correct Application Role is displayed, select it and click Open to display the details in the Home area.
Select the External Users Mapping tab.
Click Add to display the Add a User dialog.
Complete the query fields in the Add a User dialog and click Search.

Empty strings fetch all roles. The results display in the External User Search table.
Select the user to map by selecting its name in the table.

Use Ctrl+click to select multiple roles.
Click Map Users.

The selected roles display in the External User Mapping tab.

4.5.6.5 Deleting an Application Role or Removing External Role Mappings

To delete an Application Role or remove External Role Mapping from an Application Role, proceed as follows:

Choose from the following methods to display the desired Application Role.
- Expand the information tree in the Navigation Panel to find the Role Catalog node under the appropriate Application, right-click it and select Open. A search dialog opens in the Home area. Enter criteria for the lookup and click Search.
- In the Home area, select the Application Name under which the Application Role was created and click Search under Application Roles. A search dialog opens in the Home area. Enter criteria for the lookup and click Search.
For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
Select the Application Role in the Search Results table and:
- Click Delete to remove the role.
- Select the appropriate mapping in the External Role Mapping table and click Remove.

4.5.7 Managing Role Mapping Policies

Membership to an Application Role can be granted statically or dynamically with a Role Mapping Policy. An Application Role, referenced in a Role Mapping Policy, could grant a user access to the defined resources. The following sections describe management operations on Role Mapping Policies.

Creating a Role Mapping Policy
Modifying a Role Mapping Policy
Deleting a Role Mapping Policy

4.5.7.1 Creating a Role Mapping Policy

To create a Role Mapping Policy, proceed as follows:

Display the page for creating a Role Mapping Policy by choosing one of the following methods:
- Navigate to the appropriate Application node in the Navigation Panel and expand the Role Catalog branch. Right-click Role Mapping Policies and select New from the menu.
- In the Home area, select the Application Name under which the Role Mapping Policy will be created and click New from Role Mapping Policies.
An Untitled page is displayed in the Home area.
Provide the following information.
- Effect: Select Permit if the policy will grant rights or Deny if the policy will deny rights.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Name : The name is required and case insensitive.
- Description : Although optional, it is recommended to provide useful information about the policy. The description string is case insensitive.
Choose one of the following methods to add Application Roles.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Application Roles by performing a search. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop Application Roles from the Search Results tab into the area labeled App Role.
- Add Application Roles dialog
  1. Click Add in the App Role section.
    
    The Search Application Roles dialog displays.
  2. Search for the available Application Roles by entering a string.
    
    The resources matching the query are displayed in Search Results.
  3. Select the principals to add and click Add Application Roles.
    
    Use Ctrl+click to select multiple items from the list.
    
    Note:
    
    For this release, this dialog displays the Search Principals title and Add Principals button.
Choose one of the following methods to add Principals.
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Users and External Roles by performing a search. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop Users and External Roles from the Search Results tab into the area labeled Principals.
- Add Principals dialog
  1. Click Add in the Principals section.
    
    The Search Principals dialog displays.
  2. Search for the available Principals (in this case, Users or External Roles) by entering a string.
    
    The resources matching the query are displayed in Search Results.
  3. Select the principals to add and click Add Principals.
    
    Use Ctrl+click to select multiple items from the list.
Optionally, choose one of the following methods to add Resources (also referred to as Targets).
- Drag and drop
  1. Use the Navigation Panel to list the Application's available Resources by performing a search. For more information, see Section 5.2, "Finding Objects with a Simple Search".
  2. Drag and drop one or more Resources from the Search Results tab into the area labeled Resources.
- Add Targets pop up search
  1. Click Add in the Resources section.
    
    The Add Targets dialog displays.
  2. Choose the Policy Domain that contains the Resource (if applicable).
  3. Enter a string and click Search.
    
    The resources matching the query are displayed in Search Results. If no search string was entered, a list of all objects of the specified type is returned.
  4. Select the appropriate Targets to add and click Add Selected.
    
    The Target(s) are added to the Selected Targets. Use Ctrl+click to select multiple items from the list.
  5. Click the Resource Expression link to add an expression as a Target.
    
    Select a Resource Type, enter a string expression and click Add to Targets. This will search for targets, using the defined criteria, dynamically at runtime. All Resources that belong to the selected Resource Type that contain the string expression are returned, within the context of the administrator privileges.
  6. Click Add Targets.
See Section 4.6, "Using the Condition Builder" for information on using the Condition Builder.
Click Save.

4.5.7.2 Modifying a Role Mapping Policy

To modify a Role Mapping Policy, proceed as follows:

Choose from the following methods to display the desired Role Mapping Policy.
- Expand the information tree in the Navigation Panel to find Role Mapping Policies under the Role Catalog node of the appropriate Application and double click Role Mapping Policies. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- In the Home area, select the Application Name under which the Application Role was created and click Search under Role Mapping Policies. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
When the correct Role Mapping Policy is displayed, select it and click Open to display the details in the Home area.
Modify the policy as necessary.
Click Apply.

4.5.7.3 Deleting a Role Mapping Policy

To delete a Role Mapping Policy, proceed as follows:

Choose from the following methods to display the desired Role Mapping Policy.
- Expand the information tree in the Navigation Panel to find Role Mapping Policies under the Role Catalog node of the appropriate Application and double click Role Mapping Policies. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- In the Home area, select the Application Name under which the Application Role was created and click Search under Role Mapping Policies. A search dialog opens in the Home area. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
When the correct Role Mapping Policy is displayed, select it and click Open to display the details in the Home area.
Double-click the Role Mapping Policy to delete.

The Role Mapping Policy displays in the Home area.
Click Delete in the upper right corner of the Home area.

4.5.8 Managing a Role Category

A Role Category is a tag you can assign to a role for ease of management. You can create or delete a Role Category but you cannot modify them. To create a Role Category, proceed as follows. Instructions to delete a Role Category are detailed after the final step.

Expand the appropriate Application node in the Navigation Panel and double-click the Roles Categories node.

Description of the illustration role_categories.gif

The Role Categories page opens in the Home area.
Click New to display the New Category dialog.
Provide the following information.
- Name
- Display Name
- Description
  
  Description of the illustration new_category_dialog.gif
Click Create.

The new category displays in the Role Categories list.

Description of the illustration new_category_page.gif

To delete a Role Category, expand the appropriate Application node in the Navigation Panel and double-click the Roles Categories node. Select the Role Category to delete and click Delete.

4.5.9 Managing Attributes and Functions as Extensions

Attributes and Functions are definitions organized under the Extensions node of the Application for which they were created. Attribute and function definitions can be used in a Condition or an Obligation. In regards to a Condition, attribute and function definitions can be used to make an optional expression that can be added to a policy to further restrict access to the protected resource. In regards to an Obligation, this optional set of name-value pairs returns additional information, with a policy decision, to the calling application. There are two ways to define an Obligation:

Statically where an attribute with an absolute value is returned.
Dynamically where an attribute value, or a custom function, is evaluated at runtime and the output is returned.

An Attribute can be a value dynamically defined at runtime (for example, the locality of the user) or a value based on the type of protected resource (for example, creation date of a text file). During policy evaluation, attribute values can be passed in by the application or Oracle Entitlements Server can retrieve it using a custom attribute retriever. Attributes must have a defined type. Boolean, integer, date, time and string are Oracle Entitlements Server predefined types. An attribute may be singular or a multi-valued list. A Function is a definition of externally implemented logic. It can be added to a policy as a condition on the policy's outcome. The following sections describe management operations on Attributes and Functions.

Creating an Attribute
Modifying an Attribute
Deleting an Attribute
Creating a Function
Modifying a Function
Deleting a Function

4.5.9.1 Creating an Attribute

To create an attribute, proceed as follows:

Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel.
Right-click the Attributes node and select New from the menu.

An Untitled page is displayed in the Home area.
Provide the following information for the attribute.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
- Category: Select from Resource and Dynamic as a value for this required parameter.
- Type: Select from String, Date, Integer, Boolean, Time.
- Input Values: Select from Single and Multiple.
Select one of the following from the Save menu.
- Save and Close saves the configuration and renames the page with the value provided for the Display Name.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another Attribute.

4.5.9.2 Modifying an Attribute

To modify an attribute, proceed as follows:

Choose from the following methods to display the desired Attribute.
- Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel. Double-click Attributes to open a search dialog in the Home area. For information about searching in the Home area, see Section 5.3.9, "Searching Attributes."
- Search for Attributes using the Navigation Panel's search function and double-click the Attribute name in the Search Results tab. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
When the correct Attribute is displayed, select it and click Open to display the details in the Home area.
Modify the attribute as necessary.
Click Apply.

4.5.9.3 Deleting an Attribute

To delete an attribute, proceed as follows:

Choose from the following methods to display the Attribute.
- Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel. Right-click Attributes and select Open to display a search dialog in the Home area. Enter criteria for the lookup and click Search. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Attributes using the Navigation Panel's search function, right-click the Attribute name in the Search Results tab and select Open to display the Attribute in the Home area. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
Select the Attribute and click Delete.

A Delete Warning is displayed.
Click Yes.

4.5.9.4 Creating a Function

To create a function, proceed as follows:

Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel.
Right-click the Functions node and select New from the menu.

An Untitled page is displayed in the Home area.
Provide the following information for the function.
- Display Name : The display name is optional and case insensitive. Specifying a meaningful display name is recommended since it is displayed in the Administration Console, and provides extra information to help administrators identify objects.
- Name : The name is required and case insensitive. At runtime, this is the string the application passes to determine whether a user is authorized to access this Resource.
- Description : Although optional, it is recommended to provide useful information about the entitlement. The description string is case insensitive.
- Function Class Name: The name of the class that provides the functionality.
- Input Parameter: A list of the types of parameters passed to the function.
- Return Type: Select the data type returned by the function.
- Syntax Preview displays a preview of the function's syntax.
Select one of the following from the Save menu.
- Save and Close saves the configuration and renames the page with the value provided for the Display Name.
- Save and Create Another saves the configuration to the information tree in the Navigation Panel but leaves the Untitled area open for you to create another.

4.5.9.5 Modifying a Function

To modify a function, proceed as follows:

Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel.
Double-click Functions to open a search dialog in the Home area.
Enter search criteria to display the Function.

For information about searching in the Home area, see Section 5.3.10, "Searching Functions."
Select the Function from the Search Results and click Open.

The Function's details are displayed in the Home area.
Modify the Function as necessary.
Click Apply.

4.5.9.6 Deleting a Function

To delete a Function, proceed as follows:

Choose from the following methods to display the Function.
- Navigate to, and expand, Extensions under the appropriate Application node in the Navigation Panel. Right-click Functions and select Open to display a search dialog in the Home area. Enter criteria for the lookup and click Search. Select the appropriate Function from the Search Results. For information about searching in the Home area, see Section 5.3, "Finding Objects with an Advanced Search."
- Search for Functions using the Navigation Panel's search function, right-click the Function name in the Search Results tab and select Open to display the Function in the Home area. For information about searching in the Navigation Panel, see Section 5.2, "Finding Objects with a Simple Search."
Click Delete.

A Delete Warning is displayed.
Click Yes.

4.6 Using the Condition Builder

An optional Condition in a policy rule can be used to further evaluate the applicability of an authorization decision returned in response to a request for access. For example, a Condition can be used to grant access to a resource only on the condition that the request was issued from a specific location or at a specific time.

Note:

Conditions in Role Mapping Policies provide the same functionality, and take the same format, as conditions in Authorization Policies.

A Condition is written in the form of an expression that resolves to either true or false. If the expression resolves to true, the condition is satisfied and the policy is applicable. If the expression does not resolve to true, the policy is not applicable. The expression can operate on attributes, functions or literals. Oracle Entitlements Server contains predefined attributes and functions that can be inserted or you can create custom ones. The literals belong to the supported data types and are constants.

Note:

All Attributes and Functions (both custom and predefined) are created, collected and further managed under the Extensions node of the Application. For more information, see Section 4.5.9, "Managing Attributes and Functions as Extensions."

The Condition Builder allows an administrator to quickly create Condition expressions that can then be added to an Authorization Policy or a Role Mapping Policy. The following procedure illustrates how to use the Condition Builder to create a Condition for your policy. To create a Condition, you either create or modify an Authorization Policy or a Role Mapping Policy. Following one of these procedures will bring you to a step in which you can build a Condition.

Creating an Authorization Policy or
Modifying an Authorization Policy
Creating a Role Mapping Policy
Modifying a Role Mapping Policy

When you get to the appropriate screen, follow this procedure.

Click the Condition tab.
Click Edit Condition.

The Condition Builder (as displayed in Figure 4-1) displays. Note the frame of the Condition expression on the left. The frame contains two Add replaceables and an operator drop down. (The drop down is empty until an operand has been added.) The tabs for exprssion components - Attributes, Functions and Literals - are on the right. You will add components from these tabs to the Expression frame to build your Condition.

Figure 4-1 The Condition Builder

Description of "Figure 4-1 The Condition Builder"
Click the tab that contains the component type you want to add to the Condition.

Figure 4-2 is a screen shot of the Operand Value tabs. The Attributes and Function listed in these tabs are filtered based on the Application in which the policy is being created. For example, a custom Function created within Application 1 will not be visible when the Condition Builder is activated to create a policy within Application 2.

Figure 4-2 Operand Value Tabs

Description of "Figure 4-2 Operand Value Tabs"
Select the line that contains the component you want to add to the Condition and click Add.

Click the blue i to display a Details box with more information regarding the component. Figure 4-3 is a screenshot after having added a SYS_APP attribute which takes a string value.

Figure 4-3 Adding a Literal to the Condition

Description of "Figure 4-3 Adding a Literal to the Condition"
Populate the value on the right of the expression by selecting the appropriate Operand Value and click Add.
Specify the operator on the right of the Condition Builder by clicking the drop down and selecting your choice.

The operator options are dependent on the Operand Value.
Add additional expressions by clicking the last arrow in the expression and selecting AND, OR or NOT from the crop down menu, if applicable.

REMOVE will clear the expression of all components so you may begin again.
Select components for the additional expression from the appropriate Operand Value tabs, if applicable.

You may add as many expressions (and components) as necessary by clicking the last arrow in the current expression and selecting from the Operand Value tabs.
Click Done to complete the Condition.

The following points should be taken into account as you navigate the Condition Builder to create your expression.

The Condition Builder contains Tool Tips on most fields for additional details.
Click the appropriate blue i for information on the Operand Value.
At the minimum, an expression must contain two operands and an operator.
You can compare an Attribute and an Attribute, an Attribute and a Function, an Attribute and a Literal, a Function and a Function, and a Function and a Literal.
The input parameters for Functions can be Attributes, Literals or Functions.
The choice of operators displayed is directly related to the first operand chosen. For example, you cannot do less than or equal to on a string.
The choice of a second Operand Values displayed within an expression is also directly related to the first operand chosen.
REMOVE clears the expression to which it is tied of all components so you may begin again. It does not clear the entire Condition.
The completed Condition (expression) is evaluated by Oracle Entitlements Server at runtime. The interpretation is governed by the rules of precedence.
The outcome of this Condition must be a boolean.

The following sections contain procedures for more complex conditions.

Building a Complex Expression
Passing Parameters to Functions

4.6.1 Building a Complex Expression

This procedure explains how you might build a complex expression using parenthesis.

Follow one of these procedures to bring you to the Condition Builder.
Click the Condition tab.
Click Edit Condition.

The Condition Builder displays as in Figure 4-1.
Click the Attributes tab.
Select the DateAttr custom attribute and click Add.

DateAttr is not a predefined Oracle Entitlements Server attribute so this step assumes a custom attribute has been defined as documented in Section 4.5.9, "Managing Attributes and Functions as Extensions." DateAttr is added to the left of the operator.
Select the equal sign (=) as the operator.
Select the CURRENT_GMT_DATE predefined attribute and click Add.

CURRENT_GMT_DATE is a predefined Oracle Entitlements Server attribute and can be viewed under the Attributes tab. It is added to the right of the operator.
Add more complexity to the Condition by selecting the appropriate AND, OR or NOT operation at the end of the line of code.

Parentheses must match; there must be an equal number of open and closing parentheses. If you select an operation at the end of a line of code, the operation will involve the code itself. If you select an operation at the end of the entire Condition, it will allow you to add on to the Condition as a whole.
Add additional conditions by choosing values from Attributes, Functions or Literals as necessary.
Click Done when finished.

4.6.2 Passing Parameters to Functions

This procedure describes how to pass parameters into a Function.

Follow one of these procedures to bring you to the Condition Builder.
Click the Condition tab.
Click Edit Condition.

The Condition Builder displays as in Figure 4-1.
Click the Functions tab.
Select STRING_EQUAL and click Add.

Figure 4-4 illustrates an added Function and contains placeholders for the two parameters that must be passed to it. This Function will compare the two strings (one the value of a predefined attribute).

Figure 4-4 Adding a Function

Description of "Figure 4-4 Adding a Function"
Select the first parameter if not already.
Click the Attributes tab.
Select SYS_USER and click Add.

The second parameter is highlighted and the Literal tab is activated.
Enter a value for the second parameter and click Add.

For this example, joe. The boolean to the right of the operator is highlighted and the Literal tab is activated.
Choose the appropriate operator.
Click the Boolean replaceable and select whether this function output should be true or false.
Add Additional operands as you see fit.
Click Done when finished.