Web Client Plug-in

Ops Center Automator Service Builder User Guide

Version
11.0.x
Audience
anonymous
Part Number
MK-99AUT002-18

The Web Client Plug-in sends and receives HTTP request and response messages. When requested, it accesses the server by using a proxy and completes server and proxy authentication.

Function

This plug-in sends and receives HTTP request and response messages and consists of the following functions:

  • Supports HTTP/HTTPS 1.1.
  • Generates an HTTP request message based on the input properties and receives HTTP response messages as output properties.

The following table shows the relationships between HTTP request messages and their corresponding input properties.

Element Input Property
Request line Method requestMethod
URI requestUrl
HTTP/version -
Header requestHeaders
Body requestBody

The following table shows the relationships between HTTP response messages and their corresponding output properties.

Element Output Property
Status line HTTP/version -
Status code responseStatusCode
Status message responseStatusMessage
Header responseHeaders
Body responseBody

Prerequisites

  • To use HTTPS communication, import the destination server certificate or a root certificate that authenticates the server certificate in JRE truststore on the client (Ops Center Automator installation server).

Return codes

The Web Client Plug-in generates the following return codes:

Return Code Description
0 Ended normally.
1 A status code other than Success is returned for an HTTP response message.
70 Failed to connect to the remote host.
77 Failed to resolve the host name for the remote host.
80 Task execution has stopped.
86 An incorrect property value has been specified.
90 A data transmission failure occurred after the connection was established.
91 The size of the HTTP response message exceeds the upper limit value of the system.
127 Another unspecified type of error has occurred.

Property list

The properties available for the Web Client Plug-in. See details in Table 1

Property key Property name Description I/O type
webServiceConnectionCategory Web Service Connection Category When referring to the information of Web Service Connection and using it as an input value of Web Client Plug-in, specify the category of Web Service Connection. Input
webServiceConnectionName Web Service Connection Name When referring to the information of Web Service Connection and using it as an input value of Web Client Plug-in, specify the name of Web Service Connection. Input
requestMethod R Method Specify the HTTP method as follows:
  • GET
  • POST
  • PUT
  • DELETE

The default value is GET.

Input
requestUrl R Request URL Specify the resource URL to which the HTTP request is sent, and a query parameter. The URL-encoded value specified as the input property value is used as is. See Table 1 for more details. Input
requestHeaders Request Headers Specify the HTTP request header in raw format. Use the Content-Type header and the charset parameter to specify the request body format and character set. Input
requestBody Request Body Specify the HTTP request body in the raw format. Use the format specified in the Content-Type header. Input
webAuth R Server Authentication Scheme Specify the server authentication type:
  • none -- No authentication
  • basic -- Basic authentication
  • digest -- Digest authentication
  • negotiate -- Negotiate authentication
Specify "none" for the authentication header in requestHeaders.
Input
webUsername Server Authentication Username Specify the user name used for server authentication, using a maximum of 256 characters. Not valid when the webAuth property key is set to none. See Table 1 for more details. Input
webPassword Server Authentication Password Specify the password used for server authentication, using a maximum of 256 characters. Not valid when the webAuth property key is set to none. See Table 1 for more details. Input
useProxy R Use Proxy Server Set this to true when a proxy connection is required. See Table 1 for more details.

The default value is false.

Input
proxyHostname Proxy Hostname Specify the proxy host name or IP address, using a maximum of 256 characters. Not valid when the useProxy property key is set to false. See Table 1 for more details. Input
proxyPort Proxy Port Number Specify the proxy port number, using 1-65535. Not valid when the useProxy property key is set to false. See Table 1 for more details.

The default value is 8080.

Input
proxyAuth R Proxy Server Authentication Scheme Specifies the proxy authentication type. The following authentication functions are supported:
  • none -- No authentication
  • basic -- Basic authentication
  • digest -- Digest authentication

Specify "none" for the authentication header in requestHeaders.

See Table 1 for more details.

The default value is none.

Input
proxyUsername Proxy Username Specify the user name used for proxy authentication, using a maximum of 256 characters. Not valid when the useProxy property key is set to false or the proxyAuth property key is set to none. See Table 1 for more details. Input
proxyPassword Proxy Password Specify the password used for proxy authentication, using a maximum of 256 characters. Not valid when the useProxy property key is set to false or the proxyAuth property key is set to none. See Table 1 for more details. Input
responseStatusCode Status Code Outputs the status code of the HTTP response message. When "3xx Redirect" is returned, automatic tracking is activated. Output
responseStatusMessage Status Message Outputs the status message of the HTTP response message. Output
responseHeaders Response Headers Outputs the header information of the HTTP response message. Output
responseBody Response Body Outputs the body information of the HTTP response message. Make sure that the size of responseBody does not exceed 30 MB. If the size of responseBody exceeds 30 MB, the value is truncated. Output
R: Required
Note: When using Basic authentication, a request without authentication returns the 401 response code and a "WWW-Authenticate:Basic" header indicating that authentication is required. If "WWW-Authenticate:Basic" is not returned, the authentication token with Base64-converted "Username:Password" is added to the request header. Authentication by the preemptive method is not supported because Digest authentication requires values such as a nonce value to be returned from the server.

The setting value of Web Service Connection can be referred to as a value of the input property of the Web Client Plug-in. In this case, the corresponding input property is overwritten by the setting value of the Web Service Connection.

Whether to refer to the setting value of Web Service Connection is determined by the input value of webServiceConnectionCategory and webServiceConnectionName.

Input Value of webServiceConnectionCategory Input Value of webServiceConnectionName Behavior of Web Client Plug-in
Exist Exist See the value of Web Service Connection. If no matching Web Service Connection is found, it becomes a run-time error.
Exist Not exist Error (tried to refer to Web Service Connection, but did not find the matching one).
Not exist Exist Error (tried to refer to Web Service Connection, but did not find the matching one).
Not exist Not exist Do not refer to the value of Web Service Connection.

When referring to the setting value of WebServiceConnection, the URL (property name: requestUrl) is assembled dynamically at the run time. As the input value of the property, you must specify the part after "/" after the host name. The part before "/" is assembled from the setting value of Web Service Connection. In the case of the string, where the value specified in requestUrl does not begin with "/", it generates a run-time error.

Example: In the case of "http://host:port/Folder/", specify "/Folder/" as the input value. The following table shows the relationship between the value of the Web Service Connection and the input value of the Web Client Plug-in:
Table. Relationship between the value of the Web Service Connection and the input value of the Web Client Plug-in
Item of the Web Service Connection Input Property of Web Client Plug-in Remark
IP Address/Host Name Part of requestUrl host part of "http://host:port/Folder/"
Protocol Part of requestUrl http part of "http://host:port/Folder/"
Port Part of requestUrl port part of "http://host:port/Folder/"
User ID webUsername Output the message to the task logs that overwriting the input value if it was set.
Password webPassword Output the message to the task log that overwriting the input value if it was set.
Use Proxy Server useProxy -
IP Address/Host Name in Use Proxy Server proxyHostname Output the message to the task log that overwriting the input value if it was set.
Port in Use Proxy Server proxyPort Output the message to the task log that overwriting the input value if it was set.
Authentication Type in Use Proxy Server proxyAuth -
User ID in Use Proxy Server proxyUsername Output the message to the task log that overwriting the input value if it was set.
Password in Use Proxy Server proxyPassword Output the message to the task log that overwriting the input value if it was set.

Supported Headers

Headers are transmitted and received in their raw format. The following default headers are supported:

Header Value
Accept application/json
Accept-Language en
Content-Type (Only when POST or PUT is specified as the method.) application/json
Cache-Control no-cache
Pragma no-cache
User-Agent client-software-name, version
Host destination-host-name, port-number
Connection keep-alive

The following headers have a special behavior:

Header Behavior
Charset parameter in the Content-Type header Request: The body character set is converted by using the value specified in the Charset parameter of the Content-Type header. When no value is specified, it is converted to UTF-8.
Response: The body character set is interpreted according to the value specified in the Charset parameter of the Content-Type header. When a charset parameter is not returned, it is interpreted as UTF-8.
Content-Encoding When the Content-Encoding header is returned, the body is extended. The following encoding formats are supported:
  • gzip
  • deflate

Connection timeout value settings

When dealing with any HTTP/HTTPS communication problems that might occur when connecting to the destination, you should configure the connection timeout key value (plugin.http.connect.timeout) so it is obvious when a problem occurs with the connection. The connection timeout value is specified through the key name (config_user.properties) in the properties file under automation-software-installation-folder\conf.

Linkage with the JavaScript Plug-in

Because the Web Client Plug-in does not rewrite input and output property values, linkage with the JavaScript Plug-in is effective when values must be rewritten. Following is an example of linkage with the JavaScript Plug-in to extract the URL encoding and the SSO authentication token from the server response.



The following table shows the flow linkage with the JavaScript Plug-in.

Plug-in Flow Description
JavaScript Plug-in 1 Input URL entered by the user.

Script that runs URL encoding.

Execute Runs URL encoding.
Output URL-encoded URL.
Web Client Plug-in 1 Input URL-encoded URL.

Other information entered by the user (such as the header).

Execute Generates and sends the HTTP request.

Receives and analyzes the HTTP response.

Output Outputs the HTTP response elements (such as the header).
JavaScript Plug-in 2 Input URL-encoded URL.

Reconfigured header.

Other information entered by the user.

Execute Generates and sends the HTTP request.

Receives and analyzes the HTTP response.

Output Outputs the HTTP response elements.

Prerequisites for using Negotiate authentication

Negotiate authentication uses Kerberos v5 authentication, which needs the following configuration files:

File Name Description Edited by user

Kerberos configuration file

(krb5.conf)

Kerberos configuration in the user environment. Required

Login configuration file

(login.conf)

Specifies the authentication technology to be used. Not required

The following code shows that the Kerberos configuration file is in automation-software-installation-folder\conf\plugin. Edit the code, especially the italicized characters, as needed for the user environment.

[libdefaults] // Default value for Kerberos authentication
 default_realm = EXAMPLE.COM // Default realm for Kerberos authentication
 udp_preference_limit = 1

[realms] // KDC setting for each Kerberos realm (you can define settings for multiple realms)
 EXAMPLE.COM = {
  kdc = kdc.example.com // KDC host name
 }

[domain_realm] // Maps the Active Directory domain to the Kerberos realm
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM
Note:
  • Realms are case-sensitive. Because uppercase letters are conventionally used, use uppercase to specify realms (lowercase letters cannot be used).
  • Although Kerberos authentication uses UDP by default, it uses TCP for lager messages. Because TGT requests that use UDP will fail to link with Active Directory, use udp_preference_limit=1 so that TCP is used.
  • Negotiate authentication is available only if Windows is the OS of the management server on which Ops Center Automator is installed.
  • Only the computer account authentication is supported for Negotiate authentication.

Login Configuration File

The following login configuration file is in automation-software-installation-folder\conf\plugin.

com.sun.security.jgss.krb5.initiate { 
  com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true doNotPrompt=false refreshKrb5Config=true; // Specifies the authentication 
technology and options to be used
};

Enter the following in Common-Component-installation-folder\uCPSB11\CC\server\usrconf\ejb\AutomationWebService\usrconf.cfg so that the Kerberos configuration file and the login configuration file are referenced.

Note: The settings in the usrconf.cfg file are reset at the following times. Reconfigure the file after:
  • Performing an upgrade installation or overwrite installation of Ops Center Automator
  • Performing a new installation, upgrade installation, overwrite installation, or removal of a Common Component product
  • Changing the performance mode with the changemode command
add.jvm.arg=-Djava.security.krb5.conf=automation-software-installation-folder/conf/plugin/krb5.conf
add.jvm.arg=-Djava.security.auth.login.config=automation-software-installation-folder/conf/plugin/login.conf add.jvm.arg=-Djavax.security.auth.useSubjectCredsOnly=false