Configure policy assemblies

Contents

Overview
Configure a policy assembly
Apply a policy assembly

Overview

In certain cases, you may need to convert a policy into a modular reusable piece of functionality that can be called from other policies. For example, you have a complex policy that creates a WS-Security UsernameToken, inserts it into the message, and subsequently creates an XML Signature over the token and SOAP body. Depending on the message recipient, the content may need to be signed using slightly different settings. One service might require a <sp:Basic128/> algorithm suite, while another might require <sp:Basic256/>).

Similarly, subtle differences in security requirements may require the token and signature to be generated differently. 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 for such cases, interoperating with different vendor services can become arduous. This involves creating several complicated policies that might only differ in one field in each filter. To avoid this duplication, you can create a policy assembly 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>, or signing key to use), the policy assembly can use selectors for these fields, which are configured dynamically at runtime. For more details, see Select configuration values at runtime.

The policy assembly advertises that it requires configuration details to be called generically from other policies. For example, it requires the key to sign the message. By templating the signing policy as a policy assembly, and making it available to call from other policies like any other filter, the caller must set the signing key for the policy assembly. In this way, different policies that require a signed UsernameToken can call the same policy assembly. 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 assembly, it is displayed in the Policy Studio filter palette, and you can drag and drop it into any policy that requires the functionality in the assembly. You must configure any fields required by the policy assembly when it is dragged and dropped on to the canvas of another policy.

Configure a policy assembly

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

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

  2. Specify the following settings on the General tab:

    • Palette Category:

      Enter the filter palette category in which to display the policy assembly (for example, Monitoring).

    • Palette Icon:

      Enter the path to the palette icon to display for the policy assembly (for example, C:\Oracle\apigateway\icons\monitor.ico).

  3. The Input tab lists all required message attributes for the policy assembly. You can enter user-friendly names for each attribute to be displayed in the Policy Activation filter for the policy assembly (for example, HTTP Headers for the http.headers attribute).

  4. The Output tab lists the generated message attributes for the policy assembly. 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 assembly (for example, content.body).

  5. When finished, click OK.

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

Apply a policy assembly

When a policy is configured as a policy assembly, it is available for reuse in the Policy Studio filter palette. Draging and droping the policy assembly on to the policy canvas displays the Policy Activation Filter window for that policy assembly. 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 assembly (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 attribute value or selector (for example, ${http.headers}).

Specifying monitoring settings

The Traffic Monitor tab enables you to set the following filter-level monitoring settings:

  • Record outbound transactions:

    Select whether to record outbound message transactions sent from 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.

Prev  Up  Next
  Home