Extension SDK for BEA WebLogic Network Gatekeeper
|
 |
 |
|
 |
 |
The following sections contain descriptions of Policy Rules and Policy Utilities:
The policy request data is put in a PolicyRequest object which is sent to the Policy Service for evaluation. The data in the PolicyRequest object can be used from the rules evaluating the request.
The PolicyRequest object is created and sent to the rules engine in the Policy Enforcement Point (PEP).
For information on how a PEP is implemented is described in PolicyManager.
In the PEP, the PolicyRequest object, can be populated with the following standard data as described below:
In addition to these standard values, it is possible to add AdditionalParameters, which consists of an array of AdditionalDataValue. This datatype provides a mechanism for the transferring other request data that the predefined to the Policy Decision Point. AdditionalDataValue consist of a name-value pair, where different types of values can be defined in the value part. The following datatypes can be defined in an AdditionalDataValue object.
The name of the name-value pair is defined in the dataName member variable in the AdditionalData object.
Listing 14-1 Defining AdditionalData
AdditionalData adArray[] = new AdditionalData[1];
AdditionalDataValue targetAddressValue = new AdditionalDataValue();
AdditionalData adTargetAddressString = new AdditionalData();
targetAddressValue.stringValue(address);
adTargetAddressString.dataName = "targetAddress";
adTargetAddressString.dataValue = targetAddressValue;
adArray[0] = adTargetAddressString;
policyRequest.additionalParameters = adArray;
See Adding a rule to Policy Decision Point for information on how to use the PolicyRequest object in the rule.
The first thing to do when adding a rule to a Policy Decision Point is to define the name of the rule and to defined the priority of the rule. There are a set of pre-defined priority levels, which are mapped to a numerical value:
Rules with high priority are evaluated prior to rules of low priority.
Listing 14-2 Skeleton of a rule
rule DenySubscriberNotExists
{
priority = high;
when
{
// fetch the policy request data and perform evaluations.
}
then
{
// Take action on
}
};
The PolicyRequest object that was sent to the rule engine can be retrieved in the rules.
The standard requests data is found in the rules via the same names as they are defined in the PolicyRequest object created in the PEP. Below is an example on how the rule assigns the PolicyRequest member variable serviceName to the rule variable sname via the PolicyRequest object. The rule object pr is assigned to the PolicyRequest object.
Listing 14-3 Policy Request data is fetched
?pr: event PolicyRequest(?sname: serviceName);
When the policy rule has evaluated the request and the decision is to deny the request, the rule's representation of the PolicyRequest object must be retracted. Retracting the PolicyRequest object aborts further rule enforcement.
Listing 14-4 Retract a request
retract (?pr);
The requests must also be retracted for allowed requests in the last rule of the execution flow. This could be achieved by adding a general finalizing allow rule that retracts the request. This rule should have priority minimum.
Listing 14-5 General finalizing allow rule that retracts a request
rule AllowServiceRequest
{
priority = minimum;
when
{
?pr: event PolicyRequest();
}
then
{
retract (?pr);
?pr.allow();
}
};
To fetch data defined as AdditionalValues, the data is fetched by name according to the example below. In the example the AdditionalValue named targetAdress is stored in the variable adddDataValue. The PolicyRequest object is pr.
Listing 14-6 Fetching AdditionalValue data
bind ?addDataValue = ?pr.getAdditionalDataStringValue("targetAddress");
Depending on the type, the data is fetched via different methods:
If the datatype is unknown, it can be determined by invoking the discriminator method on the AdditionalDataValue object.
Listing 14-7 Determine the type of an AdditionalDatavalue
bind ?type = ?pr.getAdditionalData.dataValue.discriminator().value();
Where type is one of the following:
Also see the JavaDoc for PolicyRequest.
Service Level Agreements (SLAs) are XML files that contains data which is enforced by Policy rules. The Service Level Agreements are created and loaded into the Policy Engine on these levels:
There are separate Policy rules that enforces these SLAs, one on service provider level and one on application level. The traffic SLAs are both enforced using one rule.
When extending Service Level Agreements, the following steps must be taken:
The SLA schema files are located in
<installation directory>/bin/policy/sla_schema.
There are three different SLA schema files:
app_sla_file.xsd, which defines the SLA schema for the application level SLAs.sp_sla_file.xsd, which defines the SLA schema for the service provider level SLAs.node_sla_file.xsd, which defines the SLA schema for the service provider traffic and total traffic SLA.Update the schema file with the new element. For example, if the service provider SLA schema needs a new element that defines a String value stated in the service provider SLAs as <additionalData>mydata</additionalData>, update the serviceContract in the schema file with the following element:
<xs:element name="additionalData" minOccurs="0" maxOccurs="1" type="xs:int"/>
Load the SLA schema into the Policy service using the Network Gatekeeper Management Tool using the following methods in the Policy service:
reloadApplicationXmlDriver, for reloading application level SLA schemas.
reloadServiceProviderXmlDriver, for reloading service provider level SLA schemas.
reloadNodeXmlDriver, for service provider traffic and total traffic SLA schemas.
In order to enforce the SLA data in, the rule files have to be updated with rules that enforce the new data in the SLA.
The data in the SLA is fetched from an object model the Policy engine creates from the data defined in the SLAs. The data in an SLA is fetched from the Policy Rules by name. For example, if a a tag in the SLA is <additionalData>, the data is fetched using the same name, as described below.
The rule gets the parameter aParam from the Policy request object, and puts in the local variable pr. The parameter aParam is compared with the data fetched from the SLA, and denies the request if the parameter given in the SLA is larger than the parameter provided in the Policy request.
Listing 14-8 Get SLA data and compare with a parameter in a Policy request
rule denyAParamValueNotAllowed
{
priority = high;
when
{
?pr: event PolicyRequest(?serviceName: serviceName;
?aParam: aParam);
?sc: ServiceContract(?scs: scs;
?scs equals ?serviceName;
?aParam > additionalData);
}
then
{
retract (?pr);
?pr.deny("The parameter is not allowed!");
}
};
The rules must be loaded into the Policy engine, this is performed using the Network Gatekeeper Management Tool using the following methods in the Policy Service:
loadApplicationRules, for loading application level rules.
loadServiceProviderRules, for loading service provider level rules.
loadNodeRules, for loading service provider traffic and total traffic rules.
The SLAs needs to be updated with the tag and the data in the new tag. If extending the SLA with the tag defined in the schema file, update the service provider SLA with the tag and data:
<additionalData>mydata</additionalData>
The SLAs holding the new parameters must be loaded in to the Policy engine. See Network Gatekeeper User's guide for information on how to load a new SLAs.
A Policy Utility is a Java object that is used from a rule.
The rule language, Ilog IRL, makes it possible to perform basic evaluation and parameter substitution, but for more complex processing, call-outs to Java object might be necessary. Java objects can also be used for interaction with external systems such as databases, or prepaid systems.
Below is an example of how a Policy Utility object is called from a rule file.
Listing 14-9 Invoking a Policy Utility from a rule
if (MyPolicyUtility.getInstance().subscriberExists(?address,
?sp,
?app,
?reqID,
?sCode) == false) {
retract (?pr);
?pr.deny("The Subscriber " + ?address + " is not in database.");
}
In the example above, the rule calls the method subscriberExists in the class MyPolicyUtility.
A Policy utility class has the following set of characteristics:
A Policy Utility class executes as a singleton class in order to be callable from the rule. The Policy Utility registers its classes in the Policy service, where they are instantiated and executed. As a consequence of the classloader hierarchy, there is a need of two consecutive restarts of the SLEE in which the Policy utility is installed in order to load the Policy Utility -one for the Policy utility to install itself in the SLEE and one to load the Policy Utility into the Policy Service.
When the Policy Utility is instantiated, it registers itself into Policy service. The constructor shall be private since it is a singleton class. A static public class is created to get the Policy Utility Class from the rule, and to instantiate the class if necessary.
Since the Policy Utility class will execute in the Policy service, it fetches the service context for the Policy via reflection.
Listing 14-10 Registering the Policy Utility class
Class internalPolicyContextClass =
Class.forName("com.incomit.policy.InternalPolicyContext");
java.lang.reflect.Method getServiceContextMethod =
internalPolicyContextClass.getMethod("getServiceContext", null);
java.lang.Object serviceContextResultObj =
getServiceContextMethod.invoke(null, null);
m_sc = (ServiceContext) serviceContextResultObj;
The Policy Utility will also use the same POA as the Policy service. The POA is only necessary when the Policy Utility creates new CORBA objects, for example listener objects when connecting to a plug-in.
Listing 14-11 Getting the POA in a Policy Utility Class
java.lang.reflect.Method getChildPOAMethod =
internalPolicyContextClass.getMethod("getChildPOA", null);
java.lang.Object poaResultObj = getChildPOAMethod.invoke(null, null);
m_poa = (org.omg.PortableServer.POA) poaResultObj;
The rule calls a method in the singleton class via a static method that checks if that the class is already instantiated, instantiates it if necessary, and returns the object. In the example in Listing 14-9 this method is named getInstance().
In the example template modules in the Extension SDK, there is an example of a Policy Utility in the directory module_templates\policy_utility.
The Policy Utility is invoked from a rule and it checks if the address parameter is present is a subscriber database.
The subscriber database is interfaced using a Subscriber profile plug-in, and the Policy Utility uses the Plug-in Manager to get the plug-in.
|
|
|