Using the Detailed Auditing Policy

Learn how to enable detailed auditing of message size, bindings, and contracts.

About Policies Managing Policies About Operational Policies

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

Table of Contents

  1. Introduction
  2. Creating a Detailed Auditing Policy
  3. Configuring a Detailed Auditing Policy
  4. Detailed Auditing Policy options
  5. Attaching the Policy
  6. Detailed Auditing Policy: use case for Policy Manager

Introduction

The Detailed Auditing Policy is an out-of-the-box policy that is part of the Policy Manager default installation. It is an instance of the Auditing Service Policy. It provides detailed auditing of messages and records the message metrics in the Monitoring > Logs tab as well as the messages of each exchange. The policy is located in the Policies folder of the root organization.

Note: Only attach one auditing policy to a service or API; for example, Basic Auditing policy or Detailed Auditing policy. Do not attach multiple auditing policies to a single API.

The following message metrics are recorded:

  • Input Message: Audits Input Message content.
  • Output Message: Audits Output Message content.
  • Fault Message: Audits Fault Message content.
  • Message Size: Audits the size of messages in the exchange.
  • Binding: Audits binding information.
  • Transport: Audits Transport information.
  • Contract: Audits the contract governing a message.

The following identities are audited:

  • Consumer: Audits consumer identity sent with a request message.
  • End User: Audits end-user identity sent with a request message.

back to top

Creating a Detailed Auditing 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 a Detailed Auditing Policy below.

back to top

Configuring the Detailed Auditing 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 a Detailed Auditing 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.

back to top

Detailed Auditing 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.

Audit Messages
Ifentifies 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: specify message content that will trigger auditing. You can define trigger content in one or more of these formats: Regular Expression, JSONPath, or XPath. 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 about using regular expressions, see Using Regular Expressions 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

API Platform Version: 2018.0.0 and later

Use this section to identify that the message binding should be audited. By default, 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 filter out HTTP Transport headers so that user authentication credentials are not recorded in the logs.

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.

Back to top

Attaching the Policy

To use the Detailed Auditing Policy, go to the Policies folder in the Root Organization and attach the policy to a web service, binding, or binding operation. Then, go to the Services > Monitoring section to view the results for Logs, Real Time Charts, and Historical Charts.

Back to top

Detailed Auditing Policy: use case for Policy Manager

This section includes the following usage scenario for the Detailed Auditing Policy:

Audit Entire Message and Message Metrics

Audit entire message and message metrics of each exchange in usage logs of Monitoring tab.

  1. Create a physical service in the Policy Manager Management Console using Create Physical Service.
  2. Provide service details and finish the wizard.
  3. Using Virtualize Service, virtualize and host the physical service on Network Director (ND1), and assign a name (for example, Vs1).
  4. Attach the Detailed Auditing Policy located in the Root Organization Policies folder to the Vs1 service in Service Details > Policy Attachments > Operational Policies.
  5. Send requests from the application/client to the Vs1 service.
  6. The details of the usage logs show the recorded information for each exchange.

    Detailed Auditing policy use case: log details

    The fields that are recorded in each exchange are:

    1. Message Size
    2. Input Message
    3. Output Message
    4. Fault Message
    5. Transport
    6. Contract
    7. Binding
    8. Identities: Consumer/End-User

    Detailed Auditing policy use case: Usage Detail tab

    Detailed Auditing policy use case: Recorded Messages tab

Back to top