Using the Public and Private Operational Script Policies

Learn how to create your own custom public and private policies and how to associate each policy with different components of a service's definition such as organizations, services, operations, bindings, and access points.

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

Table of Contents

Introduction

The Operational Script Policy allows you create your own custom policy using custom utility scripts that you can associate with different components of a service's definition such as organizations, services, operations, bindings, and access points. Scripts can be defined using JavaScript, Jython, or BeanShell script languages.

The Policy Manager Scripting API, located in the \docs\scriptDocs folder of the Policy Manager installation folder, provides a series of interfaces and classes you can use to build process-related scripts. The API includes lots of use cases and sample code you can experiment with and use as a baseline when building your own custom operational policy scripts.

You can also access the Scripting API on the Akana docs site: Policy Manager Scripting API.

Private Operational Script Policy

  • This policy is considered Private and is not available to the Network Director when attached to a physical service.

Public Operational Script Policy

  • To support executing an Operational Script Policy as a Consumer when calling a physical service, Policy Manager 8.x and later includes the Public Operational Script Policy.

Configuration Options

Both policies include the following configuration options:

  • Imports: This section includes common functions that you might need to perform in your scripts that have been saved in Script objects, using the Policy Manager > Workbench > Organization > Scripts > Add Script function. The available scripts are listed in the Available Scripts tree. You can move any number of the scripts in that tree to the Imported Scripts list box. Only scripts that match the language type are available for selection in the tree.
  • Script Language: A drop-down list box that allows you to select the script language for the script to be added. Supported script languages:
  • Expression: A text box that allows you to enter your script.

Configuration

Let's take a quick walkthrough of the configuration process for each policy to get you started.

Review Script Creation Process

The first step is to review the following documentation, to become familiar with the script creation process, available tools, and the Policy Manager scripting API:

Configure Private Operational Script Policy

To configure a private operational script policy, follow these steps:

  1. Step 1: Add Policy
  2. Step 2: Modify Policy
  3. Step 3: Specify Function
  4. Step 4: Attach Policy
  5. Step 5: Test Policy

Step 1: Add Policy

In Policy Manager, to create a Private Operational Script Policy instance, go to Policies > Operational Policies and choose Add Policy.

Step 2: Modify Policy

When you click Modify to make changes to the Private Operational Script Policy on the Policy Details page, the initial policy looks like this:

To illustrate how to use the policy, we are going to add script code that gets the Service Details.

In the Source section, select JavaScript as the Script Language, add the following code to the Expression section, and then save the policy.

exchange = messageContext.getExchange();
auditLog.debug("Service Name : " + exchange.getServiceName()+ "\n" + "Operation Name : " + exchange.getOperationName()+ "\n" +"Endpoint Name : " + exchange.getEndpointName());

The script editor will look similar to the following:

Step 3: Specify Function

In the Function drop-down, as shown below, you can specify a function.

Function menu (private operational policy

All policy handlers in the policy framework execute in an order dictated by the function they provide. In the Akana Administration Console there is an ordered list of policy functions, and this dictates the policies that are applied and the sequence. You can also:

  • Create your own policy handlers and either use one of the functions listed or create a new function and add it into the list.
  • Manage the order in which policies are executed. This allows more predictable ordering of the sequence in which different policies are executed or implemented. For example, Wire-Security policies are enforced before Transformation policies.

Operational Script policies are essentially custom policies that you can write using JavaScript instead of Java. When adding an operational script, you must let the platform know when to execute the script in relation to the other policy handlers in the framework. To do this, you can define a function that your script is performing. The platform executes this according to the function list of the policy framework.

There might be one or more policies that have a specific function. The functions are as follows:

  • Pre-policy Auditing: Performs the function of auditing, or message logging, before any other policies can affect the message.
  • Denial of Service: Addresses any potential denial of service attacks.
  • Wire Security: Enforces security on the message, ensuring that the message was delivered securely; for example, verifying that a message was signed or encrypted.
  • Authentication: Authenticates any credentials sent in the message.
  • Authorization: Authorizes the authenticated user.
  • Threat: Addresses any message threats such as script injection, SQL injection, or viruses.
  • Transformation: Changes the content of the message.
  • Caching: Returns cached responses if possible.
  • Post-policy Auditing: Performs the function of auditing, or message logging, after all policies have been enforced.

Admin Console Settings for Policy Function

In the Akana Administration Console, to manage the policy settings: Configuration > com.soa.policy.framework:

  • Public Operational Script Policy:
    • Setting: policy.framework.settings.consumerHandlerFunctions
    • Default values: pre-auditing, custom, transform, sec-ctx, message-sec, wire-sec, post-auditing
  • Private Operational Script Policy:
    • Setting: policy.framework.settings.providerHandlerFunctions
    • Default values: pre-auditing, dos, pre-flight, sec-ctx, wire-sec, message-sec, auth, auz, threat, transform, custom, caching, post-auditing

Step 4: Attach Policy

After you've saved your policy, activate it, and attach it to a web service operation.

Step 5: Test Policy

To test the policy, send a request and select Monitoring > Logs > View Usage Record Details > Recorded Messages to view the DEBUG statement that prints the service details.

Configure Public Operational Script Policy

To configure a public operational script policy, follow these steps:

  1. Step 1: Add Policy
  2. Step 2: Modify Policy
  3. Step 3: Specify Function
  4. Step 4: Attach Policy
  5. Step 5: Test Policy

Step 1: Add Policy

In Policy Manager, to create a Public Operational Script Policy instance, go to Policies > Operational Policies and choose Add Policy.

Step 2: Modify Policy

When you click Modify to make changes to the Public Operational Script Policy on the Policy Details page, the initial policy looks like this:

To illustrate how to use the policy, we are going to add script code that will get public credentials.

In the Source section, select JavaScript as the Script Language, add the following code to the Expression section, and then save the policy.

msg = messageContext.getMessage();
subject=msg.getSecuritySubjects().get("urn:org:federatedgovernance:security:subject-category:enduser");
creds = subject.getPublicCredentials();
var printString ="";
for(var i=0; i<creds.length; i++){
printString += creds[i] +"\n"
}
auditLog.debug(printString);

The script editor will look similar to the following:

Step 3: Specify Function

In the Function drop-down, as shown below, you can specify a function.

Function menu (public operational policy

All policy handlers in the policy framework execute in an order dictated by the function they provide. In the Akana Administration Console there is an ordered list of policy functions, and this dictates the policies that are applied and the sequence. You can also:

  • Create your own policy handlers and either use one of the functions listed or create a new function and add it into the list.
  • Manage the order in which policies are executed. This allows more predictable ordering of the sequence in which different policies are executed or implemented. For example, Wire-Security policies are enforced before Transformation policies.

Operational Script policies are essentially custom policies that you can write using JavaScript instead of Java. When adding an operational script, you must let the platform know when to execute the script in relation to the other policy handlers in the framework. To do this, you can define a function that your script is performing. The platform executes this according to the function list of the policy framework.

There might be one or more policies that have a specific function. The functions are as follows:

  • Pre-policy Auditing: Performs the function of auditing, or message logging, before any other policies can affect the message.
  • Denial of Service: Addresses any potential denial of service attacks.
  • Wire Security: Enforces security on the message, ensuring that the message was delivered securely; for example, verifying that a message was signed or encrypted.
  • Authentication: Authenticates any credentials sent in the message.
  • Authorization: Authorizes the authenticated user.
  • Threat: Addresses any message threats such as script injection, SQL injection, or viruses.
  • Transformation: Changes the content of the message.
  • Caching: Returns cached responses if possible.
  • Post-policy Auditing: Performs the function of auditing, or message logging, after all policies have been enforced.

Admin Console Settings for Policy Function

In the Akana Administration Console, to manage the policy settings: Configuration > com.soa.policy.framework:

  • Public Operational Script Policy:
    • Setting: policy.framework.settings.consumerHandlerFunctions
    • Default values: pre-auditing, custom, transform, sec-ctx, message-sec, wire-sec, post-auditing
  • Private Operational Script Policy:
    • Setting: policy.framework.settings.providerHandlerFunctions
    • Default values: pre-auditing, dos, pre-flight, sec-ctx, wire-sec, message-sec, auth, auz, threat, transform, custom, caching, post-auditing

Step 4: Attach Policy

After you've saved your policy, activate it, and attach it to a web service operation.

Step 5: Test Policy

To test the policy, send a request and select Monitoring > Logs > View Usage Record Details > Recorded Messages to view the DEBUG statement that includes the public credentials.

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.

Example: Providing custom content for fault messages using an Operational Script policy

For a sample scenario showing how to provide custom content for fault messages using an Operational Script, policy, see How to Replace Fault Messages.