Configuring the Web Services adapter

Adapter type: ro-adapter-ws[baob201401:version]

Default adapter name: SOAPadapter

For the Web Service Method Two and JAX-WS approach, use the proxy settings shown in the <config> section in XML sample for the Web Services adapter configuration with proxy settings only if you use a proxy server for Internet connectivity. Web Service Method One does not work with these settings.

The Web Services adapter supports uploading attachments to the outgoing SOAP request and downloading attachments embedded in the SOAP response received from the web server.

Note

The Web services adapter supports downloading attachments only in the following operations:

  • Make SOAP Request Method One
  • JAX-WS - Make SOAP Request Message mode

To configure the Web Services adapter, see Configuring base adapters.

The following table describes the adapter configuration elements for the Web Services adapter that you can specify by using the form view, XML view, or both. You cannot use the form view to configure elements and attributes that do not have an entry in the "UI label" column.

Configuration node elements for the Web Services adapter

UI label

Element

Description

Required

Clear Asynchronous Cache

<clear-asynchronous-cache>

Periodically clears the cache that stores responses to asynchronous requests

Valid values: true (default), false

No

Delay

<delay>

Specifies the delay in minutes taken by the adapter to clear the cache

No

Timestamp

<timestamp>

Builds a Web Services timestamp and inserts it into the SOAP envelope

Valid values: true, false (default)

No

Time To Live

<time-to-live>

Sets the time difference (in seconds) between the Created and the Expires values in the timestamp

Default value: 60 seconds

No

Username Token

<username-token>

Builds a Web Services Username Token and inserts it into the SOAP envelope

Valid values: true, false (default)

No

User Name

<user-name>

Specifies the user name for the Username Token

Conditional; required if the value of <username-token> is true

Password

<password>

Specifies the password for the Username Token

Conditional; ; required if the value of <username-token> is true

Password Type

<password-type>

Specifies the type of password supported for Username Token authentication

This element is read-only if the value of <username-token> is true.

Valid values: plain-text (default), digest

No

Character Set

<character-set>

Specifies the supporting CharSet

Also called character set, it includes identifiers describing a series of universal characters.

Note

<character-set> is supported only in method one and the JAX-WS approach.

No

Nonce Validation

<nonce-validation>

Adds a <nonce> element to <username-token>

<nonce> is a randomly generated, cryptographic token used to prevent replay attacks. Without <nonce>, when a UsernameToken is passed from one computer to another computer using an insecure transport, such as HTTP, the token might be intercepted and used in a replay attack.

Valid values: true, false (default)

No

Created Validation

<created-validation>

Adds a created element to the <username-token> element

To help eliminate replay attacks, <nonce> and <created> elements are generated within the <username-token> element and used to validate the message. The server checks the freshness of the message by verifying that the difference between the <nonce> element creation time, which is specified by the <created> element, and the current time is within a specified time.

Valid values: true, false (default)

No

Sign Request

<sign-request>

Creates a signature according to the Web Services specification X.509 profile and adds it to the security header

The Token Reference supported by the adapter is Binary Security Token.

Valid values: true, false (default)

No

Attachment Destination Directory

<attachment-destination-directory>

Specifies the directory in which the adapter stores the attachments received with the SOAP response

Default values:

  • Java Virtual Machine (JVM) value for java.io.tmpdir
  • For Microsoft Windows: C:\DOCUME~1\user\LOCALS~1\Temp
  • For Oracle Solaris: var/tmp/
  • For Linux: /tmp

No

None

<signature-properties>

Contains the elements that specify information about the X.509 certificate (public key) and the private key that are used for XML digital signature

Valid values for the mode attribute: key-store (default), key-files, and key-data

No

None

<sign-username-token>

Signs the Web Services <username-token> element in the Security header

Valid values: true, false (default)

No

None

<sign-timestamp>

Signs the Web Services <timestamp> element in the Security header

Valid values: true, false (default)

No

None

<private-key-file>

Specifies the file containing the private key used to sign the SOAP message using the signing algorithm

The adapter supports the following formats:

  • Base64-encoded unencrypted Privacy Enhanced Mail (PEM)
  • Definite Encoding Rules (DER)

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-files

None

<certificate-file>

Specifies the file containing the X.509 Certificate (public key)

The adapter supports the following formats:

  • Base64-encoded unencrypted PEM
  • Definite Encoding Rules (DER)

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-files.

None

<private-key-data>

Specifies the private key in unencrypted Base64-encoded PEM format

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-data

None

<certificate-data>

Specifies the X.509 Certificate (public key) in unencrypted Base64-encoded PEM format

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-data

None

<keystore-file>

Configures the adapter to use the Java Keystore (JKS) specified by the keystore file name

The adapter must contain the absolute path of the keystore file.

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-store

None

<keystore-password>

Specifies the password of the keystore

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-store

None

<alias>

Specifies the user's alias name in the keystore that identifies the private key to sign the document

Conditional; required if the value of the mode attribute of the <signature-properties> element is key-store

None

<password>

Specifies the user's password to get the private signing key from the keystore

No

None

<proxy-settings>

Contains the elements that define the HTTP proxy settings:

  • <host>
  • <port>
  • <user-name>
  • <password>

    Note: <proxy-settings> and all its child elements (<host>, <port>, <user-name>, and <password>) are applicable only to method two and JAX-WS approach

No

None

<host>

Specifies the host name or the IP address of the host for the Web service request

Note

You can specify an IPv6 address with a zone ID for the <host> element in the adapter requests—for example, <host>fe80::20c:29ff:fe5d:38f0%eth0</host>.
To find the zone ID of the required computer, see Zone ID for an IPv6 address.

Conditional; required if <proxy-settings> is used

None

<port>

Specifies the destination port for the Web service request

Conditional; required if <proxy-settings> is used

None

<user-name>

Specifies the name of the user, who requests the proxy service

Conditional; required if <proxy-settings> is used and authentication is enabled and necessary on the proxy server

None

<password>

Specifies the password for the user on the specified host

Conditional; required if <proxy-settings> is used and authentication is enabled and necessary on the proxy server

Use Connection Pooling

<use-connection-pooling>

Specifies whether the connection pooling feature is enabled for the adapter

Valid values: true, false (default)

Note

The connection pooling feature is available only for the JAX-WS method.

No

Max Connections

<max-connections>

If the value of <use-connection-pooling> is true, defines the maximum number of objects that can be in circulation in the pool

Valid values: Any positive integer

Default value: 10

Note

The connection pooling feature is available only for the JAX-WS method.

No

Connection Ttl

<connection-ttl>

If the value of <use-connection-pooling> is true, specifies the maximum amount of time, in minutes, that a connection can remain idle in the connection pool before it is terminated

Valid values: Any positive integer

Default value: 60 minutes

Note

The connection pooling feature is available only for the JAX-WS method.

No

Request Timeout<request-timeout>

Specifies the time taken (in seconds) by the adapter to wait for a response after which the request expires

For example, when the value for the <request-timeout> element is 0, the adapter does not impose any timeout and waits till the response is received from the web server.

Method 1, Method 2, and the Jax-WS/Message mode support the <request-timeout> element.

Default value: 0

No

Note

The Web Services adapter supports only the SOAP with Attachments (SwA) or MIME standard to upload attachments to the outgoing SOAP request or to download attachments embedded in the SOAP response received from the web server.

While the adapter does not require a configuration node, an XML tag, <config/> is required for the Properties field in Grid Manager adapter configuration. The following figure shows an XML template of the adapter configuration for the Web Services adapter. The following configuration clears the cache after a delay of 120 minutes.

XML template of the Web Services adapter configuration

<config>
  <clear-asynchronous-cache></clear-asynchronous-cache>
  <delay></delay>
  <timestamp></timestamp>
  <time-to-live></time-to-live>
  <username-token></username-token>
  <user-name></user-name>
  <password></password>
  <password-type></password-type>
  <character-set></character-set>
  <nonce-validation></nonce-validation>
  <created-validation></created-validation>
  <sign-request></sign-request>
  <attachment-destination-directory></attachment-destination-directory>
  <signature-properties mode="key-files">
    <sign-username-token></sign-username-token>
    <sign-timestamp></sign-timestamp>
    <private-key-file></private-key-file>
    <certificate-file></certificate-file>
  </signature-properties>
  <signature-properties mode="key-data">
    <private-key-data></private-key-data>
    <certificate-data></certificate-data>
  </signature-properties>
  <signature-properties mode="keystore">
    <keystore-file></keystore-file>
    <keystore-password></keystore-password>
    <alias></alias>
    <password></password>
  </signature-properties>
  <use-connection-pooling></use-connection-pooling>
  <max-connections></max-connections>
  <connection-ttl></connection-ttl>
  <request-timeout>0</request-timeout>
</config>

The configuration shown in the following figure does not clear the cache:

XML sample of the Web Services adapter configuration that does not clear the cache

<config>
<clear-asynchronous-cache>false<clear-asynchronous-cache>
<delay>120</delay>
</config>

The following figure shows an XML sample for the Web Services adapter configuration with proxy settings:

XML sample for the Web Services adapter configuration with proxy settings

<config>
      <proxy-settings>
          <host>10.10.255.255</host>
          <port>8070</port>
          <user-name>testuser</user-name>
          <password>testpassword</password>
      </proxy-settings>
</config>

The following figures show the sample adapter configurations for Web Services adapters that require an XML digital signature and a signed Username Token in the Security header of the SOAP envelope. For the key-files or the key-data mode, you must provide the X.509 Certificate (public key) and the private key files or the private key data in unencrypted Base64-encoded Privacy Enhanced Mail (PEM) format.

XML sample of the Web Services adapter configuration for key-files mode

<config>
  <timestamp>true</timestamp>
  <time-to-live>120</time-to-live>
  <sign-request>true</sign-request>
  <signature-properties mode="key-files">
    <sign-timestamp>true</sign-timestamp>
    <private-key-file>C:\Security\pk-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM
    </private-key-file>
    <certificate-file>C:\Security\cert-MJ5GIUNLM2XJ3VRJSYTKOFDWILELDQHB.PEM
    </certificate-file>
  </signature-properties>
</config>

XML sample of the Web Services adapter configuration for key-data mode

<config>
  <timestamp>true</timestamp>
  <time-to-live>120</time-to-live>
  <sign-request>true</sign-request>
  <signature-properties mode="key-data">
    <sign-timestamp>true</sign-timestamp>
    <private-key-data>-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAKomKro6VbW4PeQtUhNzZpSH26vb....IoKFbuJhln+tlJdmN16mzl1QnyDi469i2C/yXQEvNkjiDQGHrMlhA+0eik8+JuL/TEwgrcOYKP5B
I0XNL71L
-----END PRIVATE KEY-----</private-key-data>
<certificate-data>-----BEGIN CERTIFICATE-----
MIICdzCCAeCgAwIBAgIFXseN1xYwDQYJKoZIhvcNAQEFBQAwUzELMAkGA1UEBhMC....m/0iDplDR7XkyTxAx0AWo0RF4mstOszPGbpHBKFri2qxyXM0NmIPX2dJqhKICXP4
8HATrUjWl+peSog=
-----END CERTIFICATE-----</certificate-data>
  </signature-properties>
</config>

The following figure shows the sample adapter configuration for Web Services that require an XML digital signature and signed Username Token in the Security header of the SOAP envelope. For the key-store mode, you must provide the keystore (JKS type) containing the X.509 Certificate (public key) and the private key.

XML sample of the Web Services adapter configuration for key-store mode

<config>
  <username-token>true</username-token>
  <user-name>Demo</user-name>
  <password> </password>
  <password-type>plain-text</password-type>
  <nonce-validation>true</nonce-validation>
  <created-validation>true</created-validation>
  <sign-request>true</sign-request>
  <signature-properties mode="keystore">
    <sign-username-token>true</sign-username-token>
    <keystore-file>C:\Security\bmcatriumwsclient_7.5.00.001.jks
    </keystore-file>
    <keystore-password>atrium</keystore-password>
    <alias>bmcatriumwsclient</alias>
    <password>atrium</password>
  </signature-properties>
</config>

The following figure shows the sample configuration for the Web Services adapter that supports downloading attachments:

XML sample of the Web Services adapter configuration that supports downloading attachments

<config>
  <attachment-destination-directory>D:\Soap_Attachments
  </attachment-destination-directory>
</config>
Was this page helpful? Yes No Submitting... Thank you

Comments