Configuring Policy Assemblies

Contents

Overview
Configuring a Policy Assembly
Applying a Policy Assembly
Applying a Policy Assembly to a Service

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 Username, 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 may require a <sp:Basic128/> algorithm suite, while another may 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 may 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 Selecting 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.

Configuring a Policy Assembly

To configure a policy as a policy assembly in the 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 the API Gateway.

Applying 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 screen 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 attribue 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 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.

Applying a Policy Assembly to a Service

Reusabe policy assemblies created in Policy Studio can also be applied to services in API Service Manager. When you deploy the newly created policy assembly to the API Gateway, it becomes available for selection in the New API Service wizard in API Service Manager. For more details, see Managing API Services.

Prev  Up  Next
  Home