|
|
This section provides the following topics:
A constraint is a statement added to a policy definition that limits when or under what circumstances permission is granted, denied or delegated. The primary tool for defining constraints is the Entitlements Administration Application.
The following constraint sets a purchase amount that must be satisfied in order for access to be granted:
purchaseAmount < 2000;
A number of out-of-box attribute types are provided (see Policy Extensions) and can be immediately used in constraint definitions. To use custom constraints, you must provide the code that processes the constraint logic.
Constraint definitions must be written as: <value> in [attribute] as shown in Table 4-1.
| Note: | In this section, the IF keyword is included in policy definitions. However, as of this release, do not include the IF keyword when defining constraints in the Entitlements Administration Application. |
If business logic requires the evaluation of multiple constraints, combine them into a complex constraint using an AND operator. In the following example, access is granted only if both constraints are true:
GRANT(//priv/any, //app/policy/MyApp, //sgrp/ORG/allusers/) IF purchaseAmount < 2000 AND month IN [december, january];For more information on combining multiple constraints, see Boolean Operations.
Constraints support the comparison operators listed in Table 4-2.
When using regular expressions with the LIKE and NOTLIKE operators, any character that is not a special character matches itself. The special characters are plus (+), asterisk (*), question mark (?), period (.), left bracket ([), right bracket (]), caret(^), and dollar sign ($).
The IN and NOTIN operators are used to test the memberships of sets in a constraint. For example, rather than writing:
. . . NextMonth = january or
. . . NextMonth = february or
. . . NextMonth = march;
. . . NextMonth IN [january, february, march] ;
You can also specify a range of values in constraint sets. The following statement is true if the age value is not between 1 and 100 (inclusive):
age NOTIN [1..100]
As shown in Table 4-4, use the LIKE and NOTLIKE keywords to test for specific text strings.
As shown in Table 4-5, the AND, OR, and NOT operators allow you to combine multiple constraints so that the entire constraint returns true only if certain patterns of the component constraints are true.You can build complex policy constraints using.
For clarity, it is recommended that complex boolean expressions be grouped using parentheses as shown in the following examples:
(A AND (B OR C)) AND (NOT D)
To interpret parenthetical groupings, first evaluate statements within parentheses and, if there are nested parentheses, evaluate the inner ones first. Then evaluate the other statements.
To avoid long OR or AND statements, policies can be defined in constraint sets. For example, rather than writing:
Extensions allow you to add new keywords to the policy language. These keywords can represent new data types, constants, attributes, and evaluation functions. Extension names must start with a letter or an underscore. There are three types of extensions:
Attributes and evaluation functions declare an instance (variable) of a built-in type. Attributes are based on predefined or user-defined types, and evaluation functions are based on boolean types.
For more information on extensions, see Extensions.
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 use its literal value, 12. You use constants to make policies more readable and simplify policy-wide value changes.
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, each policy would require modifying if the value changes. 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.
Here are some examples of simple constants:
CONST Insurance = "home";
CONST InterestRate= 12;
Constants can contain other constants in their value:
CONST ClosurePoints = 2;
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.
A constant can also contain a list of more than one value. For example, a constant named MyColors may have the values red, green, blue, white and black.
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:
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:
Active = "Bert"
OR Active = "Marty"
OR Active = "Sandy"
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"
Attributes store values that are predefined or determined dynamically 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.
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.
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 attributes:
cred month : month_type;
cred timeofday : time;
cred pencils_swiped : integer;
For a description of the different attribute types, see the following topics:
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.
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.
In order to use Identity Attributes in authorization or role mapping policies you must configure a ALESIdentityAttributeRetriever for ASI Authorization Provider.
Many attributes are specific instances of a extension type. These attributes are often user (identity) attributes. For example, a type called ColorType, 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-7 lists some examples of user attributes.
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. 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.
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.
As shown in Table 4-8, there are numerous pre-defined time and date system attributes. Most system attributes allow you to use comparison and range operators.
time24gmt1
|
||
1gmt is an abbreviation for Greenwich Mean Time |
Request attributes are system attributes that contain details of the request. Table 4-9 describes these attributes and provides and example of each one.
An evaluation function returns either true or false. OES provides a number of out-of-box evaluation functions and you may introduce others using a plug-in extension.
For instance, a plug-in for an accounting application could include an evaluation function named Overdrawn that contains the results of a calculation indicating if an account was overdrawn. A constraint might use that function like this:
[Deny user access to something] IF Overdrawn();
Evaluation functions can take zero or more parameter values that are passed to the plug-in. For example, the following passes the overdrawn amount to the plug-in:
[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 allows the system to cache the result of an authorization call and use that result if future identical calls are made. The cache automatically invalidates itself if there is a policy change or other client side change that affects the authorization results. However, the cache can not determine 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, set expiration times on policies that reference dynamic data.
| Note: | By default, authorization caching is turned on. |
Table 4-10 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.
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, the result of a 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);
...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 time-dependent policies appropriately.
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:
Response attributes are typically specified using built-in evaluation functions that report name/value pairs. There are two functions for returning attributes: report(), report_as() and report_append_as(). These functions always return TRUE (if there are no errors) and their information is passed to the application as response attributes, embedded within the ResponseContextCollector.
You use report(), report_as() and report_append_as() in the policy after the 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.
if (constraint) and report_as (name,value);| Note: | The evaluated policy must result in a GRANT or DENY decision in order for the report(), report_as() and report_append_as() functions to be invoked. Consider the following usage: |
report(), report_as() and report_append_as() are invoked for a GRANT or DENY decision.report(), report_as() and report_append_as() are not invoked.
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:
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, assume an attribute named department contains the value Accounting. If the following constraint was evaluated...
report(department);
...the response attribute (department = accounting) is set in the response context results. The client application can then use this information as needed.
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.
report_as("error","Your account balance is too low");
report_as("query", "Select * from record_table where dept_type = ", department);
report_as("userlogin", trading_login,trading_password);
report_as("url","http://www.xyz.com/userinfo/xyz100383.htm");
The report_append_as() is similar to the report_as() function except that report_append_as() appends, as flags, a warning on multiple occurrences and appends the value rather than replace. (On multiple report_as() invocations the named response value is reset with the last occurrence.) The following table contains a few comparisons between invoking report_append_as() and report_as() and the results of the invoke. If the value is getting replaced, there should be a warning logged about the change in response attribute value.
The report function returns the name/value pair of the specified attribute. The value may be 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", "Acme 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 action, object, and subject, results in the response attribute car = ford.
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.
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 ASI Authorizer 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 ASI Authorizer 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");
AppContextElement denied = responseContext.getElement( "com.bea.security.Authorization.deniedResources");
| Note: | The case for authorization on the request and the response is not the same. |
Using policy inheritance can reduce the number of policies required to protect a set of resources. The following topics describe how inheritance works:
Users or groups inherit the right (action 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 may have children.
| Note: | It is recommended that you define role policies using groups, rather than individual users. Role 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.
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:
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.
Policies are inherited in a number of ways:
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.
Child resources also inherit the attributes of any parent resource. Resource inheritance allows each child resource in the tree to assume all the attributes of the parent resource. Resource attribute inheritance is powerful as it allows you to define attributes on the parent resource, and have the attributes be inherited to all child resources automatically.
| Note: | It is recommended that you define 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 that handle unusual circumstances. |
|