Internal Use Policies

An internal use policy is a special preconfigured policy that is designed to achieve a specific outcome. These policies are prepackaged in every .
gateway90
An internal use policy is a special preconfigured policy that is designed to achieve a specific outcome. These policies are prepackaged in every
API Gateway
.
To use an internal use policy, choose "Internal Use Policy" as the policy type when creating a new policy, then choose the policy to use from the list of policy tags. For more information, see Create a Policy or Policy Fragment.
The following internal use policies are currently available on the
API Gateway
:
  • wsdm-notifications
  • Audit Message Filter
  • Audit Viewer
wsdm-notifications
The wsdm-notifications policy is evaluated for each WSDM notification message. This message is related to a subscription added via the "WSDM Subscription Service" internal service. In this policy, the request is initialized to the notification messasge.
This policy adds a A Route via HTTP(S) assertion that routes to ${esmNotificationUrl}, which refers to the value of the "<wsnt:Subscribe><wsnt:ConsumerReference><wsa:Address>" tag of the Subscribe method in EsmSubscriptionManagementServiceBinding.
Audit Message Filter (AMF) Policy
The AMF policy is designed to remove sensitive data from messages and to protect data prior to auditing. This policy is intended to be used in conjunction with the AV (Audit Viewer) policy.
After the service policy and any global policy fragment completes, the AMF policy will be executed for each request and/or the response that will be audited. This allows the policy author to (for example) remove sensitive data from the message or apply any necessary encryption or signature to the message.
 
The request message that is run through the AMF policy may have undergone a security undecoration process by the
API Gateway
. As a result, it may not be the same as the request first received by the
API Gateway
.
 
A message is audited under the following conditions:
  1. The policy contains the Audit Messages in Policy assertion, configured with a sufficiently high level.
  2. An assertion fails, causing the target message to be audited. (This assumes the audit.hinting cluster property is set to its default value of "true".)
If the AMF policy completes successfully, the value in the request or response message is passed onto the
API Gateway
 auditing subsystem (either the internal database and/or an audit log sink, if one has been configured). If the AMF policy fails (that is, one of its assertions returns any assertion status code other than '0'), then the message is not sent to the auditing subsystem. Instead, an audit detail is added to the audit record stating that the AMF policy failed for the relevant message—request or response.
 
The Audit Message Filter policy only runs for policy message audits. To learn more about this type of audit and about
API Gateway
auditing in general, see Message Auditing.
 
Keep in mind the following when using the AMF policy:
  • Only one AMF policy can be created per
    API Gateway
     cluster.
  • This policy cannot access context variables created by any other service policy or global policy fragment.
  • Auditing within an AMF policy is disabled.
  • The output of the AMF policy must be text/xml for it to work with the AV policy.
  • The AMF policy may use the audit viewer subject certificate as the recipient certificate for the (Non-SOAP) Encrypt XML assertion. If you create an AMF policy after designating an AV key, then the default AMF policy will encrypt for the AV key. However, there is currently no warning if the recipient certificate is something other than the designated AV key.
Understanding the Default AMF Policy
The following default policy is created when you add an AMF policy (assuming that all the assertions are licensed):
image2014-10-15 17:56:34.png
The default policy contains these assertions to help you get started:
  • Encode/Decode Data Assertion:
    This assertion encodes the request into Base64 format, which offers the greatest flexibility in handling the various message types.
  • Set Context Variable Assertion:
    This assertion creates an XML Message variable using an arbitrary
    API Gateway
     schema containing the Base64 data.
  • (Non-SOAP) Encrypt XML Element Assertion:
    This assertion encrypts the XML message into the request.
Use the default assertions as a starting point to help you create your own AMF policy. For more information, see Create a Policy.
 
Develop your AMF policy as policy fragments. This makes it easier for testing and troubleshooting. For more information, see Working with Policy Fragments.
 
Audit Viewer (AV) Policy
The AV policy can be invoked when viewing audits (for audit messages or audit details) in the Gateway Audit Events window. The AV policy is intended to reverse the actions of the AMF policy. Using security roles, you can restrict the AV policy only to individuals who have a business need to view data protected by the AMF policy. The AV policy uses a special "audit viewer" private key to enforce this restricted access.
For information on viewing audits, see Gateway Audit Events. For information on the audit viewer private key, see Private Key Properties.
The AV policy takes messages (requests or responses) that were encrypted by the AMF policy and displays them in decrypted form in the Gateway Audit Events window.
Keep in mind the following when using the AV policy:
  • Only one AV policy can be created per
    API Gateway
     cluster.
  • The AV policy assumes that the audit message or detail to be processed is in XML format (Content-Type 'text/xml'). If it is not, then the AV policy cannot process it.
  • This policy cannot access context variables created by any other service policy or global policy fragment.
  • Avoid using the Run All Assertions Concurrently assertion in the AV policy.
Understanding the Default AV Policy
The following default policy is created when you add an AV policy (assuming that all the assertions are licensed).
image2014-10-15 18:1:9.png
The default policy contains these assertions:
  • (Non-SOAP) Decrypt XML Element Assertion:
    This assertion decrypts the XML that was encrypted by the AMF policy.
  • Evaluate Request XPath Assertion:
    This assertion uses an XPATH query to extract the Base64 data from the request.
  • Encode/Decode Data Assertion:
    This assertion decodes the results back to text/xml format.
The default assertions are designed to reverse the effects of the default AMF policy. Use them as a starting point to help you create your own AV policy. For more information, see Create a Policy.
Develop your AV policy as policy fragments. This makes it easier for testing and troubleshooting. Policy fragments can also be used to protect data audited via the Add Audit Detail Assertion. For more information, see Working with Policy Fragments.