Remote XML-based management of IBM DataPower Gateways with B2B module

White Papers

Abstract

IBM DataPower Gateways with B2B module provides a secure, easy-to-maintain solution for managing B2B networks. The DataPower SOAP Configuration Management (SOMA) interface enables administrators to programmatically configure, monitor, and manage the device, and this article uses sample SOMA requests to show you how to configure partners and gateways.

Content

IBM DataPower Gateways with B2B module and SOMA

The IBM DataPower Gateways appliance with B2B module is a purpose-built hardware appliance that provides a powerful, flexible, and secure solution for handling B2B traffic, Applicability Statement (AS) message processing, and managed file transfer. As part of the DataPower line of SOA appliances, the DataPower appliance also provides functionality for securing and managing SOA transactions, Web services, and XML processing with XSLT transformations.

DataPower appliances can perform remote configuration and monitoring via the SOAP Configuration Management (SOMA) protocol. SOMA requests are XML messages sent to a configured port on the DataPower appliance. The standard configuration message is a <dp:request> SOAP message containing a set-config element to create new objects, a modify-config element to modify existing objects, or a get-config element to retrieve an existing configuration. The SOMA interface is secure (requests and responses are sent over an SSL connection) and it adheres to the Role Based Management (RBM) capability configured on the DataPower appliance.

The full SOMA schema, including the configurable DataPower objects, are on the DataPower appliance in the store:/// directory. The files are in store:///xml-mgmt-base.xsd, store:///xml-mgmt-ops.xsd, and store:///xml-mgmt.xsd

Before sending SOMA requests, ensure that XML Management is enabled on your box: Select WebGUI panel Network => Management => XML Management Interface, set the desired Listening IP address and port, and mark the Admin state as enabled. The default of 0.0.0.0 makes the service available on all addresses. You can also set authentication and authorization configuration for XML management.

WebGUI Control Panel config for XML management interface

Requests are sent to the DataPower appliance URI /service/mgmt/current, generally with a basic authentication header. You can download a sample domain that can be imported to test the sample SOMA requests, as well as copies of the article's requests and responses. Make sure that the Application Domain name on the DataPower appliance matches that of the samples (hubowner), to avoid authentication failures. In some cases, the sample XML files and listings must be done in order to ensure that underlying objects are available. Use the following curl command to send the sample SOMA requests below:

  curl -k --data-bin @request.xml -H "Content-Type: text/xml" -u username:password  https://[DataPower hostname]:5550/service/mgmt/current

Retrieving B2B object configuration

To retrieve configuration from the DataPower appliance, use the SOMA get-config request type. The example below requests the B2BGateway config for a gateway named HubOwner. Send the request to the IP address and port configured above with the appropriate credentials.

Listing 1. Sample request to retrieve B2BGateway configuration (soma-get-b2bgw.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:get-config name="HubOwner" class="B2BGateway"/>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

The DataPower appliance will return a SOAP response describing the B2BGateway service. The XML file below shows a sample response to the get-config request with some elements removed for clarity:

Listing 2. Sample response to SOMA request in Listing 1 (soma-get-b2bgw-resp.xml)

  <?xml version="1.0" encoding="UTF-8"?>  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">   <env:Body>   <dp:response xmlns:dp="http://www.datapower.com/schemas/management">   <dp:config>   <B2BGateway xmlns:env="http://www.w3.org/2003/05/soap-envelope" name="HubOwner">   <mAdminState>enabled</mAdminState>   <UserSummary>Primary B2B Hub</UserSummary>   <ASFrontProtocol>   <FrontProtocol class="AS2SourceProtocolHandler"> HubOwner_AS2 </FrontProtocol>   <MDNReceiver>on</MDNReceiver>   </ASFrontProtocol>   <B2BProfiles>   <PartnerProfile class="B2BProfile">PartnerA_Ext</PartnerProfile>   </B2BProfiles>   <B2BProfiles>   <PartnerProfile class="B2BProfile">HubOwner_Int</PartnerProfile>   </B2BProfiles>   <XMLManager class="XMLManager">default</XMLManager>   </B2BGateway>   </dp:config>   </dp:response>   </env:Body>  </env:Envelope>

The results show the gateway with an AS2 Front Side Handler, and an internal and external partner. To retrieve the configuration details for a partner, issue a get-config request with the XML in Listing 3 below. This SOMA request asks for the B2BProfile named PartnerA_Ext:

Listing 3. Sample request to retrieve B2BProfile configuration (soma-get-b2bprofile.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:get-config name="PartnerA_Ext" class="B2BProfile"/>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

The output indicates the configuration for this particular partner, including the associated business IDs and destination information (some elements have been removed for clarity):

Listing 4. Sample response to SOMA request in Listing 3 (soma-get-b2bprofile-resp.xml)

  <?xml version="1.0" encoding="UTF-8"?>  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">   <env:Body>   <dp:response xmlns:dp="http://www.datapower.com/schemas/management">   <dp:config>   <B2BProfile name="PartnerA_Ext"   xmlns:env="http://www.w3.org/2003/05/soap-envelope">   <mAdminState>enabled</mAdminState>   <UserSummary>Partner Public Profile</UserSummary>   <ProfileType>external</ProfileType>   <BusinessIDs>partnerA</BusinessIDs>   <Destinations>   <DestName>Partner_AS2</DestName>   <DestURL>as2://partner-a.com:60003/PartnerAS2</DestURL>   <ASMDNRequest>on</ASMDNRequest>   <ASMDNRequestAsync>on</ASMDNRequestAsync>   <AS2MDNRedirectURL>https://hubowner.com:60001</AS2MDNRedirectURL>   </Destinations>   </B2BProfile>   </dp:config>   </dp:response>   </env:Body>  </env:Envelope>

Adding and configuring a trading partner

In addition to retrieving configurations, you can use the SOMA interface to set and modify existing configurations. The examples below show how to configure a new partner and add it to an existing gateway, using the two request types set-config and modify-config. A single SOMA request can contain only one of these two request types, but each can set or modify multiple configuration objects.

As required by the XML Management schema, all elements of the complex property dmB2BDestination are required. You can get a list of all the elements by issuing a get-config SOMA request or by examining the XML Management schema. Listing 5 below shows a sample SOMA request to add configuration for a new partner. The set-config request type is used since this is a new configuration.

Listing 5. Sample request to create a new B2B Partner Profile (soma-create-b2bprofile.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:set-config>   <B2BProfile name="PartnerY_Ext">   <UserSummary>Partner Public Profile</UserSummary>   <ProfileType>external</ProfileType>   <BusinessIDs>yypartner</BusinessIDs>   <Destinations>   <DestName>Partner_AS2</DestName>   <DestURL>as2://partner-y.com:60003/PartnerAS2</DestURL>   <EnabledDocType/> <SMTPServerConnection/> <EmailAddress/>   <SSLProxy/>   <OverrideTimeout>120</OverrideTimeout>   <EnableFTPSettings>off</EnableFTPSettings>   <UserName/><Password/>   <Passive>pasv-req</Passive>   <AuthTLS>auth-off</AuthTLS>   <UseCCC>ccc-off</UseCCC>   <EncryptData>enc-data-off</EncryptData>   <DataType>binary</DataType>   <SlashSTOU>slash-stou-on</SlashSTOU>   <QuotedCommands/>   <SizeCheck>size-check-optional</SizeCheck>   <ASCompress>off</ASCompress>   <ASCompressBeforeSign>off</ASCompressBeforeSign>   <ASSendUnsigned>off</ASSendUnsigned>   <ASEncrypt>off</ASEncrypt>   <ASEncryptCert/>   <ASMDNRequest>on</ASMDNRequest>   <ASMDNRequestAsync>on</ASMDNRequestAsync>   <AS1MDNRedirectEmail/>   <AS2MDNRedirectURL>http://hubowner.com:60001</AS2MDNRedirectURL>   <AS3MDNRedirectURL/>   <ASMDNRequestSigned>off</ASMDNRequestSigned>   <Retransmit>off</Retransmit>   <ACKTime>120</ACKTime>   <MaxResends>3</MaxResends>   <ASEncryptAlg>3des</ASEncryptAlg>   <ASMDNRequestSignedAlgs>sha1,md5</ASMDNRequestSignedAlgs>   </Destinations>   </B2BProfile>   </dp:set-config>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

The response to this request is shown in Listing 6:

Listing 6. Response to SOMA request in Listing 5 request (soma-create-b2bprofile-resp.xml)

  <?xml version="1.0"?>  <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">   <env:Body>   <dp:response xmlns:dp="http://www.datapower.com/schemas/management">   <dp:timestamp>2009-10-19T00:48:27-04:00</dp:timestamp>   <dp:result>OK</dp:result>   </dp:response>   </env:Body>  </env:Envelope>

You must now add the partner object must to an active gateway in order to send and receive requests associated with this partner. Use a modify-config request to avoid resetting the object:

Listing 7. Sample request to add a partner profile to a B2B Gateway (soma-add-profile-to-b2bgw.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:modify-config>   <B2BGateway name="HubOwner">   <B2BProfiles>   <PartnerProfile class="B2BProfile">PartnerY_Ext</PartnerProfile>   <ProfileEnabled>on</ProfileEnabled>   <ProfileDest/>   </B2BProfiles>   </B2BGateway>   </dp:modify-config>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

If successful, the box will return a response similar to the one in Listing 6 above.

Securing partner communication

As another example, suppose you want to secure communication to an existing partner, by requiring messages destined to that partner (HubOwner_Int) to be encrypted. You need to add the key and certificate to the DataPower's cert store, create an IDCredential, and update the partner's configuration. All of these steps can be done via SOMA.

Two SOMA requests are required to add the key and certificate files. The following SOAP request uploads a public certificate to the DataPower appliance. A similar request is needed to upload the encryption key, which is private. Although the SOMA request is SSL encrypted, make sure that the key's source, transmission, and destination (the DataPower) meet your company's security requirements. A sample SOMA request to upload the key corresponding to the certificate in Listing 8 below is included in the sample request files, which you can download at the bottom of the article. The XML contains a base64 encoded version of the certificate in one of the formats that the appliance accepts, such as DER or PEM.

Listing 8. Sample request to add a file to the box (soma-add-cert-file.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management"   domain="hubowner">   <dp:set-file name="cert:///mycompany.pem">  LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMxVENDQWo2Z0F3SUJBZ0lKQUxDZ3dH  alhZNHVLTUEwR0NTcUdTSWIzRFFFQkJRVUFNRkV4Q3pBSkJnTlYKQkFZVEFsVlRNUll3RkFZ  RFZRUUlFdzFOWVhOellXTm9kWE5sZEhSek1ROHdEUVlEVlFRSEV3WkNiM04wYjI0eApHVEFY  QmdOVkJBb1RFRTE1SUVOdmJYQmhibmtzSUVsdVl5NHdIaGNOTURreE1UQTFNakl6TWpJeVdo  Y05NVEl3Ck9EQXhNakl6TWpJeVdqQlJNUXN3Q1FZRFZRUUdFd0pWVXpFV01CUUdBMVVFQ0JN  TlRXRnpjMkZqYUhWelpYUjAKY3pFUE1BMEdBMVVFQnhNR1FtOXpkRzl1TVJrd0Z3WURWUVFL  RXhCTmVTQkRiMjF3WVc1NUxDQkpibU11TUlHZgpNQTBHQ1NxR1NJYjNEUUVCQVFVQUE0R05B  RENCaVFLQmdRQzB1ODVBNXNyZ0lWdERiUkhMRmd5cW5oWFE3S2g5Cko2K0J6L3U5QjU0R3hW  R1pPM0NsQnZwMlNYODU2Wmg4aHloU0duMU55UXJDUWxqK0ZDOERyT05HL2lKQ3I0cXMKdTFm  dWZFaEYxVFBRbWNCQ0loVmdNVkhocTdTL2JhOVhsOGZSd01LazhUMzJLSkhRWGkrb0gvdG1Z  TUZNYWJrRwpIVmg2SFVqMWpNa1NFd0lEQVFBQm80RzBNSUd4TUIwR0ExVWREZ1FXQkJUNW1x  RkNwSVhvTFd1Qm9LT2tuS0hFCkp1akptRENCZ1FZRFZSMGpCSG93ZUlBVStacWhRcVNGNkMx  cmdhQ2pwSnloeENib3laaWhWYVJUTUZFeEN6QUoKQmdOVkJBWVRBbFZUTVJZd0ZBWURWUVFJ  RXcxTllYTnpZV05vZFhObGRIUnpNUTh3RFFZRFZRUUhFd1pDYjNOMApiMjR4R1RBWEJnTlZC  QW9URUUxNUlFTnZiWEJoYm5rc0lFbHVZeTZDQ1FDd29NQm8xMk9MaWpBTUJnTlZIUk1FCkJU  QURBUUgvTUEwR0NTcUdTSWIzRFFFQkJRVUFBNEdCQUxNZTUyOTZCRVAvbGxDSkUxeFN0WDdQ  QlVrdVpFU20KeWR5OW5KajJvczZldEpIa0tQZldkTXZpSi9ReHhCcmdhVWpEclhmcHorRklS  NGJlbUZ6YVZrdWk2VGhiQ2JVUgpzRUlRVk9nVDZIcVYrTjlyV3hOZlpFTkY1Tm9ieDRUaHV6  YmFVT0JUeG0rRk93QnB6L0lNckNVQzgvREhSbm9GCjZoOEVld3dwNjNaUQotLS0tLUVORCBD  RVJUSUZJQ0FURS0tLS0tCg==   </dp:set-file>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

The first SOMA request needed to complete the configuration creates a DataPower IDCredential, a configuration object that describes a key/cert pair. The set-config XML generates three objects: a certificate containing the uploaded certificate file, a key containing the uploaded key file, and an IDCredential containing the certificate and key.

Listing 9. Sample request to create an IDCredential object (soma-create-idcred.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:set-config>   <CryptoCertificate name="HubOwnerInt_Cert">   <Filename>cert://mycompany.pem</Filename>   </CryptoCertificate>   <CryptoKey name="HubOwnerInt_Key">   <Filename>cert://mycompany.key.pem</Filename>   </CryptoKey>   <CryptoIdentCred name="HubOwnerInt_IDCred">   <Key>HubOwnerInt_Key</Key>   <Certificate>HubOwnerInt_Cert</Certificate>   </CryptoIdentCred>   </dp:set-config>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

Next, modify the HubOwnerInt object to require incoming AS messages to be encrypted and specify the previously created IDCredential, using the modify-config XML in Listing 10:

Listing 10. Sample request to modify configuration to require encrypted messages to a partner profile (soma-encrypt-b2bprofile.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:modify-config>   <B2BProfile name="HubOwner_Int">   <InboundRequireEncrypted>on</InboundRequireEncrypted>   <InboundDecryptIdCred>HubOwnerInt_IDCred</InboundDecryptIdCred>   </B2BProfile>   </dp:modify-config>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

Saving configuration to flash

SOMA configuration changes, like those made in the CLI or WebGUI, immediately affect only the running configuration. To save the changes to the flash system, issue a SOMA request with a save-config action. The configuration will then persist across system reboots or domain restarts:

Listing 11. Sample request to save configuration to the flash partner profile (soma-save-config.xml)

  <?xml version="1.0"?>  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">   <soapenv:Body>   <dp:request xmlns:dp="http://www.datapower.com/schemas/management" domain="hubowner">   <dp:do-action>   <SaveConfig/>   </dp:do-action>   </dp:request>   </soapenv:Body>  </soapenv:Envelope>

Conclusion

SOMA is a secure, flexible, and maintainable interface for managing DataPower appliances. This article has shown several examples for retrieving and modifying the configuration for an DataPower appliance. Any object's configuration can be created, modified, and retrieved using the SOMA interface. For more information on SOMA, the B2B module and DataPower appliances, see the resources below.

Downloadable resources

soma-sample-files.zip

soma-export.zip

Was this topic helpful?

Document Information

Modified date:
08 June 2021

UID

ibm11109373

Tips