Contents
In some cases, you may need to convert a policy into a modular, reusable piece of functionality
that can be called from other policies. For example, if you have created a complicated policy
that creates a WS-Security Username, inserts it into the message, and subsequently creates an
XML Signature over the token and SOAP body. Depending on the ultimate recipient for this message,
the content may need to be signed using slightly different settings. One service may require one
set of algorithms to be used (for example, a <sp:Basic128/> Algorithm Suite
in WS-SecurityPolicy). While another policy may require a different set of algorithms (for example,
<sp:Basic256/>).
Similarly, subtle differences in the security requirements of services may require the token and signature to be generated using different configurations. For example:
-
Use a basic or digest password for the
UsernameToken -
Insert a
<dsig:CarriedKeyName>into the XML-Signature -
Create an enveloped or enveloping signature
-
Include a
<wsse:BinarySecurityToken> -
Use one signing key over another
-
Sign different parts of the message
If you need to create separate policies to implement such nuances, the task of interoperating
with different vendor services can become arduous, and involves creating several complicated
policies where each may only differ in one field in a given filter. To avoid this duplication,
you can create a policy package that inserts the WS-Security
UsernameToken into the message and generates the XML-Signature. However, instead
of explicitly configuring fields mentioned above (for example, enveloped or enveloping signature,
include a <wsse:BinarySecurityToken>, and the signing key to use), the policy
package can use selectors for these fields, which are configured dynamically at runtime instead
of statically at design time. For more details, see Selecting Configuration Values at Runtime.
The policy package advertises that it requires certain configuration details to be called generically
from other policies. For example, it would typically require the key to sign the message. By templating
the signing policy as a policy package, and making it available to call from other policies like any other
filter, the caller must set the signing key for the policy package to use. In this way, two distinct
policies that require a signed UsernameToken can call the same policy package. By using
selectors to pass in different signing keys, messages are signed using the appropriate key for each
calling policy.
When a policy has been configured as a policy package, it is displayed in the Policy Studio filter palette, and you can drag and drop it into any policy that requires the functionality encapsulated in the package. You must configure any fields required by the policy package when it is dragged and dropped on to the canvas of another policy.
To configure a policy as a policy package in the Policy Studio, perform the following steps:
-
Right-click the policy in the Policy Studio tree on the left, and select Policy Package -> Create.
-
Specify the following settings on the General tab:
-
Palette Category
Enter the filter palette category in which to display the policy package (for example,
Monitoring). -
Palette Icon
Enter the path to the palette icon to display the policy package (for example,
C:\Oracle\apigateway\icons\monitor.ico).
-
-
The Input tab lists all required message attributes for the policy package. You can enter user-friendly names for each attribute to be displayed in the Policy Activation filter for the policy package (for example,
HTTP Headersfor thehttp.headersattribute). -
The Output tab lists the generated message attributes for the policy package. To add a generated attribute, click Add, and enter the following details:
-
Expression
Enter the selector expression for the attribute (for example,
${content.body}). -
Attribute Type
Enter the message attribute type (for example,
com.vordel.mime.Body). -
Output Attribute Name
Enter the message attribute generated by the policy package (for example,
content.body).
-
-
When finished, click OK.
-
Click the Deploy button in the toolbar to deploy the newly created policy package to the API Gateway.
When a policy is configured as a policy package, it is available for reuse in the Policy Studio filter palette. Draging and droping the policy package on to the policy canvas displays the Policy Activation Filter screen for that policy package. This enables you to specify any required message attributes and filter-level monitoring settings.
Specifying Required Attributes
The Required Attributes tab enables you to set the configuration fields required by the policy package (for example, those configured with selectors for dynamic configuration). Click Add to specify the following fields:
-
Required Attribute
Enter the name of the required attribute for display (for example,
HTTP Header). -
Raw Attribute Name
Enter the message attribute name (for example,
http.headers). -
Attribute Type
Enter the message attribute type (for example,
com.vordel.mime.HeaderSet). -
Value/Selector
Enter a message attribue value or selector (for example,
${http.headers}).
Specifying Monitoring Settings
The Traffic Monitor tab enables you to set filter-level monitoring settings. You can configure the following fields:
-
Record outbound transactions
Select whether to record outbound message transactions sent from the API Gateway to remote hosts. This is enabled by default.
-
Record policy path
Select whether to record the policy path for the message transaction, which shows the filters that the message passes through. This is enabled by default.
-
Trace level
Select the filter trace level from the list. Defaults to
INFO.
The reusabe policy packages created in Policy Studio can also be applied to services in API Service Manager. When you deploy the newly created policy package to the API Gateway, it becomes available for selection in the New API Service wizard in the API Service Manager. For more details, see the topic on Managing API Services.
