Configuring Policy Packages


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.

Configuring a Policy Package

To configure a policy as a policy package in the Policy Studio, perform the following steps:

  1. Right-click the policy in the Policy Studio tree on the left, and select Policy Package -> Create.

  2. 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).

  3. 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 Headers for the http.headers attribute).

  4. 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).

  5. When finished, click OK.

  6. Click the Deploy button in the toolbar to deploy the newly created policy package to the API Gateway.

Applying a Policy Package

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.

Applying a Policy Package to a Service

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.