Introduction

To successfully complete a project at one of our clients, the demand arose to sign SOAP messages before sending them to an external server. As SOAP signing was not supported (at the time of writing), a custom solution was needed. At first, we wrote gateway scripts which initially to sign SOAP messages. Given that we needed to reuse the SOAP signing in multiple API’s we decided to develop a User Defined Policy (UDP) to replace the gateway scripts. This allows for easier reuse across multiple API’s.

Building this UDP proceeded less fluently than expected, which is the reason for this blog. However, once you know how to build an UDP, it is not to complex!

In this blog, we will use a specific use caseas an example. This way we are able to add screenshots to clarify actions taken. Remark: for creating UDP’s, deeper knowledge of DataPower is required. Mind that it is NOT the goal of this blog to train one in DataPower. It is merely our intention to explain how to build UDP’s.

This blog is divided in three major parts

1. DataPower Gateway -> What is needed in DataPower for a UDP
2. Prepare your APIC policy
3. IBM APIC toolkit

DataPower Gateway

It is recommended to work with a domain you can mess up. We personally used a DataPower Docker imagecontaining one domain. In case it got messed up (what happened a few times J), we were able to recreate the container and start again or continue from the latest saved status.

Next screenshot shows that we’ll be working on a dedicated domain called UDP. Also, the policy will be built in a MPG (Multi-Protocol Gateway).

In the MPG ‘UDP’ you can add your policy rule if it is SOAP related. It is possible to create a custom MPG, but it is not necessary.

IBM API Connect license

Reuse or create a new MPG-Policy. We called it SoapSigning.

Do your magic here:

• Name of your policy rulemust be the name of your policy + ‘-main’. E.g: ‘sign-soap-main’
• The name ‘sign-soap’ will be used in more locations later!
• The name of the policy is not important.

Export your magic, go back to the main screen, click ‘Export configuration’.

• Give your export a logical name
  • The name must be the name of your policy. This name will also be used in your yaml configuration file.
  • The name = the name of your policy rule without the ‘-main’.
• Select only the object you need → Processing rule → your rule

APIC-Policy

Go to the location where you downloaded your policy rule (sign-soap-zip). Create a folder with the same name as your policy rule (in our case sign-soap). In this folder you create a folder called ‘implementation’. Place your zip-file in this folder (sign-soap/implementation/sign-soap.zip).

Next you create a yaml-file with the same name as your policy-rule (in our case – sign.soap.yaml). Next you can see the syntax of a yaml-file.

Content of the configuration yaml-file

info:
title: <"title of your policy">
name: <"name_policy">
version: <policy_version>
description: <"description">
contact:
name: <"contact_team">
email: <"email_contact_team">
attach:
- <protocol> [ soap|rest ]
properties:
$schema: "http://json-schema.org/draft-04/schema#"
type: object
properties:
key:
label: <"property1">
description: <"description of the property">
type: <property_type>
required:
- key
gateways:
- datapower-gateway 
Code language: HTML, XML (xml)

Yaml file explained (important elements)

• Policy: version must remain 1.0.0. This is NOT related to your policy.
• Info:
  • Tile: can be anything you want
  • Name: must be the same name you used everywhere (in our case ‘sign-soap’)
  • Version: is the version number shown in your assembly.

Properties (properties show in the assembly to be customized).

APIC Toolkit

We will be publishing our UDP using the IBM APIC Toolkit.

Remark: You need to publish the policy to the sandbox first. If you don’t publish it to the sandbox, it does not become available in the APIC assembly view!

1. Login:
   apic.exe login –u <user_name>-p <password>-s <server>–realm [admin|provider]/<realm>
2. Publish your policy to the sandbox:
   apic.exe policies:create -c sandbox –configured-gateway-service <gateway-service>-o <organization>-s <server>–scope catalog <Path_To_Your_Policy>/<your_policy>
3. Do the same for the other catalogs. In case your catalog does not contain spaces, you probably only have to change the catalog name. Else follow next example:
   apic.exe policies:create -c <catalog> –configured-gateway-service <gateway-service>-o <organization>-s <server>–scope space –space <space_name> <Path_To_Your_Policy>/<your_policy>

How to delete a policy

Ensure that there are no API’s running using your policy.

4. Find your policy:
apic.exe policies:list-all -c <catalog>–configured-gateway-service <gateway-service>  -o <organization>-s <server>–scope [catalog|space]

5. Delete your policy:
.\apic.exe policies:delete -c <catalog>–configured-gateway-service<gateway-service>  -o <organization>-s <server>–scope catalog <your_policy>:<policy_version>
.\apic.exe policies:delete -c <catalog>–configured-gateway-service <gateway-service>  -o <organization>-s <server>–scope space –space <space_name> <your_policy>:<policy_version>

Assembly

Following screenshot shows the result in the assembly. In the toolbox on the left we find the newly created policy. Note that the version numberis also visible. In case you have multiple version available, they will be presented ordered by their version number.

Also, take a look at the property from the sign-soap policyin the assembly. You can see how it was defined in the policy yaml file.

Written by:

Niki Heyligen, Kim Meynendonckx, Tim Rombouts

Need some help with UDP’s for your organization?