Skip navigation.
Downloads | Product Documentation | Support

Policy Managers Guide

# Policy Overview

This section covers the following topics:

- What is an AquaLogic Enterprise Security Policy?
- Policy Components
- Resources
- Identities
- Policies
- Declarations

# What is an AquaLogic Enterprise Security Policy?

AquaLogic Enterprise Security is a fine-grained entitlements engine that allows the user to centrally define and manage a set of policies to control access for both application software components (for example URLs, EJBs, and EJB methods) as well as the application business objects (for example accounts and patient records) that make up the application. A set of access control policies is evaluated and enforced locally in the application container so application context can be included as part of the access control decision. A major benefit of using AquaLogic Enterprise Security to implement access control is that it allows you to remove security logic from the application. This enables you to take access control decisions out of the hands of your developers and define and manage access control consistently across multiple applications.

Policies are statements that work together to define access control for your business resources. A resource is any object that represents an underlying application or application component that needs to be protected from unauthorized access. A well-written set of policies accurately represents the access control requirements for your business, is easy to manage, and is designed for maximum efficiency.

You write separate policies to grant or deny access privileges to your business resources to users, groups, and roles under some set of conditions, or constraints. Therefore, before you begin to write policies, you must know the access control requirements of your business, the resources that are to be protected, who the users are and their responsibilities, and what privileges the users are to have on the resources.

There are three types of policies, authorization policies, role mapping policies, and delegation policies, each type having a different function.

- Authorization policies—authorization policies, also referred to as access policies, define what users, groups, or roles have what privileges on what resources. Authorization policies are used to define the access control for application software components (for example, URLs, JSPs, EJBs, and so on), as well as business objects (such as accounts, customer records, and similar items) in the application.
- Role mapping policies—Define what users and groups belong to what roles for what resources. You use role Mapping policies to define how, when, and under what constraints roles are assigned to what users and groups.
- Delegation policies—Once you have written authorization policies and role mapping policies, you can then write delegation policies. Privileges and roles can be delegated. Typically, delegation policies are used to define the constraints under which a privilege or a role that was previously granted to one user is granted to another user, however, the time period for the delegation can be indefinite. You can use delegation policies to assign access privileges previously granted to one user to another user, group, role. You can also use delegation policies to assign roles previously granted to the one user to another user or group.

# Policy Components

All policies follow a syntax that is similar to English grammar. The structure of a policy is similar to a sentence and the policy elements can be thought of as parts of the sentence.

The general syntax for an AquaLogic Enterprise Security policy is as follows:

>     Effect (privilege|role, resource, policy subject, delegator) IF constraint;

A single policy can have multiple privileges, resources, and policy subjects defined.

The functions of each policy component are as follows:

- The Effect can be to grant, to deny, or to delegate a privilege or role. A policy can grant, deny, or delegate a privilege or role on a given resource to a subject under some set of constraints. Grant is used to assign a privilege or a role to an subject. Deny is used to deny a privilege or a role from an subject. Delegate is used to assign a privilege or a role that has been granted to one subject to another subject.
- Privilege|role—a privilege is an action on a resource. A role is name that can be assigned to a set of users, similar to a group. Authorization policies assign privileges. Role mapping policies assign roles. Delegation policies can delegate privileges or roles.
- A resource is a protected object.
- A policy subject can be users, groups, or roles. For authorization policies, policy subjects can be users, groups, or roles. For role mapping policies, policy subjects can be users or groups.
- A delegator is a user, or subject, whose privilege or role is being delegated, or assigned, to another policy subject. Delegation policies that delegate privileges can delegate the privileges from one user to other users, groups, or roles. Delegation policies that delegate roles can delegate the role to other users or groups. You cannot delegate a role from one user to role.
- Constraints are conditions that must be true for the policy to evaluate to true. A broad range of operators and functions can be used to define constraints, but in general, constraints are made up of attribute/value pairs with some comparison operator. Individual constraints can also be combined with logical operators such AND, OR, and NOT. Conditions can include a date, a time, a time period, a day of the week, a day of the month, a day of the year, a location, and other attributes. You may also write custom attributes and use them as conditions. In addition to attributes that you may define specifically for users and groups and then use them as conditions, you can also define different types of declarations and use them as conditions.

Policies must adhere to the following rules:

- Parentheses enclose the privilege or role, resource, policy subject, and delegator, as a group.
- Commas separate the privilege or role, resource, subject, and delegator.
- A delegator cannot be a group or a role.
- The delegator portion of a policy is optional. It is only used for delegation policies.
- A delegator must be a user, not a group or role.
- For authorization policies, policy subjects can users, groups, and roles, however, for role mapping policies, policy subjects are limited to users and groups. Roles cannot be used as policy subjects in role mapping policies.
- You may not delegate to a role to a role, only to a user or group.
- The keyword `IF` indicates a constraint.
- All policies end with a semicolon.

# Resources

A resource is simply an object used to represent an underlying application or application component (or any resource), that can be protected from unauthorized access using authorization policies. Resources are often hierarchical in nature. Resources can be specific application software components managed by the container (for example URLs, EJBs, JSPs, and so on) or any business object in the application. Resources may have attributes, for example bank accounts have owners and transfer limits. Resources are hierarchical and child resources inherit policies and attributes from their parent.

When defining resources you start by defining the top-level resource in the resource tree and then define the resources that make up the tree. Once a resource is defined, you can write authorization policies to grant or deny access privileges to users, groups, or roles for the top-level resource and resources on the tree. So defining a resource tree is a critical requirement to enable you to write policies. For example, if you define a resource named `TellerApp` (see Figure 1-1), you can then write an authorization policy that grants or denies access privileges to the `TellerApp` resource.

Figure 1-1 Resource Mapping

Some typical resources that you might want to secure, include:

- An application, an application window, or a dialog box
- Specific business transactions, such as a money transfer or security trade
- Application controls, such as buttons and menu selections
- Database or directory server structures
- Web pages, servlets, and Enterprise Java Beans (EJB)
- Products or services accessed through a BEA WebLogic Portal

Note: In development mode, you may use the Resource Discovery tool to help define resources for a particular application. For more information, see Resource Discovery.

The following topics describe resource components:

- Resource Attributes
- Privilege Groups
- Privileges

## Resource Attributes

You can associate attributes with resources. An attribute contains information about a characteristic of the resource to which it is associated. Thus, you can use attributes to define additional information about a resource. For example, `filetype` could be a resource attribute that you use to define an html, image, jsp, or pdf file type. Then, you could grant access to all pdf files in a directory by adding the condition: `if filetype = pdf`.

## Privilege Groups

Simply stated, a privilege group is constructed by grouping two or more privileges. A privilege can belong to more than one privilege group. In addition to the privilege groups that are provided in the product, you can define your own with distinct characteristics. Privilege groups are not used in policies. They are simply a way to organize privileges and have no meaning when writing a policy and are only provided to simplify the task of choosing the right privilege.

It is common to define a privilege group that applies to a particular application or set of transactions. You can control access to privilege groups (those provided in the product and those that are user-defined) through delegated administration.

## Privileges

A privilege represents an action or task in your business policy that can be executed on a resource.

What actions can a user can perform on a resource?

Privileges are actions that are granted or denied on a resource. Privileges can be standard actions associated with specific software components (for example `Get` and `Post` for a URL) or a custom action for a business object in an application (for example, transfer for a bank account). The privileges that may be granted or denied on a particular resource are limited by the operations supported by the resource. For example, a simple text file may support Read, Write, Copy, Edit, and Delete operations. Similarly an executable (.exe) may support operations such as Copy, Delete, and Execute. A more complex resource may support far more complex privileges. For example, a checking account application may support operations such as deposit, withdrawal, view account balance, view account history, transfer to savings, and transfer from savings.

In addition to the privileges that are provided in the product, you can define your own privileges. You can also organize privileges into logical groups for ease of management.

You use privileges to write authorization polices as follows:

`grant(privilege, resource, policy subject[users, groups, roles]) IF constraint;`

For example, if you have the business security requirement: "Only lead tellers can open an account," you might define an `OpenAccount` privilege and a LeadTellers role. Now, to grant `LeadTellers` (the role) the authority to open an account (the privilege), the authorization policy might look like this:

>     grant(//priv/OpenAccount, //app/policy/TellerApp, //role/LeadTellers)
>     if time24 in [900..1700] AND
>     dayofweek in [Monday..Friday];

With this policy is deployed, only tellers who are assigned the `LeadTellers` role are allowed to used the `TellerApp` to open an account between the hours of 9:00 AM and 5:00 PM (a time-of-day constraint) on Monday through Friday (a days-of-the-week constraint).

# Identities

Identity definition includes the definition of directories, users, groups, and roles. An identity directory serves as a logical container for a collection of identity attributes, users, groups, and roles. An identity directory typically represents a set users, groups, and roles. Therefore, the first step in defining identities is to define the directory. Once you have defined the identity information, you can use it to write authorization policies and role mapping policies. In authorization and role mapping policies, the user identity (users, groups, roles) is defined in the policy subject.

You may define multiple identity directories. The number of directories you define depends on the level of granularity needed to separate your user community. You may want to have one global directory containing all users. In this case, you can populate a single directory using multiple external repositories. Having one directory for all users requires that you have a unique name for each user and group across all of your identity repositories. If you cannot guarantee this when you integrate your identity repositories, then you should probably maintain separate directories. For example, you might have one directory for customers, one for employees, and one for partners.

The following topics describe user identity components:

Identity Attributes

Groups

Users

Roles

## Identity Attributes

A user or group can contain attributes that further describe their characteristics—who they are and what they can do; these are referred to as identity attributes. You can use these identity attributes to define dynamic constraints for a role to which a user or group belongs. For example, consider that account balance is an attribute of a user. To allow customers with an account balance over $100,000 to access the premier banking features of your application, you define `accountbalance` as an attribute and apply it to each customer in the `bankusers` group (`sgrp`). Next, you define the `premierbanking` role and write a role mapping policy that only allows access to the application if the customer is in the `premierbanking` role. Then you write an authorization policy that defines the privileges you want to allow on the `bankapp` resource and define the policy subject as the role `premierbanking`.

>     Grant(//role/premierbanking,//app/policy/bankapp, //sgrp/bankusers/customers/) if accountbalance > 100000

This role mapping policy allows customers who are assigned the `premierbanking` role to access the resource called `bankapp` if they have an `accountbalance` of over $100,000.

## Groups

A group is typically a collection of users that have something in common, such as a department, a job function, or a job title. For example, a group named Accounting might contain users in the accounting department. It is important to realize that this does not directly reflect what access rights they have. A group can contain either users or other groups; users who are assigned to a group are called group members. Nested memberships of groups within a group form a hierarchy. Group membership can be assigned only from within the same directory. Groups have a static identity, or name, which you assign.

If a group has subgroups and an authorization policy grants certain privileges to a group, the members of subgroups will have the same privileges. This is true because each member of a subgroup is by default a member of the parent group.

In addition to managing groups in the policy database, AquaLogic Enterprise Security can use group membership information from a corporate directory. Typically, a group hierarchy is based on an organizational model of the company, although this is not a requirement. For example, the source of your user data might be an employee database, where users belong to four groups: the employee group, the Sales department group, the London office group, and the star-salesmen group.

Thus, you want to create groups of users, whose tasks are related and for whom the policy enforcement is the same. In the following example (see Figure 1-2), Tellers are assigned to the Teller Group.

Figure 1-2 Users and Groups

## Users

A user corresponds to an individual who makes a request to access a resource, although a user can also be an automated process that accesses a resource. You can assign users to groups from the same directory. Each user within a directory must have a unique identity or user name. Users can be associated with certain characteristics or attributes that contain information about the user. Keep in mind that it may be more efficient to write policies that apply to a collection of users defined as a role or a group. AquaLogic Enterprise Security supports both.

## Roles

A role is a set of privileges that can be assigned to a user or group. The actual access privileges assigned to a role are defined by the authorization policy that you write for the role. You write a role mapping policy to assign the role to users and/or groups, thereby granting the access privileges defined by the authorization policy. Once you have written a role mapping policy to assign the role to a user or a group, you can also write a delegation policy to delegate the role from one user to another user or group. Like groups, roles allow you to restrict access to resources for many users or groups at once. However, unlike groups, roles are computed dynamically at runtime based on role mapping policies. Additionally, roles can be associated with specific resources in an application.

# Policies

To specify the access control requirements for your resources you write a set of policies that may include role mapping policies, authorization policies, and delegation policies.

The following topics describe the different types of policies:

- Role Mapping Policies
- Authorization Policies
- Delegation Policies
- Summary of Policy Differences

## Role Mapping Policies

How are user roles assigned?

The basic format of a role mapping policy is as follows:

>     grant|deny(role, resource, policy subjects[users, groups]) IF constraints;

Where the `grant|deny` portion is the policy effect and either allows or prohibits the role to the policy subject for the given resource, the `role` defines the role, the `resource` is the application or application component to which the role is scoped, policy subjects specify which users and groups belong to the role, and `constraints` define any conditions that apply to the role.

For example:

>     GRANT(//role/accountants, //app/policy/acme/payroll, //user/acme/Bill/);

grants the `accountants` role to bill on the `payroll` resource.

At runtime, user access privileges are computed based on the roles the user has been assigned—either explicitly or through a role mapping policy—at the time an access request is made. Unlike groups, which are relatively static and persist for duration of the runtime session, roles are highly dynamic and are assigned to users by processing role mapping policies. Role mapping significantly reduces the number of policies required and makes features like role delegation easier to manage.

A role may apply to one or more users and groups and usually refers to some set of related tasks. For example, a group of bank tellers might have access to the same set of applications (resources) to perform specific banking tasks; thus, you might have a role called `TellerRole` and assign the BankTellers group to that role. Figure 1-3 shows a group of tellers who belong to a Teller group that has membership in the `CustomerService` role that, in turn, has access to the Teller resource. The privileges, or actions, allowed on that resource are defined by an authorization policy, which you also define. Now, anyone who is not in the `CustomerService` Role does not have access to the Teller resource. You can also apply restrictions and conditions to limit access to the resource at runtime by defining the constraints such as time-of-day or day-of-the-week on the role mapping policy and/or the authorization policy.

Figure 1-3 Role Mapping Policy

## Authorization Policies

What the user is allowed to do to this resource?

The syntax of an authorization policy is as follows:

>     grant|deny(privilege, resource, policy subjects[users, groups, roles]) IF constraints;

Where the `grant|deny` portion is the policy effect and either allows or prohibits the privilege to the policy subject for the given resource, the `privilege` defines the privilege, resource defines the application or application component of the privilege, policy subjects specify which users, groups, and roles are granted the privilege, and `constraints` defines any conditions that apply to the privilege.

For example, the policy:

>     GRANT(//priv/any, //app/policy/acme/payroll, //user/acme/agarcia/);

grants any privileges supported by the `acme` `payroll` application (the resource) to the user `agarcia` in the `acme` directory. And, the policy:

>     GRANT(//priv/any, //app/policy/acme/payroll, //role/accountants/);

grants any privileges supported by the `acme` `payroll` application (the resource) to the role `accountants` so only users and groups who have been granted the `accountants` role are granted this privilege. Therefore, before anyone can gain this privilege, a role mapping policy has to be written and deployed that grants this role to a user or a group.

It is important to note that by default, all access to a resource is denied until an authorization policy is written and deployed that explicitly grants an access privilege, or an entitlement, on that resource to a user, group, or role. If the authorization policies only grants an entitlement on a resource to a role, then a role mapping policy must be written and deployed that assigns a user or a group the defined role.

If an authorization policy denies a previously granted entitlement, the deny 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. For example, the `DENY` authorization policy:

>     DENY (//priv/view, //app/policy/acme/payroll, //sgrp/acme/receptionist/);

denies the view privilege related to the `acme` payroll application to everyone belonging to the group named `receptionist` in the `acme` directory.

## Delegation Policies

The syntax of a delegation policy is as follows

>     DELEGATE (privilege|role, resource, policy subject, delegator) IF constraint;

A `DELEGATE` policy that delegates a privilege allows you to share the privileges of one user with another user, group, or role. You may also add a constraint that restricts this sharing to a certain time of day or day of the week, for example:

>     DELEGATE (//priv/any, //app/policy/acme, //user/acme/joe/, //user/acme/larry/) if dayofweek in [Monday..Friday];

At runtime, this policy delegates any privileges that `larry` (the delagator) has on the `acme` application to `joe` if the day of the week is Monday, Tuesday, Wednesday, Thursday, or Friday.

A `DELEGATE` policy that delegates a role allows you to share a role of one user with another user or group. You may also add a constraint that restricts this sharing to a certain time of day or date range, for example:

>     DELEGATE (//role/accountants, //app/policy/acme, //user/acme/joe/, //user/acme/bill/) IF ThisMonth = December;

delegates the role accountants on the `acme` application from `bill` (the delagator) to `joe` at runtime if the current mouth is December.

## Summary of Policy Differences

Table 1-1 summarizes the functions of authorization and role mapping policies and highlights the differences.

Table 1-1 Summary of Policy Differences

Policy Component | Authorization Policy | Role Mapping Policy
--- | --- | ---
Effect (Grant, Deny, or Delegate) | GRANT permits the specified privilege to a user, group, or role. DENY denies the privilege to a user, group, or role. | GRANT permits the specified role to the specified user or group. DENY denies the role to the specified user or group.
Privilege | The privilege granted or denied. | NA
Role | NA | The role granted or denied.
Resources | The resource to which the privilege is granted or denied. | The resource to which the role is granted or denied.
Policy Subjects | The user, group, or role to which the privilege is granted or denied. | The user or group to which the role is granted or denied.
Delegator | The user whose privilege is delegated. | The user whose role is delegated.
Constraints | Conditions under which the privilege is granted, denied, or delegated. | Conditions under which the role is granted, denied, or delegated.

# Declarations

A declaration is a variable that represents either a predefined value (for example, days of the week) or a value that is dynamically defined at runtime (the date). You use declarations in policies as attributes. To help you design policies, built-in declarations are pre-defined for your use. You can also define custom declarations to suit your requirements.

You can define four types of declarations:

- Constants
- Enumerated Types
- Attributes
- Evaluation Functions

## Constants

A constant is a named value or set of values that does not change at runtime. You can reference constants in policies. For example, if you set a constant named `Rate` to 12, policies can then refer to the constant `Rate` rather than using its literal value, 12. Using constants in policies makes them more readable and makes changes to values that are used across of set policies easier

Constants are especially useful if the value changes periodically and you use the constant in more than one location. For example, if you enter a rate value 12 into multiple policies, you need to individually change each one. Instead, if you use the constant Rate, you can edit the value once and have it take effect in every policy that refers to the constant.

## Enumerated Types

An enumerated type is a type that consists of a predefined list of values from which you create constants and multi-valued attributes. The product comes with a number of predefined enumerated types and allows you to define your own. For example, you could define the enumerated type "color" with the values of "red", "green", or "blue".

## Attributes

Attributes represent characteristics that define dynamic values, users, groups, and configurations. Attributes may be associated with users or groups (identity attributes), resources (resource attributes), or policy requests (dynamic attributes). Attributes may be descriptive, may be used to configure policy engine behavior or manage delegated administration, or used in forming policy as part of the policy constraint.

Attributes must have a defined type, which denotes the range of legal values that it may have. A number of predefined types exist: such as string, integer, date, time, IP address, or you can use custom enumerated types. The value of the attribute may be assigned to only one instance of an attribute. An attribute may be a multi-valued list.

## Evaluation Functions

An evaluation function is a named function that you can use in a policy constraint to perform more advanced operations. Each function may have a number of parameters and returns a Boolean result of true of false.

AquaLogic Enterprise Security provides a number of pre-defined evaluation functions and also allows you to declare your own custom evaluation functions. You can use a predefined function in your application by using a plug-in extension that a programmer creates specifically for your application. To use an evaluation function you must register it as a plug-in with the authorization and role mapping providers used in the Security Service Module (SSM) configuration and declare it in a policy.