Policy Managers Guide

Advanced Topics

This topic describes more advanced aspects of writing role mapping and authorization policies. The following topics are covered here:

Designing More Advanced Policies

All policies, simple or complex, follow the same standard syntax:

GRANT|DENY|DELEGATE (privilege|role, resource, subject, delegator) IF constraint;

You can extend the policy syntax to encompass very complex situations by grouping policies and adding constraints.

For more information, see the following topics:

Multiple Components

You are not limited to one role, privilege, resource or subject per policy. You may specify sets by enclosing them in brackets [ ] and separating the individual items with commas. For example:

GRANT(any, //app/policy/MyApp, [//user/ORG/USER21/, //user/ORG/USER22/]);

Policy Constraints

A constraint is a statement that limits when or under what circumstances permission is granted, denied or delegated. All constraints start with the keyword IF. Simple constraints usually contain two values separated by an operator. The following example shows an authorization policy with a simple constraint:

GRANT(//priv/any, //app/policy/MyApp, //sgrp/ORG/allusers/) IF purchaseAmount < 2000;

In this policy, any user of the resource MyApp who is in the ORG directory is allowed to spend any amount less than $2000.

Constraints are very useful because they allow your application to have different responses based on dynamic application, data, business environment, or real-time conditions. For example, you might use a constraint to grant a user access to a resource only during certain hours of the day.

To limit the user in the previous example to having privileges only in December and January, you would add the constraint:

IF month IN [december, january]

To limit the user to accessing the application from a computer with a particular static IP address, you would add the constraint:

IF clientip = 207.168.100.1

Several types of attributes are provided that are automatically computed for you (see Declarations).

Once a grant result is determined at runtime by the Authorization and Role Mapping Engine (ARME) for a particular resource, the rest of the applicable GRANT policies, which may contain additional constraints, are ignored. Therefore, if your business logic requires the evaluation of multiple constraints, you must combine them into a complex constraint using an AND operator to achieve the desired result. For example, given the following two policies:

GRANT(//priv/any, //app/policy/MyApp, //sgrp/ORG/allusers/) IF purchaseAmount < 2000;

GRANT(//priv/any, //app/policy/MyApp, //sgrp/ORG/allusers/) IF month IN [december, january];

The conditions under which allusers would be granted access would be determined by which policy the ARME evaluates first. If the goal is to grant access only if both constraints are true, you must combine these policies into one policy using the AND operator as follows:

GRANT(//priv/any, //app/policy/MyApp, //sgrp/ORG/allusers/) IF purchaseAmount < 2000 AND month IN [december, january];

For more information on combining multiple constraints into one policy, see Boolean Operators.

The following topics provide more information on constraints:

Comparison Operators

Constraints support the comparison operators listed in Table 4-1.

Table 4-1 Comparison Operators
Symbol	Operation	Applicable Types
=	Equal to	All
!=	Not equal to	All
>	Greater than	All except String
<	Less than	All except String
=>	Greater than or equal to	All except String
=<	Less than or equal to	All except String
LIKE	Matches regular expression	String
NOTLIKE	Does not match regular expression	String
IN	Included in a list	List of any type
NOTIN	Not included in a list	List of any type

Regular Expressions

There are two comparison operators, LIKE and NOTLIKE, that are used to perform regular expression matching on attribute values or string literals. This is typically used for pattern matching on resource names. For example, the following policy provides the GET access privilege to all JPGs in a web application (//app/policy/MyWebApp).

GRANT(//priv/GET, //app/policy/MyWebApp, //role/webusers)

IF sys_resource LIKE ".*\\.JPG";

The regular expression syntax follows certain policies.

Any character that is not a special character matches itself. Special characters are:

   +     *     ?     .     [     ]     ^     $

A backslash (\) followed by any special character matches the literal character. For example:

"\*u"

matches "u".

A period (.) matches any character. For example:

".ush"

matches any string containing the set of characters, such as "Lush" or "Mush".

A set of brackets ([]) indicates a one-character regular expression matching any of the characters in the set. For example:

"[abc]"

matches either "a", "b", or "c".

A dash (-) indicates a range of characters. For example:

"[0-9]"

matches any single digit.

A caret (^) at the beginning of a set indicates that any character outside of the set matches. For example:

"[^abc]"

matches any character other than "a", "b", or "c" not including an empty string.

The following policies are used to build a multi-character regular expressions.

Parentheses (( )) indicate that two regular expressions are combined into one. For example:

(ma)+

matches one or more instances of "mad's".

The OR character ( | ) indicates a choice of two regular expressions. For example:

bell(y|ies)

matches either "belly" or "bellies".

A single-character regular expression followed by an asterisk (*) matches zero or more occurrences of the regular expression. For example:

"[0-9]*"

matches any sequence of digits or an empty string.

A single-character regular expression followed by an plus sign (+) matches one or more occurrences of the regular expression. For example:

"[0-9]+"

matches any sequence of digits but not an empty string.

A single-character regular expression followed by a question mark (?) matches either zero or one occurrence of the regular expression. For example:

"[0-9]?"

matches any single digit or an empty string.

A concatenation of regular expression matches the corresponding concatenation of strings. For example:

[A-Z][a-z]*

matches any word starting with a capital letter.

When you use a regular expression that contains backslashes, the constraint evaluator and the regular expression operation both assume that any backslashes are used to escape the character that follows. To specify a regular expression that exactly matches "a\a", create the regular expression using four backslashes as follows:

LIKE "a\\\\a"

Likewise, with the period character "." you need to include two backslashes in the expression:

LIKE "\\."

Constraint Sets

There are two operators, IN and NOTIN, used to test the memberships of sets in your constraint. A constraint set is a definition of a set of items, notated by one or more values separated by commas, enclosed in square brackets, and prefaced with either the keyword IN or NOTIN. For example, rather than writing:

. . . IF NextMonth = january or

. . . NextMonth = february or

. . . NextMonth = march;

You can write:

. . . IF NextMonth IN [january, february, march] ;

The keyword IN means in this set of values, and NOTIN means not in this set of values. Neither keyword is case sensitive.

You can also specify a range of values in a set of constraints. For example, the statement:

IF age NOTIN[1..100]

says if the age value is not between 1 and 100 (inclusive), then the statement is true. The keywords IN and NOTIN work well with attributes based on enumerated types and constant sets.

String Comparisons

You can test for specific text strings in your constraints by using the keywords LIKE and NOTLIKE. For example, assume you have a user attribute called GroupID. This attribute contains a string of data indicating information about the group the user belongs to:

GroupID = "59NY20BREQ";

To check for and exclude users in the New York office, you can test the GroupID attribute for NY as follows:

(Grant policy) IF GroupID NOTLIKE "*NY*";

where * represents any number of characters. Similarly, if you want to ensure that the user was in New York, you can add this constraint:

(Grant policy) IF GroupID LIKE "*NY*";

Similar to IN and NOTIN, LIKE and NOTLIKE are not case sensitive.

To compare a string to a policy element in the constraint, replace the first characters of the element with a wildcard. Normally, the system does not evaluate a policy element as a string. For example, to compare a user, enter the constraint using the following format:

IF user like "??user/acme/Joe/";

Boolean Operators

You can build complex policy constraints by using logical operators. Boolean operators allow you to string multiple constraints together and to have the whole constraint return true only if certain patterns of the component constraints are true. For instance, if the whole constraint is only true if both component constraints are true.

If one of them is not true, then the whole constraint is not true, as the following example:

(whole constraint) is true IF (first constraint is true) AND (second constraint is true)

Or in another example, where it is true if either component is true:

(whole constraint) is true IF (first constraint is true) OR (second constraint is true)

Boolean operators are nothing more than a way to make these kinds of statements. You can write a complex Boolean constraint like this:

IF userBudget < 2000 AND ThisMonth = December

This constraint is only true if userBudget is less than $2000 and the current month is December. Table 4-2 lists the three Boolean operators allowed.

Table 4-2 Boolean Operators
Operator	Description
`AND`	Each component must be true.
`OR`	At least one component must be true.
`NOT`	The component cannot be true.

The third Boolean operator is NOT, which simply reverses the truth of a constraint. For example, if you want to make sure it is not December, you can write:

IF NOT ThisMonth = December

The use of these Boolean operators can get as complex as you want. For example, you can have the following constraint:

IF A AND B OR NOT C

In English, this means, If both A and B are true or if C is not true, then the constraint is true. With a little thought, that is easy enough, but what about a complex constraint, such as:

IF A AND B OR C AND NOT D

Does it mean, if A and B are true or C is true and D is not true, grant the privilege, or does it mean, if A and B or C is true and D is not true, grant the privilege, or does it mean something else?

Associativity and Precedence

One way to decipher Boolean expressions is to understand keyword precedence, which is the order in which keywords are evaluated, and associativity, which is the direction in which terms are grouped. The order of precedence is:

NOT
AND
OR

AND and OR are left associative and NOT is right associative. That is, with AND and OR the system always looks to the immediate left of the keyword for the first value and to the immediate right for the second value. With NOT, the system only looks to the immediate right because NOT does not compare two or more values; it affects only one value. If our earlier example is evaluated using associativity and precedence, it means, If either both A and B are true or if C is true and D is not, the constraint is true.

Grouping with Parentheses

Rather than remembering the policies about associativity and precedence, the easiest thing to do is to use parentheses to logically group your AND, OR, and NOT statements.

In the previous example:

IF A AND B OR C AND NOT D

you can evaluate the statement by applying the policies of associativity and precedence or you can logically group the statements in parentheses as follows:

IF (A AND B) OR (C AND NOT D)

This eliminates ambiguity from the statement. It becomes clear that there are two constraints: (A AND B) and (C AND NOT D), and that one of those constraints must be true for the statement to be true because the two statements have an OR between them.

Changing the location of the parentheses can change the meaning of the statement. For example:

IF (A AND B OR C) AND (NOT D)

changes the statement completely. Now there are two constraints: (A AND B OR C) and (NOT D), in which both must be true for the statement to be true.

You may nest parentheses within parentheses to clarify or change the logic of the statement. For example:

IF ((A AND B) OR C) AND (NOT D)

is the same statement as the previous example, but it is now even clearer. However, if the parentheses are changed slightly, as in:

IF (A AND (B OR C)) AND (NOT D)

the meaning completely changes.

To understand complex grouped statements with parentheses, follow these policies:

Evaluate the statements within parentheses first.
If there are nested parentheses, evaluate the inner ones first.
Once the statements in parentheses are evaluated, evaluate the other statements.
If necessary, use associativity and precedence on the simplified statements.

Boolean Operators and Constraint Sets

Rather than building long OR or AND statements, you can define sets of constraints for your policies. A constraint set defines a set of items. For example, rather than writing:

If ThisMonth = january OR ThisMonth = february

OR ThisMonth = march

you can write:

IF ThisMonth IN [january, february, march]

The keyword IN means in this set of values, and NOTIN means not in this set of values.

You can also specify a range of values in a set of constraints. For example, the following statement:

IF age NOTIN[1..100]

says if the age value is not between 1 and 100 (inclusive), then the statement is true.

The keywords IN and NOTIN work well with attributes based on enumerated types and with constant sets.

You may be wondering about the value of constraint sets when the constraint statement is nearly as long as the chain of ORs that you would instead have to write. Besides the ability to specify ranges of values, the real benefit to constraint sets is that you can predefine them as constants (Constant Declarations). Using the previous example:

IF ThisMonth in [january, february, march]

using a predefined a constant list called FirstQuarter, you can write:

IF ThisMonth in FirstQuarter

rather than the longer bracketed statement.

Declarations

Declarations allow you to add new keywords to the policy language. These keywords can represent new data types, constants, attributes, or evaluation functions. Declaration names must start with a letter or an underscore. There are four types of declarations:

Constants-States one definition for a value that is used over and over.
Enumerated Types-Defines the structure of the other declarations.
Attributes-Contains data and must have a declared type. There are several types of attributes, including identity attributes (user and group attributes), resource attributes, and built-in system attributes.
Evaluation Functions-Returns a true or false value from a plug-in.

For programmers, type declarations are enumerated types. Type declarations declare the composition of the enumerated type and define an ordered list of acceptable values. Attributes and evaluation functions declare an instance (variable) of a built-in or enumerated type. Attributes are based on predefined or user-defined types, and evaluation functions are based on Boolean types.

For more information on declarations, see the following topics:

Constant Declarations

A constant is a named value or set of values that does not change at runtime. For instance, if you set a constant named Rate to 12, policies can then refer to the constant Rate rather than using its literal value, 12. You use constants to:

make policies more readable
make policy-wide value changes 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 it.

Simple Constant

Here are some examples of simple constant declarations:

CONST Insurance = "home";

CONST InterestRate= 12;

Constants can contain other constants in their value:

CONST ClosurePoints = 2;

Or even enumerated types:

CONST FavoriteVehicle = Motorcycle;

If you enclose Motorcycle in quotation marks, this constant would contain a string without any special meaning. If you use Motorcycle without quotation marks, it is recognized as the special value Motorcycle of type Vehicles.

Constants List

A constant can also contain a list of more than one value. For example, you may define a constant called MyColors with the values red, green, blue, white and black.

Constant lists differ from enumerated type lists. Types are used to restrict the values an attribute may contain. For example, an integer may only contain numerals and a constant list is simply a declared list or range of values with no implied order. A constant list always has an underlying type. In the previous example, the underlying type is a string. You can also create lists of any other type.

The rules for defining constant lists are as follows:

Ensure all the constants in a list represent the same data type, including enumerated types.
Use commas to separate the items in the list.
Use square brackets [ ] to enclose the whole list.
Enclose strings in the list with quotation marks.
If values in a list are a range, indicate the range with two dots. For example, [1..100]. A list of one item is still a valid list, as long as you enclose it in brackets.

Here are some examples of constant lists:

CONST MyPets = ["Dogs", "Cats", "Birds"];

CONST CurrentAge = [1..120];

CONST WorkWeek = [monday..friday];

CONST Transportation = [Motorcycle];

You can even place another constant list within a constant list, like this:

CONST FamilyPets = ["Ferrets", "Birds", MyPets];

One benefit of a constant list is that it saves you from having to write multiple policies or string-together constraints to test if a value belongs in a group. Without constant lists, you would need to compare your value to each independent constant, rather than perform one quick test to see if the value belongs in the list. For example, given the constant list:

CONST Manager = ["Bert", "Marty", "Sandy"];

If you want to find out if your string attribute called Active contains a value that is in the Manager list, you could write constraints to test for these three possibilities:

IF Active = "Bert"

OR Active = "Marty"

OR Active = "Sandy"

or you could simply write:

IF Active IN Managers

As mentioned before, there is no implied order to the Manager list. So, even if Bert is clearly a more privileged Manager than Sandy, the following test is invalid.

If "Bert" > "Sandy"

For the test to work, you need to create an enumerated type containing the names of the three managers.

Enumerated Type Declarations

An enumerated type defines a class or group of values from which you can create constants and attributes. It is a template for constants and attributes. For example, an attribute of the type integer (a predefined, built-in type) may only have integer values. Many attributes can use the same type declaration, but each attribute is limited to one type, and this type cannot change without deleting and recreating the attribute. For example, you could have dozens of integer attribute variables, but each one is based on the same integer type declaration. Think of an enumerated type declaration as a cookie cutter and attributes as the cookies.

Pre-Defined, Built-In Enumerated Types

The following types are pre-defined and built into the product and are available for you to use. They cannot be modified.

date - A type that limits the data to the format MM/DD/YYYY and allows you to compare date values and date ranges within constraints.
integer - A type that contains a whole number with no decimal places that may be negative, positive, or zero. You can use integers in comparisons and ranges.
ip - A type that limits the data to the format allowed for IP (Internet Protocol) addresses: xxx.xxx.xxx.xxx, where xxx is any numeral between 0 and 255, inclusive. You can compare IP addresses, but when defining ranges of IP values, the host number, which is represented by the last three digits, is allowed to vary.
string - A type that contains an alphanumeric text value. Strings do not allow comparison or range operations because they are not ordered. However, you can use wildcard comparisons using LIKE and NOTLIKE operations.
time - A type that limits data to the format HH:MM:SS and allows you to compare time values and time ranges within constraints.

Note: Different types of declarations cannot have the same names as they share the same namespace. For example, you cannot have a constant and an attribute both named account_number. In addition, the values of enumerated types share this namespace. So, continuing with our example, you could not create constants or attributes with the values Crows, Ducks, or Geese (or Birds).

User-Defined Types

You can also create custom types. For example, you might create a type called Insurance that contains the values Truck, Car and Motorcycle. You would declare it like this:

enum_Insurance = (Truck,Car,Motorcycle)

Once you declare a type, you must declare an attribute to use the type in your policy. You can declare an attribute based on your new type like this:

cred Transportation : Insurance;

Once declared, you must give the attribute a value, like this:

Transportation = Motorcycle;

As mentioned earlier, you can compare the value based on your type by testing if the value is greater to or less than a value in the list. For example, to make your list order represent the relative level of insurance of a vehicle, you might use this constraint to see if your Transportation attribute is greater than a Car enumeration:

IF Transportation > Car

If Transportation is a Motorcycle, given the order of the list defined earlier, this would return TRUE and your constraint allows implementation of the policy.

Attribute Declarations

An attribute is a variable that you can use in policies. Attributes store values that are predefined or dynamically defined at runtime.

Declaring an attribute allows you to associate an instance of that attribute with an identity or a resource. For example, you can declare a identity attribute named "email" of type "string", and then associate email addresses to users.

Attributes make policies more legible by replacing certain constraint values with logical names. You can use attributes to put values in constraints that depend on conditions unknown when you write the policy, such as timeofday. Attributes contain values for your input data that your policies can manipulate. That is, they can serve as variables, for example, account_balance could be used as an attribute.

There are several ways to use attributes:

Resource Attribute-Provides a value defined and associated with a resource.
Identity Attribute-Provides a value defined and associated with a user or group.
Dynamic Attribute-Provides a value computed or retrieved when the policy is evaluated.

System Attribute - A dynamic attribute that is computed automatically by the Authorization Provider and available for use in your policy. These attributes usually begin with the prefix sys_.
Time and Date Attributes - System attributes that provide time and date information.

Attributes are specific instances of a declared type. For example, an attribute of the type integer can only contain an integer value. Attributes can represent any type, whether provided as part of the product or defined by you. Here are some examples of attribute declarations:

cred month : month_type;
cred timeofday : time;
cred pencils_swiped : integer;

For a description of the different types of attributes, see the following topics:

Resource Attributes

Resource attributes store information about the entity to which they belong. For example, the Banking application might have an attribute called Version that contains the current version number for the application, denoted as a string.

Resource attributes behave differently from identity attributes. While they do inherit attributes and their values, they do not merge any values of redundant attributes. If the same attribute exists in more than one place in a tree, the resource first attempts to take the attribute from itself. Failing that, the resource takes the value of the attribute from the first resource above it on the tree that contains the attribute. The attributes of the same name on still higher nodes are ignored; once an instance of the attribute is found, the search ends.

For example, assume that you have an application resource called Banking that contains a variety of banking features. Deposit is a resource of the ATMCard application, which in turn is an application node below the Banking organization node. If both the ATMCard resource and the Banking application have the Version attribute defined with a value (and Deposit does not), Deposit inherits the value of the Version attribute from ATMCard. The Banking Version attribute is ignored.

Identity Attributes

User attributes store information about an individual user. For instance, you could have an attribute called AgeRange that stores a range of dates. Attributes are associated with a directory through a directory schema. The schema states that all users of a given directory have a given set of available attributes. Additionally the schema determines if the attribute value is a list.

You can also assign attributes to groups (although groups may only contain list attributes). Thus, users can inherit the attributes of all groups to which they belong. However, a user can still have a unique value for an inherited attribute. If you do not assign the user attribute a value, then the user inherits the value of the attribute from the group. This is how group attributes provide default attribute values for users who are members of those groups. If a user has the same attribute as a group, but a different value is assigned to the user attribute, the value of the user attribute always takes precedence of the value of the group attribute.

Even an empty string, " ", is considered a value for purposes of this rule. Therefore, if you do not assign a value, the user attribute does not take precedence over a group attribute of the same name. However, if you placed an empty string in the user attribute, it does take precedence.

Group attributes behave very differently from user attributes. Group attribute values are cumulative — if the same attribute exists in more than one place in the inheritance path of a user, the values of the attributes are merged and passed on to the user. For example, assume you have a user called Bob, and Bob is a member of the Manager group, which in turn is a member of the Employee group. If both Manager and Employee both have an attribute called WorkPlace with the values primary and secondary respectively, Bob would inherit a WorkPlace attribute with the value primary and secondary (a list attribute). In fact, to support this merging of attribute values, all group attributes must be list attributes. If the attribute merging finds the same value more than once, it eliminates the redundancy from the final list value.

Static Attributes

Many attributes are specific instances of a declaration type. These attributes are often user (identity) attributes. For example, if you had a type called ColorType, you might have the static credentials HairColor and EyeColor, which are both of type ColorType. You can attach these static attributes to a user. Table 4-3 lists some examples of user attributes.

Table 4-3 User Attributes
Instance	Type
`MonthBorn`	`month_type`
`ArrivalTime`	`time`
`Pencils_needed`	`integer`

As previously discussed, there are several attribute types. Attributes differ from constants in that their value may change, but not the name and value type. Depending on the user making the request, a different value can be calculated for the attribute. In contrast, constants have a static value, as well as a static name and type. The declaration for a user attribute is attached to one or more directories. Because of this, all users in the same directory have the same user attribute names but not necessarily the same values for those attributes. Attributes can be applied to users, groups, and resources; however, each one behaves a bit differently.

Dynamic Attributes

A dynamic attribute is an attribute with a value that may change at policy evaluation time. Dynamic attributes have their value set by the provider, your application, or through a plug-in function. These attributes can have any type of value.

Additionally, plug-ins can be registered to compute the value of dynamic attributes. These plug-ins can retrieve the values of other attributes and use them to compute the attribute value needed.

Time and Date Attributes

Numerous time and date system attributes are pre-defined and built in. Most system attributes allow you to use comparison and range operators. Table 4-4 lists the built-in time and date attributes provided for you to use.

Table 4-4 Built-In Time and Date System Attributes
Attribute	Value	Range or Format
time24	integer	0-2359
time24gmt¹	integer	0-2359
dayofweek	Dayofweek_type	Sunday-Saturday
dayofweekgmt	Dayofweek_type	Sunday-Saturday
dayofmonth	integer	1-31
dayofmonthgmt	integer	1-31
dayofyear	integer	1-366
dayofyeargmt	integer	1-366
daysinmonth	integer	28-31
daysinyear	integer	365-366
minute	integer	0-59
minutegmt	integer	0-59
month	month_type	January-December
monthgmt	month_type	January-December
year	integer	0-9999
yeargmt	integer	0-9999
timeofday	time	`HH:MM:SS`
timeofdaygmt	time	`HH:MM:SS`
hour	integer	0-23
hourgmt	integer	0-23
currentdate	Date	`MM/DD/YYYY`
currentdategmt	Date	`MM/DD/YYYY`

¹gmt is an abbreviation for Greenwich Mean Time

Request Attributes

There is a set of system attributes that contain details of the request. Table 4-5 describes these attributes and provides and example of each one.

Table 4-5 Built-In Request System Attributes
Attribute	Value	Range or Format
`sys_defined`	Evaluation function	Returns true if all arguments passed to it are defined attributes (either single valued or list). Using an undefined attribute in a policy causes a runtime error. This can occur when the value of the attribute is determined from the application code, either through the context handler or the resource object. If there is a chance that the attribute does not have a value, then use the `sys_defined` evaluation function to ensure that a value exists before it is used. For example `grant(...) if sys_defined(foo) and foo = "bar";`
`sys_external_attributes`	list of strings	A resource attribute set through the Administration Console on an application resource to indicate what attributes are needed for dynamic evaluation. This contains a list of attribute names.
`sys_rule_subj_q`	string	Qualified subject user or group name in the currently evaluated policy: `//user/ales/system/`
`sys_rule_subj`	string	Unqualified subject user or group name in the currently evaluated policy: `system`
`Servername`	string	Name of the server, where an ARME process is running.
`sys_rule_obj_q`	string	Qualified resource name for the currently evaluated policy: `//app/policy/foo`
`sys_rule_obj`	string	Unqualified resource name for the currently evaluated policy: `foo`
`sys_rule_priv_q`	string	Qualified current policy privilege: `//priv/write`
`sys_rule_priv`	string	Unqualified current policy privilege: `write`
`sys_subjectgroups_q`	list of string	List of groups to which the current user belongs: ["`//sgrp/ales/admin/`," "`//sgrp/ales/managers/`"]
`sys_subjectgroups`	list of strings	List of unqualified group names to which user belongs: ["`admin`", "`managers`"]
`sys_dir_q`	string	Directory of the user: `//dir/ales`
`sys_dir`	string	Directory of the user, unqualified form: `ales`
`sys_user_q`	string	Current user: `//user/ales/system/`
`sys_user`	string	Current user: unqualified form: `system`
`sys_obj_type`	enumeration	Set through the Administration Console on the resource. Valid values include: Organizational node (orgnode) Application node (appnode) Binding node (bndnode) Application Binding node (bndappnode) Resource node (resnode)
`sys_obj_distribution_point`	Boolean enumeration {yes, no}	Distribution point set through the Administration Console on the resource. Setting this to yes, displays the resource on the distribution page as a potential point of distribution.
`sys_suppress_rule_exceptions`	Boolean enumeration {yes, no}	Set through the Administration Console to indicate whether to continue evaluation if a policy with missing data is encountered.
`sys_app_q`	string	Name of the binding resource for the resource on which query is performed: `//app/policy/ALES/admin`
`sys_app`	string	Unqualified name of the binding resource for the resource on which the query is performed: `admin`
`sys_obj_q`	string	Resource on which the query is performed: `//app/policy/foo/bar`
`sys_obj`	string	Resource on which the query is performed: `bar`
`sys_priv_q`	string	Effect of the current policy: `//priv/foo`
`sys_priv`	string	Unqualified form of the effect of the current policy: `foo`
`sys_privilege`	string	Unqualified name of the action on which the resource is being queried. The following two policies are equivalent: `grant( //priv/READ, //app/policy/library, //role/Reader);` `grant( any, //app/policy/library, //role/Reader) if sys_privilege="READ";` The attribute can also be used in a role-mapping policy. For example, the following policy assigns the role `Reader` to all users if the requested action is `READ`: `grant( //role/Reader, //app/policy/library, //sgrp/asi/allusers/) if sys_privilege="READ";`
`sys_direction`	enumeration	Defines the direction of authorization: once, post or prior.

Evaluation Function Declarations

An evaluation function is a declaration that returns one of two values: true or false. These values come from a predefined function and are included by using a plug-in extension that a programmer creates specifically for your application. Additionally, you can use any of the built-in evaluation functions available in all applications.

For instance, your programmer might create a plug-in for your accounting application that includes an evaluation function called Overdrawn that contains the results of a calculation of whether the account was overdrawn for that month. A constraint for a deny policy might use that function like this:

[Deny user access to something] IF Overdrawn();

Like functions and procedures in programming, evaluation functions can take zero or more parameter values, which are passed to the plug-in. For example, if you wanted to provide the overdrawn amount, you might use it like this:

[Deny user access to something] IF Overdrawn(500);

Evaluation functions can dynamically take different numbers or types of parameter values each time they are referenced in a policy. It is up to the programmer writing the evaluation function code to correctly handle the parameters.

Authorization Caching Expiration Functions

Authorization caching allows the system to cache the result of an authorization call and use that result if future identical calls are made. The cache is smart and automatically invalidates itself if there is a policy change or other client side change that would affect the authorization results. However, the cache is not smart enough to know when authorization decisions depend on dynamic data. Dynamic data includes date and time values, as well as evaluation plug-ins that reference external sources. If you are using authorization caching you need to set expiration times on policies that reference dynamic data. For additional information on caching, see Authorization Caching, in Integrating ALES with Application Environments.

Note:

By default, authorization caching is turned on.

Table 4-6 lists the expiration functions for the authorization cache that let you set an expiration time for the authorization decision. This way you can instruct the cache to only hold the value for a given period of time, based on Greenwich Mean Time (GMT), or not to hold it at all.

Table 4-6 Expiration Functions for Authorization Cache
Function	Argument Type	Description
`valid_for_mseconds`	`integer`	Valid for a given number of milliseconds.
`valid_for_seconds`	`integer`	Valid for a given number of seconds.
`valid_for_minutes`	`integer`	Valid for a given number of minutes.
`valid_for_hours`	`integer`	Valid for a given number of hours.
`valid_until_timeofday`	`time`	Valid until the specified time on the date the evaluation is performed.
`valid_until_time24`	`integer`	Valid until the specified time on the date the evaluation is performed.
`valid_until_hour`	`integer`	Valid until the specified hour on the date the evaluation is performed.
`valid_until_minute`	`integer`	Valid until the specified minute of the hour the evaluation is performed.
`valid_until_date`	`Date`	Valid until the specified date.
`valid_until_year`	`integer`	Valid until the specified year.
`valid_until_month`	`month_type`	Valid until the specified month of the year the evaluation is performed.
`valid_until_dayofyear`	`integer`	Valid until the specified day of the year the evaluation is performed
`valid_until_dayofmonth`	`integer`	Valid until the specified day of the month the evaluation is performed.
`valid_until_dayofweek`	`Dayofweek_type`	Valid until the specified day of the week the evaluation is performed.
`valid_until_timeofday_gmt`	`time`	Valid until the specified time on the date the evaluation is performed in GMT time.
`valid_until_time24_gmt`	`integer`	Valid until the specified time on the date the evaluation is performed in GMT time.
`valid_until_hour_gmt`	`integer`	Valid until the specified minute of the hour the evaluation is performed in GMT time.
`valid_until_minute_gmt`	`integer`	Valid until the specified minute of the hour the evaluation is performed in GMT time.
`valid_until_date_gmt`	`Date`	Valid until the specified date in GMT time.
`valid_until_year_gmt`	`integer`	Valid until the specified year in GMT time.
`valid_until_month_gmt`	`month_type`	Valid until the specified month of the year the evaluation is performed in GMT time.
`valid_until_dayofyear_gmt`	`integer`	Valid until the specified day of the year the evaluation is performed in GMT time.
`valid_until_dayofmonth_gmt`	`integer`	Valid until the specified day of the month the evaluation is performed in GMT time.
`valid_until_dayofweek_gmt`	`Dayofweek_type`	Valid until the specified day of the week the evaluation is performed in GMT time.

For example, suppose you have the following authorization policy:

GRANT(//priv/order,//app/restaurant/breakfast,//group/customers/allusers) if hour < 11;

With authorization caching enabled (it is enabled by default), the results of this grant decision is cached until the next policy distribution.

On the other hand, if you call the valid_until_hour() expiration function in the authorization policy as follows:

GRANT(//priv/order,//app/restaurant/breakfast,//group/customers/allusers) if hour < 11 and valid_until_hour(11);

with authorization caching, the result of this policy is cached until 11:00 AM, at which time it expires. Therefore, with authorization caching enabled, it is important to update your time dependent policies appropriately.

Policy Inheritance

Using policy inheritance can reduce the number of policies that have to written to protect a set of resources. The following topics describe how inheritance works:

Group Inheritance

Users or groups inherit the right (privilege or role) of any group to which they belong, either directly or through their parents. Group inheritance allows each user in the group to assume all the group rights to which they are members, either directly or indirectly through their parent groups (or the groups of their parents). Both users and groups can have parent groups but only groups can have children. Group inheritance is very powerful as it allows you to define entitlements once and have the policy apply to all members.

Note:

BEA recommends that you define your role mapping policies using groups, rather than individual users. Role mapping policies written using users should be used for exceptions and to handle unusual or infrequent situations.

It is important to note that parent groups usually have fewer rights than their children. As you move from the bottom of the resource tree to the top, the groups inherit the rights of their ancestors and are directly granted.

Direct and Indirect Group Membership

The immediate members of a group are called direct members. Direct members appear immediately below their parent on the inheritance tree. A member that has an inherited membership is called indirect member. The collection of all groups available, either directly or through inheritance, is referred to as group closure.

Group inheritance behavior is affected by how group membership searching is configured in your security providers. Two attributes control group membership searching:

GroupMembershipSearching—Specifies whether group membership searching traverses all the group's children or a limited number of levels of child groups.
MaxGroupMembershipSearchLevel—If GroupMembershipSearching is set to limited, specifies the number of levels of child groups to search. A value of 0 indicates only direct group memberships will be found. A positive number indicates the number of levels to go down.

If you set GroupMembershipSearching to unlimited, all indirect members will be considered when a policy is evaluated. If you set GroupMembershipSearching to limited, only indirect members within the number of levels of inheritance specified by MaxGroupMembershipSearchLevel will be considered.

Restricting Policy Inheritance

Policies are inherited in a number of ways:

Policies written on a resource apply to the descendants of that resource.
Policies written on a group apply to all members of that group.
Policies written on a role apply to everyone who has been granted that role.
Policies written on the any privilege apply to all privileges.

You can restrict policy inheritance by limiting its applicability. For example, you can limit the applicability of a GRANT role mapping policy by adding a constraint. The following policy illustrates this:

GRANT(//role/admin, //app/policy/www.myserver.com/protected, //sgrp/acme/manager/) IF sys_obj_q = //app/policy/www.myserver.com/protected;

where: sys_obj_q is a system attribute on which the query is performed.

The sys_obj_q constraint keeps this policy from being applicable to the descendants of the protected resource, thus blocking policy inheritance.

Resource Attribute Inheritance

Like users and groups, descendant resources also inherit the attributes of any parent resource. Resource inheritance allows each child resource in the tree to assume all of the attributes of the parent resource. Resource attribute inheritance is also very powerful as it allows you to define attributes on the parent resource, and have the attributes be inherited to all child resources automatically.

Note:

BEA recommends that you define your attributes on parents, rather than individual child resources. When an attribute is explicitly defined for a child, the attribute overrides any inherited value. Policies written directly for child resources should be used for exceptions or short-lived policies so as to handle unusual circumstances.

WebLogic Resource Type Conversions and Resource Trees

This section describes how ALES converts the different resource types supported by WebLogic Server, WebLogic Portal, AquaLogic Data Services Platform, and AquaLogic Service Bus and how they are represented in a resource tree in the Administration Console.

Table 4-7 lists the resource types supported for WebLogic Server, WebLogic Portal, AquaLogic Data Services Platform, and AquaLogic Service Bus.

Table 4-7 Supported Resource Types
Target System	Supported Resource Types
WebLogic Server	`<adm>`, `<app>`, `<com>`, `<eis>`, `<ejb>`, `<jdbc>`, `<jms>`, `<jndi>`, <ld>, `<svr>`, `<url>`, `<web>`, `<webservices>`
WebLogic Portal	All WebLogic Server resources plus `<wlp>`.
AquaLogic Data Services Platform	All WebLogic Server resources plus <`ld`>.
AquaLogic Service Bus	All WebLogic Server resources plus <`wlsb-proxy-service`> and <`alsb-proxy-service`>.

Understanding Resource Nodes

An authorization policy involves a resource, action, subject and attributes. Every resource is represented as a node within a tree, and the node is referenced using a path-like expression. The nodes are delimited by the `/' character and can include the following hierarchy of nodes:

root node
application deployment parent node
application node
resource type node
resource parent node
resource node

Root Node

The root node of resources in ALES is a node named //app/policy.

Application Deployment Parent Node

Typically a node called an application deployment parent follows the root node. Using multiple application deployment parent nodes helps to organize resources according to their physical, organizational or logical structure. The application deployment parent can be set in the Administration Console under the authorization provider.

Application Node

The application deployment parent is followed by the application node that corresponds to an application a resource is associated with. Not every resource belongs to a particular application (for example, a JDBC resource); in that case, the keyword shared substitutes for the name of the application.

Resource Type Node

The next level in the resource path is the resource type node. The name of this node corresponds to a resource type being addressed, for example, jms, ejb, jndi, etc.

Resource Parent Node

The resource type node is followed by the resource parent node. The resource parent node helps to organize resources within an application and its value depends on the type of the resource.

Resource Node

The final element in a resource description is the name of the resource itself, which follows the resource parent node.

Thus, to address any resource in the resource tree, it is necessary to know the following resource path elements:

application deployment parent
application name
resource type
resource parent
resource name

The application deployment parent depends only on the configuration of the authorization provider; the remaining four elements vary from one resource type to another.

Table 4-8 gives an example of how the different resource type can be represented in the Administration Console resource tree.

Table 4-8 Examples of Mapping Resource Types to Resource Nodes
Resource Type	Sample Resource Tree Conversions
`<adm>`	`//app/policy/ALES/shared/adm //app/policy/ALES/shared/adm/Configuration //app/policy/ALES/shared/adm/FileDownload //app/policy/ALES/shared/adm/FileUpload //app/policy/ALES/shared/adm/ViewLog`
`<app>`	`//app/policy/essdemo/myapplication/app //app/policy/essdemo/anotherapplication/app`
`<com>`	`//app/policy/essdemo/comapplication/com/classpackage/classname`
`<eis>`	`//app/policy/essdemo/shared/eis`
`<ejb>`	`//app/policy/essdemo/ess/ejb/netuix.jar //app/policy/essdemo/ess/ejb/netuix.jar/PortalCustomizationManager`
`<jdbc>`	`//app/policy/essdemo/shared/jdbc/ConnectionPool //app/policy/essdemo/shared/jdbc/ConnectionPool/MyPool-DB`
`<jms>`	`//app/policy/essdemo/shared/jms/queue //app/policy/essdemo/shared/jms/queue/jms`
`<jndi>`	`//app/policy/essdemo/shared/jndi/jms //app/policy/essdemo/shared/jndi/weblogic //app/policy/essdemo/shared/jndi/weblogic/jms //app/policy/essdemo/shared/jndi/weblogic/jms/MessageDrivenBeanConnectionFactory //app/policy/essdemo/shared/jndi/weblogic/jms/S:MedRecServer //app/policy/essdemo/shared/jndi/weblogic/management //app/policy/essdemo/shared/jndi/weblogic/management/home //app/policy/essdemo/shared/jndi/weblogic/management/home/localhome`
`<svr>`	`//app/policy/essdemo/shared/svr`
<url>	//app/policy/essdemo/ess/url/demolaunch //app/policy/essdemo/ess/url/demolaunch/launch.portal //app/policy/essdemo/ess/url/demolaunch/framework //app/policy/essdemo/ess/url/demolaunch/framework/skins //app/policy/essdemo/ess/url/demolaunch/resources //app/policy/essdemo/ess/url/demolaunch/resources/images
<webservices>	//app/policy/essdemo/shared/webservices
<wlp>	//app/policy/essdemo/ess/wlp/essWeb/com_bea_p13n //app/policy/essdemo/ess/wlp/essWeb/com_bea_p13n/Page //app/policy/essdemo/ess/wlp/essWeb/com_bea_p13n/Desktop //app/policy/essdemo/ess/wlp/essWeb/com_bea_p13n/Book //app/policy/essdemo/ess/wlp/essWeb/com_bea_p13n/Portlet
<ld>	//app/policy/essdemo/shared/ld //app/policy/myrealm/RTLApp/ld/DataServices/RTLServices/CustomerView.ds/CUSTOMER/ORDERS/ORDER_SUMMARY/OrderDate

Resource Paths and Policies for Common Resources

This section describes the values of resource path elements for most popular resource types. For each resource type, we describe how to specify the resource path and privileges, list dynamic resource attributes are available, and give examples of policies for that resource type. In the examples in this section, we assume that the application deployment parent node is //app/policy/AppParentNode.

EJB Resources

Table 4-9 shows the mapping of the resource path elements for an EJB resource.

Table 4-9 EJB Resource Path Elements
Element Name	Value
application name	Same as the EJB application name
resource type	`ejb`
resource parent	Same as the EJB module name
resource name	The name of the EJB

EJB Resource Path Example

For the purposes of this example, suppose you have an EJB application named MyEjbApplication and a module named MyManagers, configured by the following EJB application declaration:

<Application Name="MyEjbApplication" Path="./applications"             StagingMode="nostage" TwoPhase="true">
  <EJBComponent Name="MyManagers" Targets="myserver" URI="managers.jar"/>
</Application>

Listing 4-1 shows how an EJB named AccountService could be defined in the standard EJB ejb-jar.xml deployment descriptor:

Listing 4-1 EJB Configuration

<enterprise-beans>
<!-- Session Beans -->
  <session>
    <display-name>AccountService</display-name>
    <ejb-name>AccountService</ejb-name>
    <home>com.bea.security.examples.ejb.AccountServiceHome</home>
    <remote>com.bea.security.examples.ejb.AccountService</remote>
    <ejb-class>ejb.AccountServiceSession</ejb-class>
    <session-type>Stateless</session-type>
    <transaction-type>Bean</transaction-type>
  </session>
</enterprise-beans>

The fully qualified resource path of the AccountService stateless session bean defined by the configuration in this example would be:

//app/policy/AppParentNode/MyEjbApplication/ejb/MyManagers/AccountService.

EJB Resource Privilege Mappings

The privilege required to access an EJB resource is the method name called on the EJB. For example, assume that the AccountService bean has a business method called getBalance(). To be able to call the getBalance() method, the user must be granted the getBalance privilege. In order for the user to be able to instantiate the remote interface by calling the create() method on the EJB home interface, the user must be granted the create privilege.

EJB Resource Dynamic Resource Attributes

The following attributes are supported by EJB resources and can be used as a part of an authorization policy:

application

The name of the application

module

The name of the module

ejb

the name of the EJB

method

the name of the method

methodinterface

One of the values Home, Remote, LocalHome, or Local

Param<N>

A value of the Nth parameter in the method, e.g. Param1, Param2...

For an example that illustrates EJB resources, see WLS_SSM_HOME/examples/EJBAppExample .

JNDI Resources

Table 4-10 shows the mapping of the resource path elements for a JNDI resource.

Table 4-10 JNDI Resource Path Elements
Element Name	Value
application name	`shared`
resource type	`jndi`
resource parent	The JNDI resource path
resource name	Not used

JNDI Resource Path Example

Listing 4-2 is an extract from weblogic-ejb-jar.xml that defines the JNDI name of the AccountService EJB used in EJB Resource Path Example.

Listing 4-2 JNDI Name Definition

<weblogic-ejb-jar>
  <weblogic-enterprise-bean>
    <ejb-name>AccountService</ejb-name>
    <stateless-session-descriptor></stateless-session-descriptor>
    <reference-descriptor></reference-descriptor>
    <jndi-name>AccountService</jndi-name>
  </weblogic-enterprise-bean>
</weblogic-ejb-jar>

The fully qualified resource name that corresponds to the physical JNDI name of the AccountService EJB home interface would be:

//app/policy/AppParentNode/shared/jndi/AccountService

JNDI Resource Privilege Mappings

The privilege for a JNDI call is the JNDI action name. The privilege value can have one of the following values:

modify

Required whenever an application modifies the JNDI tree in any way (that is, adding, removing, changing). This includes the bind(), rebind(), createSubContext(), destroySubContext(), and unbind() methods.

lookup

Required whenever an application looks up an object in the JNDI tree. This includes the lookup() and lookupLink() methods.

list

Required whenever an application lists the contents of a context in JNDI. This includes the list() and listBindings() methods

JNDI Dynamic Resource Attributes

The following dynamic attributes are supported by JNDI resources and can be used as a part of an authorization policy:

application

Always shared.

path

The JNDI resource path.

action

The JNDI action name (modify | lookup | list).

JNDI Resource Policy Examples

The following policy grants the group Everyone a privilege to perform the lookup operation on any JNDI resource. Note that the resource //app/policy/AppParentNode/shared/jndi must be a virtual one.

grant(//priv/lookup, //app/policy/mybank/shared/jndi, //role/Everyone) if true;

The following policy grants the role Admin a privilege to modify a JNDI resource named DataSource. This will allow a user who has been assigned the Admin role to perform such operations as bind() and unbind().

grant(//priv/modify, //app/policy/mybank/jndi/DataSource, //role/Admin) if true;

URL Resources

Table 4-11 shows the mapping of the resource path elements for a URL resource.

Table 4-11 URL Resource Path Elements
Element Name	Value
application name	The name of the web application that contains the resource
resource type	`url`
resource parent	The context path of the web application
resource name	The resource URI after the context path

URL Resource Path Example

In this example, assume that:

there is a web resource accessible through the URL http://localhost/helloworld/HelloWorld.jsp
the web server configuration file references the web application as HelloWorldApp with the context path /helloworld

To protect the resource, it is necessary to know how the JSP page is represented in the resource tree. In this example, the elements of the resource path are:

Application Name - the name of the web application,. HelloWorldApp
Resource Type - url
Resource Parent - the context path of the web application, helloworld
Resource Name - the JSP name, HelloWorld.jsp

The resulting resource representation is:

//app/policy/AppParentNode/HelloWorldApp/url/helloworld/HelloWorld.jsp

URL Resource Privilege Mappings

In case of a URL resource, the privilege name is mapped to the HTTP request method name: GET, POST, PUT, HEAD, DELETE, TRACE, CONNECT, etc.

URL Dynamic Resource Attributes

The following dynamic attributes are supported by URL resources and can be used as a part of an authorization policy:

application

The name of the web application.

contextpath

The context path of the web application.

uri

The URI of the resource.

httpmethod

The HTTP method (same as privilege).

transporttype

The transport guarantee required to access the URL resource, as it appears in the corresponding <transport-guarantee> element in the deployment descriptor. The value can be one of INTEGRAL or CONFIDENTIAL.

authtype

The name of the authentication scheme used to protect the servlet. The value can be one of: BASIC, FORM, CLIENT_CERT or DIGEST.

pathInfo

Extra path information associated with the URL sent by the client when it made a request.

pathtranslated

Extra path information after the servlet name but before the query string is translated to a real path.

querystring

The query string that is contained in the request URL after the path.

remoteuser

The login of the user making the request, if the user has been authenticated.

requestedsessionid

The session ID specified by the client.

requesturi

The part of this request's URL from the protocol name up to the query string in the first line of the HTTP request.

requesturl

The URL the client used to make the request. The returned URL contains a protocol, server name, port number, and server path, but it does not include query string parameters.

servletpath

The part of this request's URL that calls the servlet.

characterencoding

The character encoding used in the body of the request.

contenttype

The MIME type of the body of the request.

locale

The preferred Locale of the client.

protocol

The name and version of the protocol, for example, HTTP/1.1.

remoteaddr

The Internet Protocol address of the client or last proxy that sent the request.

remotehost

The fully qualified name of the client or the last proxy that sent the request.

scheme

The name of the scheme used to make this request, for example, http, https, or ftp.

servername

The host name of the server to which the request was sent.

serverport

The port number to which the request was sent.

issecure

A boolean indicating whether this request was made using a secure channel, such as HTTPS.

HTTP Request Context Elements

In addition, HTTP request context elements such as servlet attributes, URL query parameters, HTTP request headers and cookies are available as name/value pairs. This section describes how to access the following elements while creating authorization policy constraints:

The attributes that correspond to servlet attributes, URL query parameters, HTTP request headers and cookies are case insensitive; however, an assumption that the attribute names are case sensitive will slightly improve the performance.

If names of a servlet attribute, URL query parameter, HTTP request header, or cookie collide, only one attribute will be available in policy constraints. The order the framework searches for a matching attribute is:

URL query parameters
servlet attributes
HTTP request headers
cookies

Servlet Attributes

Servlet attributes are name/value pairs that can be internally added to a request by a servlet container. Usually the attributes are added by calling method setAttribute of the ServletRequest interface. The policy attribute names correspond to the names of servlet attributes. The names are represented as strings and case insensitive.

URL Query Strings

The attribute names that correspond to the parameters in a URL query string are the same as the parameter names. The names are represented as strings and are case insensitive. The attributes refer to the query string variable encoded within the request. For example, if a URL includes a query such as ?test=endcoded%20char, the parameter can be accessed in the constraint of an authorization policy in the following way:

"if test= "encoded char"

HTTP Request Headers

The attribute name of an HTTP request header corresponds to the name of the header. The name is returned as a string and is case insensitive. Examples of the headers often available are: date, if-modified-since, referrer, or user-agent.

Note:

The date header, which is usually a date type, is returned as a string.

Cookies

The attribute names that correspond to cookies in an HTTP request are the same as the cookie name in the request. The names are returned as strings and case insensitive. The value of the cookie returned is application specific and may need further decoding. For example, if you are using the ALES cookie, the attribute name is:

"ALESIdentityAssertion"

URL Resource Policy Examples

The following policy grants user anonymous (any unauthorized user) a privilege to view current currency exchange rates (the page currentRates.jsp) but only if the connection is secure (for example, through HTTPS).

grant( //priv/GET, //app/policy/mybank/bankapp/url/currencyExchange/currentRates.jsp, //user/myusers/anonymous/) if issecure=yes;

The following policy grants the role Manager a privilege to post new currency exchange rates (the page postNewRates.jsp) but only if the user updates the data from local machine.

grant( //priv/POST, //app/policy/mybank/bankapp/url/currencyExchange/postNewRates.jsp, //role/Manager) if remotehost="localhost";

Let us imagine a web application that allows a customer to buy stocks online. When the customer clicks on the link mybroker/buyStocks.do, the browser sends an HTTP request that is mapped to a Java servlet. The servlet is responsible for fetching balances of all customer's accounts and calculating the customer's purchasing power, the amount of money he or she can spend on buying new stocks. Then the servlet then sets a request attribute named purchasingPower and forwards the request to a page located at mybroker/buyStocks.jsp The mybroker/buyStocks.jsp shows the customer's purchasing power and asks about the amount he or she wants to spend.

The mybroker/buyStocks.jsp page should not be displayed if a customer's purchasing power is not positive. The following rule grants access to the page only if a customer has a positive purchasing power by checking the purchasingPower servlet attribute.

grant( //priv/GET, //app/policy/mybank/bankapp/url/mybroker/buyStocks.jsp, //role/Client) if purchasingPower>0;

Again, let us imagine an application that allows a customer to trade stocks online. Before the customer can trade stocks, he or she must open a brokerage account. The account can be opened online by clicking on the mybroker/openAccount.jsp link. The first page that is displayed contains a trading agreement text and asks the customer to accept it. The checkbox is linked to an HTML form parameter named customerAgreed. When the HTML form is posted, this parameter is set to true if the customer has accepted the trading agreement.

The following rule allows customer to proceed only if he or she accepted the trading agreement by ticking the checkbox off. The rule checks the customerAgreed HTTP request parameter.

deny( //priv/POST, //app/policy/mybank/bankapp/url/mybroker/openAccount.jsp, //role/Client) if Not customerAgreed="true"

JDBC Resources

Table 4-12 shows the mapping of the resource path elements for a JDBC resource:

Table 4-12 JDBC Resource Path Elements
Element Name	Value
application name	The application name or `shared` if the resource is global
resource type	`jdbc`
resource parent	the module name (if any) + the resource type (`ConnectionPool` or `MultiPool`)
resource name	The resource name

JDBC Resource Path Example

Listing 4-3 shows the configuration of a JDBC resource.

Listing 4-3 JDBC Resource Configuration

<JDBCConnectionPool DriverName="oracle.jdbc.driver.OracleDriver"
                    Name="MyJDBCConnectionPool"
                    PasswordEncrypted="{3DES}B2Bl+tp70Eh3D1pT53/anw=="
                    Properties="user=wles" Targets="myserver"
                     TestTableName="SQL SELECT 1 FROM DUAL"
                     URL="jdbc:oracle:thin:@localhost:1521:ASI"/>
  <JDBCTxDataSource JNDIName="MyDataSource"
                    Name="MyJDBCDataSourceName"
                    PoolName="MyJDBCConnectionPool"
                     Targets="myserver"/>

Because the resource is global and does not belong to any particular module, the fully qualified resource name is:

//app/policy/AppParentNode/shared/jdbc/ConnectionPool/MyJDBCConnectionPool

where ConnectionPool is the resource type and MyJDBCConnectionPool is the resource name.

JDBC Resource Privilege Mappings

The privilege name of a JDBC resource is mapped to a JDBC operation name and can take one of the following values:

admin

Privilege to perform the admin operations such as clearStatementCache, suspend, forceSuspend, resume, shutdown, forceShutdown, start, getProperties, and poolExists.

reserve

Privilege to reserve a connection in the data source by looking up the data source and then calling getConnection.

shrink

Privilege to shrink the number of connections in the data source.

reset

Privilege to reset the data source connections by shutting down and re-establishing all physical database connections.

JDBC Resource Path Example

Listing 4-4 gives an example of code that uses the JDBC resource we defined earlier.

Listing 4-4 JDBC Resource Code Example

javax.naming.InitialContext initialContext = new javax.naming.InitialContext();

javax.sql.DataSource ds = (javax.sql.DataSource) initialContext.lookup("MyDataSource");

java.sql.Connection conn = ds.getConnection();

PreparedStatement statement = 
conn.prepareStatement("SELECT accountName FROM accounts WHERE balance < 0");

ResultSet result = statement.executeQuery();

if (result.next()) {
    String accountName = result.getString(1);
    System.out.println("The first account with negative balance is " + accountName);

In the example, the code calls the getConnection() method on the data source instance. This initiates an authorization check to verify the reserve privilege against the //app/policy/AppParentNode/shared/jdbc/ConnectionPool/MyJDBCConnectionPool resource.

JDBC Dynamic Resource Attributes

The following dynamic attributes are supported by JDBC resources and can be used as a part of an authorization policy:

application

The name of an application that hosts the resource.

module

The name of a module the resource belongs to.

resource

The name of the resource.

action

The JDBC operation name (admin | reserve | shrink | reset).

JDBC Resource Policy Examples

The following policy grants the role ExternalApplication a privilege to reserve (open) a JDBC connection from a connection pool called ExternalDataPool:

grant(//priv/reserve, //app/policy/mybank/shared/jdbc/ConnectionPool/ExternalDataPool, //role/ExternalApplication) if true;

The following policy grants the role Admin the admin privilege that will allow him or her to shut down any JDBC resources except a resource named SystemJdbcPool. Note that the //app/policy/mybank/shared/jdbc resource must be a virtual one.

grant(//priv/admin, //app/policy/mybank/shared/jdbc, //role/Admin) if Not resource="SystemJdbcPool";

JMS Resources

Table 4-13 shows the mapping of the resource path elements for a JMS resource:

Table 4-13 JMS Resource Path Elements
Element Name	Value
application name	The application name or `shared` if the resource is global
resource type	`jms`
resource parent	The destination type (topic or queue)
resource name	The resource name

JMS Resource Path Example

Listing 4-5 gives an example of how a JMS queue named MyJMSQueue might be configured.

Listing 4-5 JMS Resource Configuration Example

<JMSServer Name="WSStoreForwardInternalJMSServermyserver"
           Store="FileStore" Targets="myserver">
  <JMSQueue CreationTime="1150241964468"
          JNDIName="JMSQueue" Name="MyJMSQueue"/>
</JMSServer>

<JMSConnectionFactory JNDIName="JmsConnectionFactory"
                       Name="MyJMSConnectionFactory" Targets="myserver"/>

To insure the client can use the JMS queue named MyJMSQueue, it should be granted rights to access resource //app/policy/AppParentNode/shared/jms/queue/MyJMSQueue.

JMS Resource Privilege Mappings

The privilege name of a JMS resource is mapped to the JMS operation name. It can have one of the following values:

send

Required to send a message to a queue or a topic. This includes calls to the MessageProducer.send(), QueueSender.send(), and TopicPublisher.publish() methods.

receive

Required to create a consumer on a queue or a topic. This includes calls to the Session.createConsumer(), Session.createDurableSubscriber(), QueueSession.createReceiver(), TopicSession.createSubscriber(), TopicSession.createDurableSubscriber(), Connection.createConnectionConsumer(), Connection.createDurableConnectionConsumer(), QueueConnection.createConnectionConsumer(), TopicConnection.createConnectionConsumer(), and TopicConnection.createDurableConnectionConsumer() methods.

browse

Required to view the messages on a queue using the QueueBrowser interface.

JMS Resource Example

Listing 4-6 gives an example of a JMS client that uses the JMS queue declared above.

Listing 4-6 JMS Client Example

//Instantiate the inital context
javax.naming.InitialContext initialContext = new javax.naming.InitialContext();

//Look up the JMS connection factory and the message queue
Queue messageQueue = (Queue) initialContext.lookup("JMSQueue");
JMSConnectionFactory factory =
    (JMSConnectionFactory) initialContext.lookup("JmsConnectionFactory");

//Create the queue connection and session
QueueConnection queueConnection = factory.createQueueConnection();
QueueSession session =
    queueConnection.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);

//Create a text message
TextMessage textMessage = session.createTextMessage();
textMessage.setText("Hello from the client!");

//Send message to the queue
QueueSender sender = session.createSender(messageQueue);
sender.send(textMessage);

In the example, the client sends a text message to MyJMSQueue. This requires the send privilege for resource //app/policy/AppParentNode/shared/jms/queue/MyJMSQueue to successfully execute the code.

JMS Dynamic Resource Attributes

The following dynamic attributes are supported by JMS resources and can be used as a part of an authorization policy:

application

The name of an application that hosts the resource.

destinationtype

The JMS destination type (queue | topic).

resource

The name of the resource.

action

The JDBC operation name (send | receive | browse).

JMS Resource Policy Examples

The following policy grants the role Client a privilege to send messages to a JMS queue named FeedbackQueue:

grant(//priv/send, //app/policy/mybank/shared/jms/queue/FeedbackQueue, //role/Client) if true;

The following policy grants the user FeedbackProcessor a privilege to receive messages from a JMS queue named FeedbackQueue:

grant(//priv/receive, //app/policy/mybank/shared/jms/queue/FeedbackQueue, //user/myusers/FeedbackProcessor);

Web Services Resources

Table 4-14 shows the mapping of the resource path elements for a Web Services resource:

Table 4-14 Web Services Resource Path Elements
Element Name	Value
application name	The name of the application that contains the resource
resource type	`webservices`
resource parent	The application context
resource name	The Web Service name

Web Services Resource Path Example

Listing 4-7 shows the configuration of a web application named BasicWS that contains a Web Service implementation named BasicWS_Component.

Listing 4-7 Web Application Configuration Example

<application Name="BasicWS"
             Path="applications/BasicWS.ear"
             StagedTargets="myserver"
  <WebServiceComponent Name="BasicWS_Component"
                        Targets="myserver"

URI="BasicWS.war"/>

</application>

Listing 4-8 shows how the application.xml file from the BasicWS.ear enterprise archive defines the web application context:

Listing 4-8 Web App Context Example

<module>
  <web>
    <web-uri>basic_javaclass.war</web-uri>
    <context-root>myservices</context-root>
  </web>
</module>

Listing 4-9 shows the configuration of a Web Service named HelloWorld, which is defined in the descriptor web-services.xml inside the WAR file.

Listing 4-9 Web Service Example

<web-services>
  <web-service useSOAP12="false"
               name="HelloWorld"
               style="rpc"
               uri="/HelloWorld">
    <operations>
        <operation name="sayHello"
                   method="sayHello(int,java.lang.String)"/>
    </operations>
  </web-service>
</web-services>

The fully qualified name of this Web Service resource is:

//app/policy/AppParentNode/BasicWS/webservices/myservices/HelloWorld

Web Services Resource Privilege Mappings

The privilege for accessing a Web Service is mapped to the name of the Web Service operation.

Web Services Resource Policy Examples

To call the operation sayHello in the HelloWorld service defined in this section, the client must be granted the privilege sayHello. Note that some of the clients may require access to the WSDL file, which is actually a URL resource. Consider the following client code:

String wsdlUrl = "http://localhost:7001//HelloWorld?WSDL";
HelloWorld service = new HelloWorld_Impl(wsdlUrl);   
HelloWorldPort port = service.getHelloWorldPort();
String result = port.sayHello(34, "Josh");

Before calling method sayHello, the client accesses the WSDL file. To make the code run successfully, the client must be granted the privilege GET on the resource //app/policy/AppParentNode/BasicWS/url/myservices/helloworld in addition to the Web Service resource. Thus, the following policies must be created:

grant(//priv/GET, //app/policy/AppParentNode/BasicWS/url/myservices/helloworld, //role/SomeUser) if true;

grant(//priv/sayHello, //app/policy/AppParentNode/BasicWS/webservices/myservices/HelloWorld, //role/SomeUser) if true;

Note that for the URL Resource, the resource name was changed to lower case.

Web Services Dynamic Resource Attributes

The following dynamic attributes are supported by Web Services resources and can be used as a part of an authorization policy:

application

The name of the application

contextpath

The context part of the web application

webservice

The name of the web service

method

The name of the web service operation called

Param<N>

A value of the Nth parameter in the method, for example,. Param1, Param2...

Web Services Resource Policy Examples

The following policy grants the role Client a privilege to call the operation getDelayedQuote on a Web Service named StockQuoteService:

grant(//priv/getDelayedQuote, //app/policy/mybank/myservices/webservices/publishedservices/StockQuoteService, //role/Client) if true;

The following policy grants the role Client a privilege to call the operation getRealtimeQuote on a Web Service named StockQuoteService, but only if he or she has a premium subscription type:

grant(//priv/getRealtimeQuote, //app/policy/mybank/myservices/webservices/publishedservices/StockQuoteService, //role/Client) if subscriptionType="premium";

Server Resources

A Server resource determines who can control the state of a WebLogic Server instance. When users start server instances by invoking the weblogic.Server class in a Java command, the policy on the Server resource is the only security check that occurs. You can create security policies that apply to all WebLogic Server instances in a domain or to individual servers.

The following table shows the mapping of the resource path elements for a Server resource:

Table 4-15 Server Resource Path Elements
Element Name	Value
application name	`shared`
resource type	`svr`
resource parent	Not used
resource name	The server instance name

Server Resource Path Example

Listing 4-10 gives an example of the configuration of a WebLogic Server instance named myserver.

Listing 4-10 WebLogic Server Instance Configuration

<Server ListenAddress=""
        ListenPort="7001"
        Machine="mymachine"
        Name="myserver"
        NativeIOEnabled="true"
        ReliableDeliveryPolicy="RMDefaultPolicy"
        ServerVersion="8.1.5.0">
    <SSL Enabled="false" HostnameVerificationIgnored="false"
        IdentityAndTrustLocations="KeyStores" Name="myserver"/>
</Server>

The fully qualified name of the resource that corresponds to the server instance is //app/policy/AppParentNode/shared/svr/myserver.

Server Resource Privileges Mapping

The privilege name of a Server resource is mapped to the operation name. It can have one of the following values:

boot

Privilege required to start a WebLogic Server instance, either an Administration Server or Managed Server.

shutdown

Privilege required to shut down a running WebLogic Server instance, either an Administration Server or Managed Server.

suspend

Privilege required to prohibit additional logins (logins other than for privileged administrative actions) to a running WebLogic Server instance, either an Administration Server or Managed Server.

resume

Privilege required to re-enable non-privileged logins to a running WebLogic Server instance, either an Administration Server or Managed Server.

Server Dynamic Resource Attributes

The following dynamic attributes are supported by Server resources and can be used as a part of an authorization policy:

server

the name of the server the resource is associated with.

action

the name of an operation performed on the server instance (boot | shutdown | suspend | resume).

Server Resource Policy Examples

The following policy grants the role Admin a privilege to boot all WebLogic Server instances. Note that the resource //app/policy/mybank/shared/svr must be a virtual one.

grant(//priv/boot, //app/policy/mybank/shared/svr, //role/Admin) if true;

The following policy grants the role Admin a privilege to shutdown or suspend a WebLogic Server instance named CentralServer but only on Sundays or other days between 2 a.m. and 4 a.m.:

grant[//priv/shutdown,//priv/suspend], //app/policy/mybank/shared/svr/CentralServer, //role/Admin) if timeofday in [2:0:0..4:0:0] Or dayofweek=Sunday;

Subject Mapping

All authorization policies in ALES are applied considering a subject that accesses a resource. A subject representation uses the standard javax.security.auth.Subject class that contains a set of java.security.Principal objects. The subject consists of a directory name, a user name, and a set of group names. The user and groups are considered to exist within the specified directory. The directory name is a part of configuration of the authentication and role-mapping providers, and can be modified using the ALES Administration Console.

The providers iterate the principals, selecting those that implement the weblogic.security.spi.WLSUser and weblogic.security.spi.WLSGroup interfaces. The first WLSUser principal is used to retrieve the user name. All of the WLSGroup principals are used to build of the group names.

Note that running an application under the ALES framework does not require any changes on the client or server side in terms of credential handling. The actual methods of supplying credentials depend on the resource type. For example, to access a URL resource, the user can supply its credentials in the browser's prompt dialog or, if the client is Java code, it can send the credentials as the HTTP Authorization header of the request. Listing 4-11 shows an example how the credentials can be supplied using standard methods before accessing enterprise resources:

Listing 4-11 Supplying Credentials

Hashtable properties = new Hashtable();
properties.put(InitialContext.PROVIDER_URL, "t3://localhost:7001");
properties.put(InitialContext.SECURITY_PRINCIPAL, "username");
properties.put(InitialContext.SECURITY_CREDENTIALS, "password");
properties.put(InitialContext.INITIAL_CONTEXT_FACTORY,
    "weblogic.jndi.WLInitialContextFactory");
javax.naming.InitialContext initialContext =
    new javax.naming.InitialContext(properties);

//Look up and access the resources here...

Policy Element Naming

The policy language uses standard naming conventions called qualifiers to refer to privileges, applications, resources, roles, and identity elements (directories, users and groups). These conventions ensure that each component has a unique name, even if you use the same name in other locations. The Administration Console hides these qualifiers from you during most operations. See Fully Qualified Names for additional information on naming conventions.

The following rules apply to policy element names:

Most names are case sensitive. Declarations and attribute names are the exception; they are case insensitive. Internally, when a declaration name or attribute name is saved, it is saved in all lowercase. For example, the user names //user/ales/system/ and //user/ales/System/ reflect the same user.
A qualified name is a name with qualifier prefix prepended to the non-qualified name. Some names, like user and group names, have an ending suffix also. See Table 4-16 for examples. Declaration names do not have a qualified form.
The characters used for the names and the length of the names are restricted. See Size Restriction on Policy Data.

Table 4-16 Examples of Qualified Names
Policy Element	Example
resource	`//app/policy/banking/transfer`
directory	`//dir/extranet`
privilege	`//priv/place_order`
privilege group	`//grp/trading_privileges`
user	`//user/extranet/JohnDoe/`
group	`//sgrp/extranet/trader/`
role	`//role/roleName`
logical name	`//ln/ShortHandForResource`

For more information on policy element naming, see the following topics:

Fully Qualified Names

A fully qualified name references the full name for a policy element. This name consists of a series of simple names separated by forward slashes (/). Fully qualified names have the following parts, in order:

A starting double forward slash: //
A qualifier followed by a forward slash
For users and groups, a directory name followed by a slash mark, and a final slash after the name
A name:

For example, in //user/Accounting/JJBob/

user is the qualifier
Accounting is the directory
JJBob is the user name

For resources, the qualified name starts with //app/policy/. Additional names may appear, each separated by a single slash. This naming convention defines the resource tree. Each resource name is represented as a node on the tree, but the entire string represents the fully qualified name of the final resource. For example:

//app/policy/trading_system/PersonalTrades/BondOrder/Order

Policy Element Qualifiers

Qualifiers are built in. You cannot create your own qualifier or change the existing ones. They represent one of the basic policy elements and always begin with a double slash (//) followed by a single slash (/). Table 4-17 lists the built-in qualifiers.

Table 4-17 Policy Element Qualifiers
Qualifier	Policy Element
`//priv`	privilege
`//grp`	privilege group
`//user`	user
`//sgrp`	group
`//app`	resource
`//dir`	directory
`//bind`	engine
`//role`	role
`//ln`	logical name

There is no qualifier for a declaration. Declarations are identified by a different method. For a discussion of declarations, see Declaration Names.

Size Restriction on Policy Data

There are some limits on the size of names, attribute values, and rules, restricted by the type of database that you use. The restriction by the database is determined by the VARCHAR column size and the key size allowed by the database. Table 4-18 summarizes the limit for different policy data and different databases.

Table 4-18 Database Restrictions on Policy Data
Policy Data	Oracle	Sybase 12.5 2K¹	Sybase 12.5 4K	Sybase 12.5 8K	Sybase 12.5 16K
Qualified privilege name Qualified privilege group name Qualified role name Qualified resource name Qualified user name Qualified subject group name Qualified logical name Qualified security provider name	2000	580	1200	2500	5000
All privileges in the privilege field of a rule All roles in the privilege field of a rule All resources in the object field of a rule All user and group in subject field of a rule All roles in subject field of a rule	2000	580	1200	2500	5000
Rule conditions	4000	1160	2400	5000	10000
Rule text-combined text of all fields in a rule (privilege, object, subject, delegator, and conditions, plus the syntax delimiters)	N/A²	1962	4010	8106	16298
Declaration name Attribute name The individual declaration name inside a type declaration	2000	580	1200	2500	4000
Declaration text-the combined text of declaration name, kind, and value, plus the syntax delimiters	4000	1160	2400	5000	10000
A single attribute value	2000	580	1200	2500	4000
A quoted literal string in the declaration value	4000	1160	2400	4000	4000
A quoted literal string in a constraint for a rule	4000	1160	2400	4000	4000
A qualified name in the declaration value	2000	580	1200	2500	4000
A qualified name in a constraint for a rule	2000	580	1200	2500	4000
Integer value of a constant declaration	9 digits*³	9 digits*	9 digits*	9 digits*	9 digits*
All attribute values combined for a user, group or resource attribute	40000	40000	40000	40000	40000

¹Sybase 12.5 has a dependency on the logical page size that you choose when you set up the database server. The supported logical page size varies from 2K, 4K, 8K, and 16K.

²N/A means that there is no limit.

³An asterisk (*) indicates that the limit is imposed.

Character Restrictions in Policy Data

There are several restrictions on the character set that you can use to define policy data. The following common rules apply and Table 4-19 describes the extended character set restrictions.

Because AquaLogic Enterprise Security does not support internationalization, the character set used in policy data is ISO 8859-1 (Latin-1), Western European eight-bit character set.
All names without qualifier or called non-qualified names allow alphanumeric characters (a-z, A-Z, and 0-9) and the underscore (_). These names include privilege name, privilege group name, role name, resource name, user name, subject group name, directory name, logical name, security provider name, declaration, and attribute name.
All names, except user and subject group name, must start with an alpha character or underscore. Numeric characters are not allowed.

Table 4-19 Policy Data Character Restrictions
Policy data	Extra characters allowed
Resource name	Pound sign (#), apostrophe (`), dash (-), period (.), colon (:), at (@), tilde (~), ampersand (&).
User name or Subject group name	The name can include any other printable characters, such as space, period, and dollar sign, etc. A forward slash (/) in the name must be escaped by a backward slash (\), because a forward slash (/) is used as field separator.
String typed attribute value	All printable characters are allowed.
Literal string in the value of a constant declaration	All printable characters are allowed except the double quote (") and a backslash (\). When used, these characters may cause parsing problems.
Literal string in a condition for a rule	All printable characters are allowed except the double quote (").

The following topics provide more information:

Data Normalization

When using the ASI Authorization or ASI Role Mapping providers, there are certain data transformations that you must consider. The policy database limits what characters are allowed in certain policy elements. This set is more restrictive than the set allowed by the Security Framework.

The ASI Authorization and ASI Role Mapping providers perform normalization of input data to ensure that they abide by the restrictions imposed by the authorization management system. The management system does not currently perform any automatic normalization, so it is important to understand the normalization mechanism because it must be preformed manually when writing policy. Unless otherwise stated, the substitutions listed Table 4-20 apply to the following elements: resource, attribute, privilege, role, and directory names.

Additionally, any nonprintable character is translated into the numeric hexadecimal equivalent; for example, the ASCII character code 1 (a smiley face) is represented as __0x1_. Table 4-20 shows the characters that are normalized and the character substitution applied at runtime. When writing policy, you must substitute these characters.

Table 4-20 Character Substitution
Character	Character Substitution
\n	(carriage return) __CR_ also applies to user and group names
0	__0_ 1st character only
1	__1_ 1st character only
2	__2_ 1st character only
3	__3_ 1st character only
4	__4_ 1st character only
5	__5_ 1st character only
6	__6_ 1st character only
7	__7_ 1st character only
8	__8_ 1st character only
9	__9_ 1st character only
\t	(tab) __TAB_
` `	(space) __SP_
!	__EXPL_
"	__DQUOT_
#	__HASH_ 1st character of resource, or any character in attr, priv, role, dir
.	__PRD_ 1st character of resource, or any character in attr, priv, role, dir
%	__PRCT_
(	__OPRN_
)	__CPRN_
*	__ASTR_
+	__PLUS_
,	__COMMA_
/	__FSLSH_
;	__SCLN_
<	__LT_
=	__EQ_
>	__GT_
?	__QTM_
[	__OSQB_
\	__BSLSH_
]	__CSQB_
`	__CSQUOT_
{	__OCRL_
\|	__PIPE_
}	__CCRL_
&	__AMP_ Applies only to attr, priv, role, dir
-	__DASH_ Applies only to attr, priv, role, dir
:	__CLN_ Applies only to attr, priv, role, dir
@	__AT_ Applies only to attr, priv, role, dir
~	__TLD_ Applies only to attr, priv, role, dir

Directory Names

A directory further separates qualifiers. You define directories to store and scope users and groups. For example, if you had an application called Bankers, the directory that stores users and groups might look like this:

//dir/Bankers

Once declared, the directory is used with the user and group qualifier to fully qualify subjects. For example, //sgrp/Bankers/loans/ is a group called loans that belongs to the Bankers group and //user/Bankers/BSilva/ is a user named BSilva that belongs to the Bankers application.

Note:

A directory name must start with a letter and can contain any number of alphanumeric or underscore characters. Directory names are case sensitive.

A directory name does not necessarily need to represent a resource. For example, a directory name might represent users in a particular location (as in //dir/NewYork) or a department (as in //dir/Accounting). Essentially, you can use them any way you want to delineate groups of users and groups.

A privilege group is not part of the policy language but is provided for administrative convenience. Each privilege in a group is defined as an individual privilege in the actual policy.

Logical Name

A logical name is a shorthand method used to represent a resource. Once you map a logical name to a fully qualified name, your developers can use the logical name when coding your application.

//ln/name

Declaration Names

A declaration name is not qualified. In fact, that is exactly how they are identified. Any policy element without a fully qualified name and not in quotation marks (indicating a string), is assumed to be a declaration. When defined, declarations are preceded by one of the following identifiers:

const - Constant Declaration

type - Type Declaration

cred - Credential (or Attribute) Declaration

eval - Evaluation Function Declaration

Special Names and Abbreviations

There are several special names, referred to as keywords, that are shortcuts for denoting groups of objects. The keywords keep you from having multiple rules or multiple rule queries in certain reoccurring situations. By using these keywords, you can define very powerful, yet generic rules. The keywords are as follows:

any—Signifies any privilege. When specifying any in a rule, it means you do not care what privilege a user invokes when applying the rule.
ALL—Signifies a privilege group containing all privileges. You must use the grp qualifier with the keyword ALL (//grp/ALL). The keyword ALL is mainly used for grouping purpose in the console and, by default, every privilege defined belongs to the privilege group ALL.
allusers—For each user directory, there is an implied group called allusers. This group refers to all users in a directory. For example:

//group/Acct/allusers

This example refers to allusers for the Acct directory and eliminates the need to individually address each user or to create a named group for all of the users.

Note: The keyword allusers is only a limited pseudo group. It does not have many of the qualities of a regular group; you cannot map it to anything, you cannot add or remove members, and it cannot be a member of group hierarchy. You can delegate to allusers groups.

Table 4-21 describes the rules for using keywords.

Table 4-21 Rules for Using Keywords
Characteristic	any	ALL	allusers
Policy Element	Built-in privilege	Built-in privilege group	Built-in local group
Represents	any privilege	All privileges including built-in and user-defined	All users in one local directory
Used in rules	Yes	No	Yes
Needs qualifier	No	Yes `//grp/ALL`	Yes `//sgrp/ [directory name]/allusers`
Used in policy queries	Yes Only finds rules with the literal any. That is, it does not return all rules (rules with any privilege).	No	Yes Finds rules that specifically entitle the group allusers
Controlled by delegation	No Must be in a group that is delegated	Yes Controls access to all privileges regardless of privilege group	Yes You must be specifically delegated access to this group
Case-sensitive	Yes	Yes	Yes

Sample Policy Files

A policy file is a text file that lists the relevant policy elements using their fully qualified names. The ALES Administration Server installation includes sets of sample policies for BEA WebLogic Portal, BEA AquaLogic Data Services Platform, and BEA AquaLogic Service Bus. You can import these sample policies and use them as a starting point for developing a full set of policies for your applications. For information about how to import the sample policies, see the README files in each of the sample directories and see also Importing Policy Data. Table 4-22 shows the location of the samples.

Table 4-22 Sample Policy Files
BEA Product	Sample Policy Directory
WebLogic Portal	`BEA_HOME/ales22-admin/examples/policy/portal_sample_policy`
AquaLogic Data Services Platform	`BEA_HOME/ales22-admin/examples/policy/aldsp_sample_policy`
AquaLogic Service Bus	`BEA_HOME/ales22-admin/examples/policy/alsb_sample_policy`

In addition, this section provides examples of policy files. Sample files for each policy element are provided with the product and are installed in the following directory:

BEA_HOME\ales22-admin\examples\policy

For a description of each of these files, see the following topics. The policy data filenames are shown in brackets ("[]").

Application Bindings [binding]

This file contains an example of the Authorization provider and Service Control Manager bindings. The resources that can be bound are the resources that are created as binding nodes.

Each line contains a name of an Authorization provider or Service Control Manager, followed by a binding node name. A Security Provider can only bind policy resources and the Service Control Manager can only bind configuration resources.

Examples:

//bind/myAuthorizationProvider  //app/policy/myApplication/myBinding

//bind/mySCM //app/config/myConfiguration/configBind

Attribute [attr]

This file lists the subject attribute for users and subject group. The attribute value property must comply with user attribute schema defined for //dir/dirName. If the property is "L", the attribute value must be enclosed in brackets ([]), with items separated by commas. In general, the attribute value for all users must be set according to the specification defined in user attribute schema. However, if an attribute is not set when this file is created, its record may be left out in this file.

Note:

Both user and credential declarations must exist in the policy database before it can be loaded successfully. Further, the user attribute schema must be defined before the user attribute can be assigned in Attribute Value file.

Examples:

Given the user attribute schema shown in Listing 4-12, the user attribute values and subject attribute value are defined as shown in Listing 4-13 and Listing 4-14.

Listing 4-12 User Attribute Schema

//dir/CA_Office my_host_ip S

//dir/CA_Office my_favorite_color L [blue,green]

//dir/NY_Office email_address S "user@crosslogix.com"

//dir/NY_Office my_birthday   S

//dir/NY_Office my_favorite_color L [red]

Listing 4-13 Sample User Attributes

//user/CA_Office/user_a@mycom.com/ my_host_ip 121.1.100.25
//user/CA_Office/user_b@mycom.com/ my_host_ip 121.1.100.26
//user/CA_Office/user_c@mycom.com/ my_host_ip 121.1.100.50
//user/CA_Office/user_d@mycom.com/ my_host_ip 121.1.100.225
//user/CA_Office/user_e@mycom.com/ my_host_ip 132.99.25.77

//user/CA_Office/user_a@mycom.com/ my_favorite_color [red]
//user/CA_Office/user_b@mycom.com/ my_favorite_color [white,green]
//user/CA_Office/user_c@mycom.com/ my_favorite_color [red,blue]

//user/NY_Office/user_1/ email_address     "user1@crosslogix.com"
//user/NY_Office/user_1/ my_birthday       1/1/1960
//user/NY_Office/user_1/ my_favorite_color [blue]

Listing 4-14 Sample Subject Group Attribute

//sgrp/NY_Office/role1/ my_favorite_color [green]

Declarations [dec]

AquaLogic Enterprise Security supports four kinds of declarations that are used in rules, user attributes, and resource attributes. You must create the declaration before you use it in a rule. The kinds of declarations are: enumerated types (ENUM), constants (CONST), attributes (CRED), and evaluation functions (EVAL). You can use this file to declare each one. Each line contains the declaration text, starting with declaration type. Declaration names are case-insensitive and are always saved in lower case. The four kinds of declaration text must conform with the following syntax.

ENUM enum_name = (enum1, enum2, ..., enumn);

CONST constant_name_1 = constValue;

CONST constant_name_2 = [value1, value2, ..., valuen];CRED cred_name : datatype;

EVAL eval_name;

Examples:

ENUM color_type = (red, blue, green, white);

CONST my_favorite_color = green;

CONST my_birth_date = 07/04/1980;

CONST favorite_colors_for_tom = [blue, white];

CONST colors_of_my_choice = [my_favorite_color, red];

CONST a_few_cities = ["New York", "Boston", "San Francisco"];

CONST a_magic_number = 28;

CRED string_cred_1 : string;

CRED color_cred : color_type;

CRED date_cred : date;

CRED weight_in_pound : integer;

EVAL is_good_number;

Directories [dir]

Multiple directories can be used to separate users and groups that come from different user stores. A directory is also associated with a schema and the types of attributes the users in that directory contains.

This file lists the name of some sample directories. The directory name must start with the prefix:

//dir/

Examples:

//dir/CompanyA

//dir/CompanyB

Directory Attribute Schemas [schema]

A directory defines all users and user groups. Before a user or a user group can be assigned an attribute, you must declare the directory to accept their attributes. You can use this file to declare the attributes that a directory can have.

Each line in the file contains a directory name, an attribute name (the attribute declaration as in file "decl"), a value type (single- or multi-value), and an optional template value matching the data type of the attribute. The single-value type is denoted by S and multi-value type by L (from list-value).

You must enter a multi-value (list) attribute with all values enclosed in square brackets [] and separated by commas, and enclose each value for a string data typed attribute with double quotes ("). You cannot use another double quote (") and backslash (\) in the template value.

Examples:

//dir/CompanyA my_host_ip S 111.111.111.111

//dir/CompanyA my_favorite_color S

//dir/CompanyA email_address L ["user@bea.com", "xyz@yahoo.com"]

//dir/CompanyB my_birthday   S

//dir/CompanyB my_favorite_color L [blue,green]

list of exclusive sgrp pair.

Mutually Exclusive Subject Groups [excl]

This file lists the subject groups that are mutually exclusive from one another. An exclusive subject groups record has the following format:

//sgrp/dirName/aSubjectGroupName/ //sgrp/dirName/anotherSubjectGroupName

For subject groups to be mutually exclusive, they must comply with the following requirements:

Both subject groups must be in the same directory.
The subject groups must not share a common sgrp member or user member.
Both subject groups in a pair must exist in the policy database before the pair can be defined and loaded successfully.

Example:

//sgrp/CA_Office/trader/ //sgrp/CA_Office/salesPerson/

Resources [object]

In general, resources are constructed as a tree below two tree roots: the policy resources tree and the configuration tree. The policy tree has a resource name that starts with the prefix //app/policy/ (for resource configuration) and configuration tree that starts with the prefix //app/config/ (for provider configuration). However, you do not see the provider configuration in the tree. This file lists all the resource names in order, from the root to the child nodes, together with the resource type and the logical name for the resource.

There is a special resource type, denoted by A, indicating that the resource node is bound by an ASI Authorization Provider or a Service Control Manager. This special resource node is called a binding node. All other resources are denoted by O and are called non-binding nodes.

A logical name or alias is a short name for a resource and can be optionally associated with a resource. Only binding nodes derived from the resource can have an alias. A logical name used as an alias must start with prefix:

//ln/

and must be unique to the entire resource tree. Each line contains a resource name, an optional resource type, and an optional alias. If the resource type is missing, it defaults to O. If there is an alias, the resource type must be specified.

Examples:

//app/policy/myApplication

//app/policy/myApplication/myBinding A

//app/policy/myApplication/myBinding/myresource.one O //ln/myres1

//app/policy/myApplication/myBinding/myresource.two O

//app/policy/myApplication/myBinding/myresource.three

//app/config/myConfiguration O

//app/config/myConfiguration/configBind A //ln/configBind

Resource Attributes [object]

Because a resource is also referred to as object, a resource attribute is also referred to as an object attribute. Each line contains a resource name (as in file "object"), an attribute name (the declaration as in file "decl"), a value type (single- or multi-value), and values matching the data type of the attribute. The single-value type is denoted by S and multi-value type is by L (from list-value). You can enter a multi-value attribute either in multiple lines, with the same resource name, attribute name and value type (L); or, you can enter it using one line, with all the values enclosed in square brackets [] and separated by commas. You must enclose each value for a string attribute with double quotes ("). You cannot use another double quote and backslash (\) in the attribute value.

Examples:

//app/policy/myApplication/myBinding  string_attr_1 S  "A value to be decided"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "1st Value"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "2nd Value"

//app/policy/myApplication/myBinding/myresource.one string_attr_1  L  "3rd Value"

//app/policy/myApplication/myBinding/myresource.two string_attr_1  L ["ABC", "DEF", "XYZ"]

//app/policy/myApplication/myBinding/myresource.three color_attr_1 L [red, blue]

//app/policy/myApplication/myBinding/myresource.three integer_attr_1 S  1001

//app/policy/myApplication/myBinding/myresource.three date_attr_1 L  [01/01/2003, 01/01/2004]

Policy Distribution [distribution]

This file provides the parameters used for policy distribution issued by the Policy Import tool when the distribution is enabled in a configuration. The policy distributor takes a list of user directories and distribution point combinations. Therefore, each line contains a directory and a distribution point separated by white spaces.

The distribution point is a resource node on or above a binding resource node. The directory can be either a specific directory or //dir/* to include all user directories.

Note:

You cannot use applications pending deletion as distribution points. Select a node higher in the tree as the distribution point.

Examples:

//dir/* //app/policy/myApplication

//dir/CompanyA //app/policy/myApplication/myBinding

Policy Inquiry [piquery]

AquaLogic Enterprise Security stores the contents of a policy inquiry in the policy database. This file contains examples of policy inquiries to import and store in the policy database. Each query can span multiple lines, can have multiple lines of each type, but must have a minimum of one line. The first line of each query must specify the privilege, the effect (grant or deny), the query owner and the query title.

Each line has the following syntax:

P/O/S oneQualifiedName grant/deny queryOwner queryTitleMayhaveSpace

where P/O/S stands for privilege, object (resource), and subject.

Listing 4-15 shows policy inquiry examples.

Listing 4-15 Policy Inquiry Examples

# Sample query 1:

P //priv/delete     grant //user/ales/system/ Saved Policy Inquiry #1
O //app/policy/myApplication/myBinding  grant //user/ales/system/
      Saved Policy Inquiry #1
S //ales/ales/userid/ grant //user/ales/system/ Saved Policy Inquiry #1

# Sample query 2 (same content as query 1):

P //priv/delete     grant //user/ales/system/ Policy Inquiry #2
O //app/policy/myApplication/myBinding 
S //ales/ales/userid/

# Sample query 3:

P //priv/delete   grant //user/ales/system/ Policy Inquiry #3

# Sample query 4:

P //priv/delete               deny //user/ales/system/ PIQuery4
P //priv/create 
O //app/policy/myApplication

Policy Verification [pvquery]

AquaLogic Enterprise Security stores the contents of a policy verification in the policy database. This file defines policy verification queries to import and store in the database. Each query spans multiple lines. The first line of each query must have the owner and title, in the following syntax:

LP/RO/RP/RO oneQualifiedName queryOwner queryname

A query name may contain spaces.

Listing 4-16 shows policy verification examples:

Listing 4-16 Policy Verification Examples

# Sample query 1:

LP //priv/delete //user/ales/system/ Policy Verification #1
LO //app/policy/myApp/firstResource //user/ales/system/ Policy Verification #1
RP //priv/create //user/ales/system/ Policy Verification #1
RO //app/policy/myApp/secondResource //user/ales/system/ Policy Verification #1

# Sample query 2 (query content is the same as query 1):

LP //priv/delete //user/ales/system/ Policy Verification #2
LO //app/policy/myApp/firstResource
RP //priv/create
RO //app/policy/myApp/secondResource

# Sample query 3:

LP * //user/ales/system/ Policy Verification #3
LO //app/policy/myApp/firstResource //user/ales/system/ Policy Verification #3
RP //priv/delete //user/ales/system/ Policy Verification #3
RO //app/policy/myApp/secondResource //user/ales/system/ Policy Verification #3

# Sample query 4:

LP * //user/ales/system/  PolicyVerification#4
LO //app/policy/myApp/firstResource //user/ales/system/  PolicyVerification#4
RP * //user/ales/system/  PolicyVerification#4
RO //app/policy/myApp/secondResource //user/ales/system/  PolicyVerification#4

Privileges [priv]

This file contains a sample list of privilege names. Each privilege name must start with the prefix:

//priv/

Examples:

//priv/read

//priv/Read

//priv/search_file

//priv/search_text

Privilege Bindings [privbinding]

This file contains examples of how privileges are bound to privilege groups. Each line contains a privilege group followed by a privilege.

Examples:

//grp/myPrivGroup //priv/read
//grp/myPrivGroup //priv/search_file
//grp/myPrivGroup //priv/search_text
//grp/DevelopmentGroup //priv/read
//grp/DevelopmentGroup //priv/Read

Privilege Groups [privgrp]

This file contains examples of privilege group names. Each privilege group name must start with the prefix:

//grp/

Examples:

//grp/myPrivGroup
//grp/DevelopmentGroup

Role [role]

This file defines a list of role names. Roles are used to construct policies. Each line contains a role name. Each role name is prefixed with:

//role/

Examples:

//role/manager
//role/QA
//role/trading_Manager
//role/salesEngineer
//role/junior_trader
//role/salesPerson
//role/trader

Rule [rule]

Rules are used by the Authorization and Role Mapping Engine (ARME) to make authorization and role mapping decisions. This file lists rules with their rule text conforming to rule syntax. Each line contains one rule, a grant, deny, or delegate rule. Sample entries assume all of the referenced roles, privileges, resources, users, groups and declarations exist in the policy database.

Examples:

grant(//role/Administrators, //app/policy/myApplication, //user/ales/system/);
grant(//priv/read, //app/policy/myApplication, //sgrp/ales/allusers/);
deny([//priv/read, //priv/search_text],
//app/policy/myApplication/myBinding/confidentialDocument.one, //role/public);
delegate(//role/Administrators, //app/policy/myApplication, //user/ales/John Doe/, //user/ales/system/) if dayofweek in weekend;

Distribution Targets

There are two types of distribution targets in BEA AquaLogic Enterprise Security:

The Authorization and Role Mapping providers that enforce policy
The Service Control Manager that manages configuration changes

Both of these targets retrieve their policy data from the policy distributor. The security providers receive only policy related changes and the Service Control Manager retrieves only configuration related changes. The file called engine lists the names of the security providers and the Service Control Manager and respective type.

The name is qualified by the prefix:

//bind/

The names are referred to by the application binding file (binding) and must be imported before the application binding file.

Examples:

//bind/myAuthorizationProvider ARME

//bind/mySCM SCM

Subject Group Membership [member]

This file lists subject group membership. Each record has one of the following formats:

//sgrp/dirName/aSubjectGroupName/ //sgrp/dirName/aSubjectGroupMemberName/

//sgrp/dirName/aSubjectGroupName/ //user/dirName/aUserMemberName/

When you define subject group memberships, the subject group and members must comply with the following requirements:

The subject group and the member must be in the same directory.
One user may belong to many subject groups.
One subject group may be a member of many subject groups.
Two subject groups that have common members cannot become mutually exclusive.
Both subject groups and their members must exist in the policy database before the membership can be loaded successfully.

For an example of a Member policy file, see Listing 4-17.

Listing 4-17 Sample Member Policy File

//sgrp/CA_Office/junior_trader/   //sgrp/CA_Office/trader/
//sgrp/CA_Office/trader/          //sgrp/CA_Office/senior trader/
//sgrp/CA_Office/senior trader/   //sgrp/CA_Office/trading_Manager/
//sgrp/CA_Office/salesEngineer/   //sgrp/CA_Office/salesManager/
//sgrp/CA_Office/salesPerson/     //sgrp/CA_Office/salesManager/

//sgrp/CA_Office/junior_trader/   //user/CA_Office/user_a@mycom.com/
//sgrp/CA_Office/senior trader/   //user/CA_Office/user_b@mycom.com/
//sgrp/CA_Office/trading_Manager/ //user/CA_Office/user_c@mycom.com/
//sgrp/CA_Office/salesPerson/     //user/CA_Office/user_d@mycom.com/
//sgrp/CA_Office/customer/        //user/CA_Office/user_e@mycom.com/

Subjects [subject]

This file contains a list of users and subject groups. Each record must have one of the following formats:

//user/dirName/aUserName/ //sgrp/dirName/aSubjectGroupName/

The directory name must be formatted as //dir/dirName and it must exist in the policy database before its subjects can be loaded successfully.

For an example of a Subjects policy file, see Listing 4-18.

Listing 4-18 Sample Subjects Policy File

//user/CA_Office/user_a@mycom.com/
//user/CA_Office/user_b@mycom.com/
//user/CA_Office/user_c@mycom.com/
//user/CA_Office/user_d@mycom.com/
//user/CA_Office/user_e@mycom.com/
//sgrp/CA_Office/junior_trader/
//sgrp/CA_Office/trader/
//sgrp/CA_Office/senior trader/
//sgrp/CA_Office/salesEngineer/
//sgrp/CA_Office/salesPerson/
//sgrp/CA_Office/salesManager/
//sgrp/CA_Office/trading_Manager/
//sgrp/CA_Office/customer/

//user/NY_Office/user_1/
//sgrp/NY_Office/sgrp1/

Using Response Attributes

Response attributes are defined as a list of the attributes you want to return from the authorization system when a request is made by an application. Response attributes provide a mechanism for allowing the authorization system to pass arbitrary information back through the Security Framework to the caller. The use of this information is typically application specific. Some examples of how you can use response attributes include:

Personalization—The decision as to what resources to display on a portal may be tied closely to the security policy. Suppose that when a user enters the portal, the portal displays a list of accounts and menu options denoting operations on the accounts. If a user attempts to access a particular item and the attempt is rejected for security reasons, the portal has limited effectiveness. That is, the portal may serve as an information source used for future attacks. By tying the security policy directly to the portal, only the resources that the user is allowed to access are displayed.
Business process flow —Business processes often have inter-task dependencies. For example, suppose that a senior trader has the ability to override the rejection of a trade placed by a junior trader. To make this decision, the senior trader would have to take into account the reasons why the proposed trade violates the security policy, which could be the trade amount, the risk profile, or any of several other reasons. By enhancing the authorization decision with that context, subsequent authorization decisions based on that context can be enabled.
Transaction specific data—An application may need specific facts about authorized or rejected transactions. For example, the application may want to display the post-trade balance for an executed transaction, information that typically would be calculated as part of the authorization process but not returned as part of the authorization decision.

Response attributes are typically specified using built-in evaluation functions that report name/value pairs. There are two functions for returning attributes: report() and report_as(). These functions always return TRUE (if there are no errors), and their information is passed to your application as response attributes, embedded within the ResponseContextCollector.

You use report() and report_as() in the policy after an IF statement used in a constraint. It is best to use them in a logical if this policy is evaluated, then manner, even though "then" does not exist in the language.

For example:

if (constraint) and report_as (name,value);

While the functions are run when the policy is evaluated, they are not really constraints of the policy. Data reported by the functions are returned only if the adjudicated authorization decision agrees with the policy. This means the attributes returned from GRANT policies are not passed to the caller unless the overall access decision is PERMIT.

The following topics provide more information on using response attributes:

report() Function

The report function takes one or more attributes as input parameters and sets a corresponding response attribute with the name/value pair of the supplied attributes. For example, suppose you have the attribute called department, containing the value Accounting. If the following constraint was evaluated:

IF report(department);

the response attribute (department = accounting) is set in the response context results. Your client application can then use this information in many ways, for example:

As a parameter in a database query where it filters the query results by department
To personalize a portal page with an accounting department template
To update the record being modified with the department information

report_as() Function

The report_as function loads a named response attribute with a specified value. The value may be an attribute, a constant or a string literal. You can specify multiple values, in which case the response attribute is returned as a list.

IF report_as("error","Your account balance is too low");

IF report_as("query", "Select * from record_table where dept_type = ", department);

IF report_as("userlogin", trading_login,trading_password);

IF report_as("url","http://www.xyz.com/userinfo/xyz100383.htm");

Report Function Policy Language

The report function returns the name/value pair of the specified attribute. The value may be a one or more strings and is determined using the attribute retrieval mechanism of the authorization system. This means that the attribute can come from the following sources: system, user, resource or context.

The report_as function allows you to write the policy to specify both the attribute name and value:

report_as("company", "BEA Systems")

Additionally, you can specify a list of values, as follows:

report_as("accounts", "123", "456", "789")

The value portion of the report function supports de-referencing. Assume the user attribute favorite_color is part of a user profile. You can put the following statement into a policy:

report_as("window_background", favorite_color)

This allows you to set the response attribute window_background with the value of the favorite color that is stored in another attribute. You can use any of the supported language data types as values, but they are all returned to the provider using their string representation and no additional type data is transmitted.

Reporting the same attribute multiple times from the same policy results in only the last report clause date being used. For example:

grant (p,o,s) if report as ("car", "porche") and report_as ("car", "ford");

where: (p,o,s) is shorthand for privilege, object, and subject, results in the response attribute car = ford.

Using Evaluation Plug-ins to Specify Response Attributes

The ASI Authorization and ASI Role Mapping providers support the use of custom evaluation plug-ins to generate response attributes. The report and report_as functions are just special implementations of ASI Authorization and ASI Role Mapping provider plug-ins. Using custom evaluation functions, you can write even more complex statements. For example, the following policy retrieves the current stock price from an authoritative source.

grant(//priv/lookup, //app/policy/stockprice, //role/everyone)
if report_stock_price("BEAS");

A plug-in that implements this function must handle all of the logic required to obtain the actual stock price and then return it in a response attribute. Listing 4-19 shows an example of how to use a plug-in to implement this function.

Listing 4-19 Stock Price Function Implementation

TruthValue report_stock_price(Session &sess, const char *fname,
      char **argv) {
   const char* stock_symbol=argv[0];
   //lookup stock price using custom logic
   double price;
   bool found = lookup_stock_price(stock_symbol, &price);
   if(!found) {
         return TV_FALSE;//price not found
         }
   //change numeric value into a string
   char pricestr[1024];
   snprintf(pricestr,1023,"%f",price);
   //setup the return data
   sess.appendReturnData("stock_price",
                          new AttributeValue((const char*)pricestr));
   return TV_TRUE;
}

For additional information on using ASI Authorization and ASI Role Mapping provider plug-ins, see Provider Extensions in the Administration Reference Guide.

Using queryResources and grantedResources

This feature allows a caller to query the authorization system to determine access on a set of resources rather then a single resource. The ASI Authorization provider determines access to all child nodes of the node specified in the access query, and returns lists indicating which nodes are granted and which nodes are denied.

The client performs an isAccessAllowed query on the parentResource. This resource must be a binding node or a resource of a binding node.

The queryResources functionality evaluation is triggered by the presence of some qrvalue value in the com.bea.security.authorization.queryResources attribute of the ContextHandler. The access decision for the parentResource is returned, as normal. One of the return attributes for this decision is a com.bea.security.Authorization.grantedResources return attribute. One of the return attributes for this decision is a com.bea.security.Authorization.deniedResources return attribute.

For grantedResources, the value of this attribute is a list of values for the qrvalue resource attribute; or, if the qrvalue is an empty string, the value is the internal ARME name for the resource. This list is an intersection of all child nodes of parentResource and all resources for which the ASI Authorization provider and ASI Role Mapping provider and role policy evaluates to GRANT. If the qrvalue attribute is not defined on a particular child node, it is omitted to allow an application to deal with identification of the resource other than the internal ARME representation of it, which is not trivial to convert back to the framework resource.

This list can contain duplicate values. If the empty value for the qrvalue is used, the returned resource name is unique and defined for each child node.

The same applies for the deniedResources, except for the resources that the policy evaluates to DENY. For example, assume that an application makes an isAccessAllowed call on the //app/policy/Foo resource and sets the value of the queryResources attribute to object_id. The authorization policy has no policies set on the Foo resource, thus an ABSTAIN result is returned.

Now let's assume that Foo has child nodes Foo/A, Foo/B, Foo/C. The authorization policy allows access to Foo/A and Foo/C, given the role policy on Foo by all providers, and the role policy for A and C for a security provider. Assume that A and C have an object_id resource attribute equal to "rA" and "rC". Then, the above query returns an attribute grantedResources with the value ["rA", "rC"].

For role providers other than the ASI Role Mapper provider, roles granted on the parentResource are assumed to apply to all child nodes of the parentResource. For the role policy, it is evaluated as usual for all child nodes.

To receive the results, you must supply a ResponseContextCollector in the ContextHandler request.

When the application needs to call into the Security Framework to query resources it passes in:

AppContextElement qrElement = new SimpleContextElement( "com.bea.security.authorization.", "queryResources", "name"); appContext.addElement(qrElement);

When it retrieves the list of resources from the response, for granted resources, it must call:

AppContextElement granted = responseContext.getElement( "com.bea.security.Authorization.grantedResources");

or, for denied resources:

AppContextElement denied = responseContext.getElement( "com.bea.security.Authorization.deniedResources");

Note:

The case for authorization on the request and the response is not the same.

Resource Discovery

When developing policy for use with a Security Service Module, you can use the Discovery mode to help build your policy. Understanding how to write a policy requires that you understand the application you want to protect, the policy representations, and the mapping between the two.

Note:

You should never use Discovery mode in a production environment. Discovery mode is used in the development environment to create the bootstrap security policy.

A typical policy consists of the following elements:

Resources
Privileges
Roles
Attributes (user, group and resource)
Attributes, privileges, and resource associations
Rules to grant privileges on resources through roles
Rules to grant roles to users

The ASI Authorization and ASI Role Mapping providers support a Discovery mode that helps make this task easier. Typically, these providers answer questions about security, but when in Discovery mode, the providers record information about those questions to build your policy (for example, what privileges and resources must be granted to view a particular web page).

To use Discovery mode, you must modify the command line that starts your Security Service Module by adding the following system properties:

com.bea.security.providers.authorization.asi.AuthorizationProviderImpl.discoverymode=true

com.bea.security.providers.authorization.asi.RoleProviderImpl.discoverymode=true

You set the system properties using the -D command-line switch in the appropriate file, depending on which Security Service Module (SSM) you are targeting. Table 4-23 lists the files and their default locations for each type of SSM.

Table 4-23 Setting System Properties for Discovery Mode
Security Service Module Type	File Name	File Default Location
Apache	`set-env.sh` (UNIX only)	`BEA_HOME\ales22-ssm\apache-ssm\ instance\ <`instancename`>\bin`
IIS Web Server	`set-env.bat` (Windows only)	`BEA_HOME\ales22-ssm\iis-ssm\instance\ <`instancename`>\bin`
Java	`set-env.bat (.sh` for UNIX)	`BEA_HOME\ales22-ssm\java-ssm\instance\<`instancename`>\bin`
Web Services	`wlesws.wrapper.conf`	`BEA_HOME\ales22-ssm\webservice-ssm\ instance\<`instancename`>\config`
WebLogic Server 8.1	`set-wls-env.bat` (`.sh` for UNIX)	`BEA_HOME\ales22-ssm\wls-ssm\instance\ <`instancename`>\bin`

Note: The policy files are stored in the domain directory from which the startWeblogic.bat or startWeblogic.sh script is started and configured to run in Discovery mode.

A sample policy is recorded by the providers as you traverse an application. This is a learning process for the providers and they can only learn about the parts of the application that you use. If a portion of the application is not used, no information or policy about it is recorded. The generated policy is output to a set of files that you can import later, by using the Policy Import tool described in Importing Policy Data.

Among other things, the ASI Authorization and ASI Role Mapping providers transform their requests into a proprietary format. A request consists of the following four elements:

Subject
Resource
Action
Attributes

The ARME providers build this information based on data contained in the request to the provider. Each of these elements has different restrictions on the allowable character set. The providers automatically normalize any invalid characters to produce a valid entry. See Character Restrictions in Policy Data for further details.