Using the Auditing Service Policy

Learn how to create and configure an Auditing Service policy.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

Introduction

The Auditing Service policy allows you to specify conditions under which messages will be audited. Basic Auditing and Detailed Auditing are examples of the Auditing Service policy and are provided out-of-the-box.

Note: You can set up Basic Auditing for successful messages and Detailed Auditing for error conditions.

Creating an Auditing Service Policy

The first step in creating a policy is to define the basic policy information.

To add an operational policy

  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

At this point, you've created the policy, but it doesn't do anything. The next step is to configure the policy details. See Configuring an Auditing Service Policy below.

Configuring an Auditing Service Policy

Once you've created the policy, you can configure the policy details that determine how the policy works. Then you can activate the policy so that it can be used.

To configure an Auditing Service policy in Policy Manager

  1. In the Organization Tree, find the level where the policy was defined. Click to select.
  2. In the center pane, in the Auditing Service Policy section, click Modify. The Modify Auditing Service Policy overlay is displayed, as shown below.

    Modify Auditing Service Policy

  3. Specify values for the messages you want to apply the policy to, the audit identities, and the reporting options. For details on field values, see Auditing Service Policy Options below.
  4. Click Apply.

Now that the policy is defined, you can activate it and start using it. On the right, under Actions, choose Activate Policy.

Auditing Service Policy Options

On the Auditing Service Policy Options page, you can specify:

Refer to the field descriptions below.

Audit Messages

Use this section to identify which messages should be audited. The Audit Messages section includes two main options:

  • Audit All Messages: Enables the auditing of all messages.
  • Filter Messages: Filter settings determine which messages are audited. Options:

    Exchanges resulting in an error: Audits only messages with errors.

    Percentage of exchanges: Audits a random sample of messages based on a specified percentage. If you choose this option, specify an integer percentage from 1 to 99.

    Filter by message content: Allows you to filter the messages to be audited by providing one or more regular expressions, JSONPath expressions, or XPath expressions. If message content matches the specified expressing, auditing is triggered.

    Note: Initially, only the XPath option is available, since auditing is performed on the normalized message. If you choose to apply auditing at the binding level (see Audit Binding below), the additional options appear.

    The XPath option includes a table where you can define Prefix and Namespace for each XPath expression. Click Add or Delete to modify the list. You can also sort the list by clicking the table header. Allows you to filter the messages to be audited by An example is shown below.

    Auditing Service policy: Filter settings

    The XPath option includes a table where you can define Prefix and Namespace for each XPath expression. Click Add or Delete to modify the list. You can also sort the list by clicking the table header.

    For more information, see Using Regular Expressions in Policies, Using JSONPath in Policies, and Using XPath in Policies.

Audit Messages: additional options

The Audit Messages section includes the following additional checkboxes:

  • Audit Input Message: Enables the auditing of input messages.
  • Audit Output Message: Enables the auditing of input messages.
  • Audit Fault Message: Enables the auditing of fault messages.
  • Audit Contract: Enables the auditing of a contract governing a message.
  • Audit Message Size: Enables the auditing of the size of messages in the exchange.

Audit Binding

Use this section to identify that the message binding should be audited. If you check Audit Binding, the policy settings apply to the entire message binding. If you check Audit Transport, you can specify one or more transport headers to exclude.

For example, you could use this option to exclude the authorization cookie so that it isn't recorded in the logs.

Note: When the binding checkbox is selected, the Auditing Service policy is applied at the binding level. At that point, the content can be in any format, so it can be filtered in multiple ways. In this scenario, in the Audit Messages section, RegEx, XPath, and JSONPath are available options. If the policy is applied at the service level (Audit Binding option is cleared) then auditing is performed on the normalized exchange. Since normalized exchanges are always XML, in this scenario only XPath is available in the Audit Messages section.

Auditing Service policy: Audit Binding option

The Transport Header table stores a list of transport headers to be audited. Click Add or Delete to modify the list. You can also sort the list by clicking the table header.

Audit Identities

Checking this box enables the auditing of specified identities included in a request message. Options:

Consumer
Audits the consumer identity sent with a request message.
End-User
Audits the end-user identity sent with a request message.
Additional Subject Categories
Audits the identity associated with one or more specified Subject Categories sent with a request message. If you choose this option, you can create one or more user-defined subject categories that you want to use. You can also add or delete from the table.

Reporting Options

The following reporting options are available:

Log
Indicates that audit information should be logged.
Alert
Indicates that audit information should be delivered in an alert event.

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.

Auditing Service policy use cases

Use cases are available for the following policies, which are implementations of the Auditing Service policy:

Note: The "OutOfMemory" error occurs when the following two causes are encountered.

Cause:

  1. If a file of size 200 MB or more is attached to the request of an API and the default Detailed Auditing policy is attached to the API Product, then an OutOfMemory error will be thrown and the request may fail.

  2. If a file of size 200 MB or more is attached to the response of an API and the default Detailed Auditing policy is attached to the API Product, then an OutOfMemory error will be thrown and the request may fail.

Action:

To avoid an OutofMemory error, the solution is not to attach the default Detailed Auditing policy on the virtual service of the API. However, if you wish to audit the requests and responses, then you should create a Message Auditing policy instance that is configured as described below:

  1. If a file of size 200 MB or more is attached to the request of an API, then use the following configuration.

  2. If a file of size 200 MB or more is attached to the response of an API, then use the following configuration.