SOAP services.

SOAP services

A Connection Manager service can define an optional list of SOAP services. Each SOAP service has the following attributes:

Name	Optional	Purpose
URL	No	Base URL of the SOAP service
Start program	No	Pathname of the KCML SOAP server program
User ID	Yes	UNIX user account used to execute the SOAP server
Environment	Yes	List of environment variables

The URL that is used to connect to the SOAP service will be of the form http://hostname:790/serviceName/baseUrl. When a HTTP request is made to the connection manager, and the URL matches the above patten, KCML will be executed in SOAP server mode via the -b flag. If the URL of the HTTP request is not of the form http://hostname:790/serviceName/baseUrl, then it is passed on to the built in web server.

The file name of the KCML program that will service SOAP requests is defined in the Start program field. The Connection Manager will use this to set the $SOAPSTART environment variable. The set of environment variables that the SOAP server program inherits will be taken from the service's <environment> section as well as the <general> list of variables. The SOAP service can define extra environment variables, these will override any previous values.

The Connection Manager will also set the $SERVER_HTTP_URI, $PATH_INFO, $SERVER_NAME, $SERVER_PORT, $QUERY_STRING CGI environment variables, so that the SOAP server program can reconstruct URLs, for example in the use of the .Endpoint$ SOAP object property

For example:

soapUrl$ = ENV("SERVER_HTTP_URI") & "//" & ENV("SERVER_NAME") & ":" & ENV("SERVER_PORT") & "/" & ENV("SERVICE") & "/" & ENV("PATH_INFO") & "?" & ENV("QUERY_STRING")

The list of SOAP services can be defined in an XML include file. When using the Display/Update services page, you can reference an include file by setting the URL to include and the Start program to the pathname of the include file. The Connection Manager will expand any environment variables that are in the include file's pathname.

The Connection Manager does not directly support SOAP via SSL (https:) connections, however the use of Apache, mod_ssl.so & the mod_wcm.so module can be used to broker secure SOAP requests to the Connection Manager.

On Unix systems, it is recommended to set the optional User ID attribute. This will cause the SOAP server to be executed under that user's account, instead of being executed by the root super-user.

Starting with Unix versions of the of the KCML 7.04 Connection Manager, system administrators can secure the execution of SOAP servers by defining a list of user names or patterns in /etc/kcml/kcml.conf:-

[SOAP]
ValidUser=fred
ValidUser=bert
ValidUser=kcc*

When /etc/kcml/kcml.conf defines this ACL, the User ID attribute is no longer optional and must be allowed by at least of one of the ValidUser keys. Patterns are case-sensitive and are matched using the same algorithm as KI_PMATCH. In the above example, legitimate User ID values would be fred, bert or any user whose name begins with kcc.

The ValidUser ACL can also exclude specific users by prefixing their name with a ! character, for example:

[SOAP]
ValidUser=!root
ValidUser=*

Would allow any value of the User ID attribute except the root super-user.

If the /etc/kcml/kcml.conf configuration is incorrect or the User ID attribute is not allowed then the Connection Manager will reply with a HTTP '401 Authorization Required' error, the actual error message is reported to the Unix syslog.

Error message	Cause	Remedy
Insecure access permissions on /etc/kcml/kcml.conf	File permissions allow group or public write access	Set permissions so that only the root super-user has write access, see kcml.conf.
The [SOAP] section of /etc/kcml/kcml.conf mandates that SOAP services are executed under a Unix user account	No User ID attribute set	Set a User ID attribute that is allowed by the ValidUser keys of kcml.conf
Missing ValidUser key in the [SOAP] section of /etc/kcml/kcml.conf	kcml.conf defines a [SOAP] section which has no ValidUser keys	Add one, or more, ValidUser keys to the [SOAP] section
Access for user 'fred' has been denied by the [SOAP] section of /etc/kcml/kcml.conf	The User ID attribute has been rejected by the ValidUser list in kcml.conf	Either add ValidUser keys to allow that user account or change the User ID attribute to match the ValidUser keys

See Also: