|
|
This section contains the following topics:
BEA SALT leverages the Tuxedo Service Metadata Repository to define service contract information for both Tuxedo legacy services and SALT proxy services. Service contract information for all listed Tuxedo services is obtained by accessing the Tuxedo Service Metadata Repository system service provided by the local Tuxedo domain. Typically, SALT calls the TMMETADATA system as follows:
GWWS server run-time.It calls the Tuxedo Service Metadata Repository to retrieve necessary Tuxedo service definition at the appropriate time.
It calls the Tuxedo Service Metadata Repository to retrieve necessary Tuxedo service definitions and converts them to the WSDL description.
The following topics provide SALT-specific usage of Tuxedo Service Metadata Repository keywords and parameters:
Table 2-1 lists the Tuxedo Service Metadata Repository service-level keywords used and interpreted by SALT.
| Note: | Metadata Repository service-level keywords that are not listed have no relevance to BEA SALT and are ignored when SALT components load the Tuxedo Service Metadata Repository. |
The Tuxedo Service Metadata Repository interprets parameters as sub-elements encapsulated in a Tuxedo service typed buffer. Each parameter can have its own data type, occurrences in the buffer, size restrictions, and other Tuxedo-specific restrictions. Please note:
Each parameter of the buffer should represent a VIEW/VIEW32 structure member.
Each parameter of the buffer should represent an FML/FML32 field element that may be present in the buffer.
Tuxedo treats these buffers holistically. At most, one parameter is permitted for the buffer to define restriction facets (such as buffer size threshold).
Parameters facilitate describing details about the buffer type.
Table 2-2 lists the Tuxedo Service Metadata Repository parameter-level keywords used and interpreted by SALT.
| Note: | Metadata Repository parameter-level keywords that are not listed have no relevance to BEA SALT and are ignored when SALT components load the Tuxedo Service Metadata Repository. |
|
|||
Specifies the view structure name if the parameter type is view32. For any other typed parameter, BEA SALT ignores this value.
|
|||
This section describes the required and optional configuration tasks for exposing native Tuxedo services as Web Services:
To expose a set of Tuxedo services as Web services through one or more HTTP/S endpoints, a native WSDF must be defined.
Each native WSDF must be defined with a unique WSDF name. A WSDF can define one or more <WSBinding> elements for more Web service application details (such as SOAP protocol details, the Tuxedo service list to be exposed as web service operations, and so on).
Each WSBinding object is defined using the <WSBinding> element. Each WSBinding object must be defined with a unique WSBinding id within the WSDF. The WSBinding id is a required indicator for the SALTDEPLOY file reference used by the GWWS.
Each WSBinding object can be associated with SOAP protocol details by using the <SOAP> sub- element. By default, SOAP 1.1, document/literal styled SOAP messages are applied to the WSBinding object.
Listing 2-1 shows how SOAP protocol details are redefined using the <SOAP> sub-element.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" />
<Service name="tolower" />
</Servicegroup>
<SOAP version=”1.2” style=”rpc” use=”encoded”>
<AccessingPoints>
...
</AccessingPoints>
</SOAP>
</WSBinding>
</Definition>
Within the <SOAP> element, a set of access endpoints can be specified. The URL value of these access endpoints are used by corresponding GWWS servers to create the listen HTTP/S protocol port. It is recommended to specify one HTTP and HTTPS endpoint (at most) for each GWWS server for an inbound WSBinding object.
Each WSBinding object must be defined with a group of Tuxedo services using the <Servicegroup> sub-element. Each <Service> element under <Servicegroup> represents a Tuxedo service that can be accessed from a Web service client.
Each service object is defined using the <Service> element. Each service must be specified with the “name” attribute to indicate which Tuxedo service is exposed. Usually, the “name” value is used as the key value for obtaining Tuxedo service contract information from the Tuxedo Service Metadata Repository.
Listing 2-2 shows how a group of services are defined for WSBinding.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" />
<Service name="tolower" />
</Servicegroup>
...
</WSBinding>
</Definition>
You can create your own plug-in functions to customize SOAP XML payload and Tuxedo typed buffer conversion routine. For more information, see Using BEA SALT Plug-ins in BEA SALT Programming Web Services and Configuring Plug-in Libraries.
Once a plug-in is created and configured, it can be referenced using the <service> element to specify user-defined data mapping rules for that service. The <Msghandler> element can be defined at the message level (<Input>, <Output> or <Fault>) to specify which implementation of “P_CUSTOM_TYPE” category plug-in should be used to do the message conversion. The <Msghandler> element content is the Plug-in name.
Listing 2-3 shows a service that uses the “MBCONV” custom plug-in to convert input and “XMLCONV” custom plug-in to convert output.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" >
<Input>
<Msghandler>MBCONV</Msghandler>
</Input>
<Output>
<Msghandler>XMLCONV</Msghandler>
</Output>
</Service>
</Servicegroup>
...
</WSBinding>
</Definition>
Advanced Web service features can be enabled by configuring WS-Policy files (for example, Reliable Messaging and Web Service Message-Level Security). You may need to create WS-Policy files to use these features. The Web Service Policy Framework specifications provides a general purpose model and syntax to describe and communicate the policies of a Web Service.
To use WS-Policy files, the <Policy> element should be defined in the WSDF to incorporate these separate WS-Policy files. Attribute location is used to specify the policy file path, both abstract and relative file path are allowed. Attribute use is optionally used by message level assertion policy files to specify the applied messages, request (input) message, response (output) message, fault message, or the combination of the three.
There are two different sub-elements in the WSDF that reference WS-Policy files:
Servicegroup>Service>BEA SALT provides some pre-packaged WS-Policy files for most frequently used cases. These WS-Policy files are located under directory $TUXDIR/udataobj/salt/policy. These files can be referenced using location=”salt:<policy_file_name>”.
Listing 2-4 shows a sample of using WS-Policy Files in the native WSDF file.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Policy location=”./endpoint_policy.xml” />
<Policy location=”/usr/resc/all_input_msg_policy.xml” use=”input” />
<Service name="toupper">
<Policy location=”service_policy.xml” />
<Policy location=”/usr/resc/input_message_policy.xml”
use=”input” />
</Service>
<Service name="tolower" />
</Servicegroup>
....
</WSBinding>
</Definition>
For more information, see Specifying the Reliable Messaging Policy File in the WSDF File and Using WS-SecurityPolicy Files.
Once a Tuxedo native WSDF is created, the corresponding WSDL file can be generated using the SALT WSDL generation utility, tmwsdlgen. The following example command generates a WSDL file named “app1.wsdl” from a given WSDF named “app1.wsdf”:
tmwsdlgen -c app1.wsdf -o app1.wsdl
| Note: | Before executing tmwsdlgen, the TUXCONFIG environment variable must be set correctly and the relevant Tuxedo application using TMMETADATA must be booted. |
You can optionally specify the output WSDL file name using the ‘-o’ option. Otherwise, tmwsdlgen creates a default WSDL file named “tuxedo.wsdl”.
If the native WSDF file contains Tuxedo services that use CARRAY buffers, you can specify tmwsdlgen options to generate different styled WSDL files for CARRAY buffer mapping. By default, CARRAY buffers are mapped as xsd:base64Binary XML data types in the SOAP message. For more information, see
Data Type Mapping and Conversions in the BEA SALT Programming Web Services and
tmwsdlgen in the BEA SALT Reference Guide.
To invoke an external Web Service from Tuxedo, the following configuration tasks need to be performed:
BEA SALT provides a WSDL conversion command utility to convert external WSDL files into Tuxedo definitions. The WSDL file is converted using Extensible Stylesheet Language Transformations (XSLT) technology. Apache Xalan Java 2.7.0 is bundled in SALT installation package and is used as the default XSLT toolkit.
BEA SALT WSDL converter is composed of two parts:
wsdlcvt, invokes the Xalan toolkit. This wrapper script provides a user friendly WSDL Converter interface.The following sample command converts an external WSDL file and generates Tuxedo definition files.
wsdlcvt -i http://api.google.com/GoogleSearch.wsdl -o GSearch
Table 2-3 lists the Tuxedo definition files generated by BEA SALT WSDL Converter.
BEA SALT maps each wsdl:message to a Tuxedo FML32 typed buffer. BEA SALT WSDL Converter decomposes XML Schema of each message and maps each basic XML snippet as an FML32 field. The generated FML32 fields are defined in a definition table file, and the field name equals to the XML element local name by default.
To access a SALT proxy service, Tuxedo applications must refer to the generated FML32 fields to handle the request and response message. FML32 environment variables must be set accordingly so that both Tuxedo applications and GWWS servers can map between field names and field identifier values.
|
|||
BEA SALT WSDL Converter converts the WSDL file into a WSDF file, which can be deployed to GWWS servers in the SALT deployment file for outbound direction. The generated WSDF file is so-called non-native WSDF file.
|
|||
WSDL embedded XML Schema and imported XML Schema (XML Schema content referenced with <xsd:import>) are saved locally as .xsd files. These files are used by GWWS servers and need to be saved under the same directory.
|
Table 2-4 lists WSDL Element-to-Tuxedo Service Metadata Definition Keyword mapping rules.
|
||||
Table 2-5 lists WSDL Element-to-WSDF Element mapping rules.
The following post conversion tasks need to be performed for configuring outbound Web service applications:
When converting a WSDL file, unexpected naming conflicts may be found due to truncation or lost context information. Before using the generated Service Metadata Definitions and FML32 field table files, the following potential naming conflicts must be eliminated first.
tuxservice” definitions
The keyword tuxservice in the SALT proxy service metadata definition is the truncated value of the original Web Service operation local name if the operation name is more than 15 characters. The truncated tuxservice value may be duplicated for multiple SALT proxy service entries. Since GWWS server uses tuxservice values as the advertised service names, so you must manually resolve the naming conflict among multiple SALT proxy services to avoid uncertain service request delivery. To resolve the naming conflict, you should assign a unique and meaningful name to tuxservice.
When converting a external WSDL file into Tuxedo definitions, each wsdl:message is parsed and mapped as an FML32 buffer format which containing a set of FML32 fields to represent the basic XML snippets of the wsdl:message. By default, The generated FML32 fields are named using the corresponding XML element local names.
The FML32 field definitions in the generated field table file are sorted by field name so that duplicated names can be found easily. In order to achieve a certain SOAP/FML32 mapping, the field name conflicts must be resolved. You should modify the genenated duplicated field name with other unique and meaningful FML32 field name values. The corresponding Service Metadata Keyword param values in the generated SALT proxy service definition must be modified accordingly. The generated comments of the FML32 fields and Service Metadata Keyword “param” definitions are helpful in locating the corresponding name and param.
After potential naming conflicts are resolved, you should load the SALT proxy service metadata definitions into the Tuxedo Service Metadata Repository through tmloadrepos utility. For more information about tmloadrepos, see BEA Tuxedo Service Metadata Repository Documentation.
Before booting GWWS servers for outbound web services, the following environment variable settings must be performed.
FIELDTBLS32 to add the generated FML32 field table files.XSDDIR and XSDFILES accordingly.XSDDIR and XSDFILES are introduced in SALT 2.0 release. They are used by the GWWS server to load all external XML Schema files at run time. Multiple XML Schema file names should be delimited with comma ‘,’. For instance, if you placed XML Schema files: a.xsd, b.xsd and c.xsd in directory /home/user/myxsd, you must set environment variable XSDDIR and XSDFILES as follows before booting the GWWS server:XSDDIR=/home/user/myxsd
XSDFILES=a.xsd,b.xsd,c.xsd
The SALT Deployment file (SALTDEPLOY) defines a SALT Web service application. The SALTDEPLOY file is the major input for Web service application in the binary SALTCONFIG file.
To create a SALTDEPLOY file, do the following steps:
For more information, see SALT Deployment File Reference in the BEA SALT Reference Guide.
You should import all your required WSDF files to the SALT deployment file. Each imported WSDF file must have a unique WSDF name which is used by the GWWS servers to make deployment associations. Each imported WSDF file must be accessible through the location specified in the SALTDEPLOY file.
Listing 2-5 shows how to import WSDF files in the SALTDEPLOY file.
<Deployment ..>
<WSDF>
<Import location="/home/user/simpapp_wsdf.xml" />
<Import location="/home/user/rmapp_wsdf.xml" />
<Import location="/home/user/google_search.wsdf" />
</WSDF>
...
</Deployment>
Each GWWS server can be deployed with a group of inbound WSBinding objects and a group of outbound WSBinding objects defined in the imported WSDF files. Each WSBinding object is referenced using attribute “ref=<wsdf_name>:<WSBinding id>”. For inbound WSBinding objects, each GWWS server must specify at least one access endpoint as an inbound endpoint from the endpoint list in the WSBinding object. For outbound WSBinding objects, each GWWS server can specify zero or more access endpoints as outbound endpoints from the endpoint list in the WSBinding object.
Listing 2-6 shows how to configure GWWS servers with both inbound and outbound endpoints.
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
<Inbound>
<Binding ref="app1:app1_binding">
<Endpoint use="simpapp_GWWS1_HTTPPort" />
<Endpoint use="simpapp_GWWS1_HTTPSPort" />
</Binding>
</Inbound>
<Outbound>
<Binding ref="app2:app2_binding">
<Endpoint use=" extServer1_HTTPPort" />
<Endpoint use=" extServer1_HTTPSPort" />
</Binding>
<Binding ref="app3:app3_binding" />
</Outbound>
</GWInstance>
</WSGateway>
...
</ Deployment>
The GWWS server can be configured with properties that switch feature on/off or set argument to tune the server’s performance.
Properties are configured in the <GWInstance> child element <Properties>. Each individual property is defined by using the <Property> element which contains a “name” attribute and a “value” attribute). Different “name” attributes represent different property elements that contain a value. Table 2-6 lists GWWS server level properties.
| Note: | For more information about GWWS multiple encoding support, see Configuring Multiple Encoding Support. |
| Note: | For more information abouth Performance tuning properties, see Tuning the GWWS Server. |
Listing 2-7 shows an example of how GWWS properties are configured.
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
.......
<Properties>
<Property name="thread_pool_size" value="20"/>
<Property name="enableMultiEncoding" value="true"/>
<Property name="timeout" value="600"/>
</Properties>
</GWInstance>
</WSGateway>
...
</ Deployment>
SALT supports multiple encoding SOAP messages and the encoding mappings between SOAP message and Tuxedo buffer. SALT supports the following character encodings:
| Note: | ASCII, BIG5, CP1250, CP1251, CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, CP850, CP862, CP866, CP874, EUC-CN, EUC-JP, EUC-KR, GB18030, GB2312, GBK, ISO-2022-JP, ISO-8859-1, ISO-8859-13, ISO-8859-15, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, JOHAB, KOI8-R, SHIFT_JIS, TIS-620, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, UTF-8 |
To enable the GWWS multiple encoding support, GWWS server level property “enableMultiEncoding” should be set to “true”.
| Note: | GWWS internally converts non UTF-8 external messages into UTF-8. However, encoding conversion hurts server performance. By default, encoding conversion is turned off and messages that are not UTF-8 encoded are rejected. |
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
.......
<Properties>
<Property name="enableMultiEncoding" value="true"/>
</Properties>
</GWInstance>
</WSGateway>
...
</ Deployment>
Table 2-7 explains the detailed SOAP message and Tuxedo buffer encoding mapping rules if the GWWS server level multiple encoding switch is turned on.
GWWS sets the target SOAP message in UTF-8 encoding, and assumes the original STRING buffer containing only UTF-8 encoding characters.
|
||||
SOAP xml encoding is set to FLD_MBSTRING encoding, the original Typed buffer field characters are not changed in the SOAP message.
|
||||
SOAP xml encoding is set to UTF-8, the original Typed buffer FLD_MBSTRING field characters in other encodings are converted into UTF-8 in the SOAP message.
|
BEA SALT defines a set of global resources shared by all GWWS servers in the SALTDEPLOY file. The following system level resources can be configured in the SALTDEPLOY file:
Certificate information must be configured in order for the GWWS server to create an SSL listen endpoint, or to use X.509 certificates for authentication and/or message signature. All GWWS servers defined in the same deployment file shares the same certificate settings, including the private key file, trusted certificate directory, and so on.
The private key file is configured using the <Certificate>/<PrivateKey> sub-element. The private key file must be in PEM file format and stored locally.
SSL clients can optionally be verified if the <Certificate>/<VerifyClient> sub-element is set to true. By default, the GWWS server does not verify SSL clients.
If SSL clients are to be verified, and/or the X.509 certificate authentication feature is enabled, a set of trusted certificates must be stored locally and located by the GWWS server. There are two ways to define GWWS server trusted certificates:
Listing 2-9 shows a SALTDEPLOY file segment configuring GWWS server certificates.
<Deployment ..>
...
<System>
<Certificates>
<PrivateKey>/home/user/gwws_cert.pem</PrivateKey>
<VerifyClient>true</VerifyClient>
<CertPath>/home/user/trusted_cert</CertPath>
</Certificates>
</System>
</Deployment
A plug-in is a set of functions that are called when the GWWS server is running. BEA SALT provides a plug-in framework as a common interface for defining and implementing plug-ins. Plug-in implementation is carried out through a dynamic library that contains the actual function code. The implementation library can be loaded dynamically during GWWS server start up. The functions are registered as the implementation of the plug-in interface.
In order for the GWWS server to load the library, the library must be specified using the <Plugin>/<Interface> element in the SALTDEPLOY file.
Listing 2-10 shows a SALTDEPLOY file segment configuring multiple customized plug-in libraries to be loaded by the GWWS servers.
<Deployment ..>
...
<System>
<Plugin>
<Interface lib=”plugin_1.so” />
<Interface lib=”plugin_2.so” />
</Plugin>
</System>
</Deployment
| Note: | If the plug-in library is developed using the SALT 2.0 plug-in interface, the “id” and “name”attributes for the interface do not need to be specified. These values can be obtained through plugin interfaces. |
| Note: | For more information, see Using Plug-ins with BEA SALT in BEA SALT Programming with Web Services. |
BEA SALT currently supports the following advanced Web Service Messaging features:
Supports both inbound and outbound asynchronous Web service messaging.
BEA SALT supports Web service addressing for both inbound and outbound services. The Web service addressing (WS-Addressing) messages used by the GWWS server must comply with the Web Service Addressing standard (W3C Member Submission 10 August 2004).
Inbound services do not require specific Web service addressing configuration. The GWWS server accepts and responds accordingly to both WS-Addressing request messages and non WS-Addressing request messages.
Outbound services require Web service addressing configuration as described in the following sections:
For outbound services, Web service addressing is configured at the Web service binding level. In the SALTDEPLOY file, each GWWS server can specify a WS-Addressing endpoint by using the <WSAddressing> element for any referenced outbound WSBinding object to enable WS-Addressing.
Once the WS-Addressing endpoint is configured, the GWWS server creates a listen endpoint at start up. All services defined in the outbound WSBinding are invoked with WS-Addressing messages.
Listing 2-11 shows a SALTDEPLOY file segment enabling WS-Addressing for a referenced outbound Web service binding.
<Deployment ..>
...
<WSGateway>
<GWInstance id="GWWS1">
...
<Outbound>
<Binding ref="app1:app1_binding">
<WSAddressing>
<Endpoint address=”https://GWWS_host:8801/app1_async_point”>
</WSAddressing>
<Endpoint use=" extServer1_HTTPPort" />
<Endpoint use=" extServer1_HTTPSPort" />
</Binding>
<Binding ref="app2:app2_binding">
<WSAddressing>
<Endpoint address=”https://GWWS_host:8802/app2_async_point”>
</WSAddressing>
<Endpoint use=" extServer2_HTTPPort" />
<Endpoint use=" extServer2_HTTPSPort" />
</Binding>
</Outbound>
...
</GWInstance>
</WSGateway>
...
</ Deployment>
| Notes: | In a GWWS server, each outbound Web Service binding can be associated with a particular WS-Addressing endpoint address. These endpoints can be defined with the same hostname and port number, but the context path portion of the endpoint addresses must be different. |
| Note: | If the external Web service binding does not support WS-Addressing messages, configuring Addressing endpoints may result in run time failure. |
No matter you create a WS-Addressing endpoint or not in the SALTDEPLOY file, you can explicitly disable the Addressing capability for particular outbound services in the WSDF. To disable the Addressing capability for a particular outbound service, you should use the property name “disableWSAddressing” with a value set to “true” in the corresponding <Service> definition in the WSDF file. This property has no impact to any inbound services.
Listing 2-12 shows WSDF file segment disabling Addressing capability.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper">
<Property name="disableWSAddressing" value=”true” />
</Service>
<Service name="tolower" />
</Servicegroup>
....
</WSBinding>
</Definition>
BEA SALT currently supports Reliable Messaging for inbound services only. To enable Reliable Messaging functionality, you must create a Web Service Reliable Messaging policy file and include the policy file in the WSDF. The policy file must comply with the WS-ReliableMessaging Policy Assertion Specification (February 2005).
| Note: | A WSDF containing a Reliable Messaging policy definition should be used by the GWWS server for inbound direction only. |
A Reliable Messaging Policy file is a general WS-Policy file containing WS-ReliableMessaging Assertions. The WS-ReliableMessaging Assertion is an XML segment that describes features such as the version of the supported WS-ReliableMessage specification, the source endpoint’s retransmission interval, the destination endpoint’s acknowledge interval, and so on.
For more information about the WS-ReliableMessaging policy file format, see the BEA SALT WS-ReliableMessaging Policy Assertion Reference in the BEA SALT Reference Guide.
Listing 2-13 shows a Reliable Messaging policy file example.
<?xml version="1.0"?>
<wsp:Policy wsp:Name="ReliableSomeServicePolicy"
xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
xmlns:wsp=”http://schemas.xmlsoap.org/ws/2004/09/policy”
xmlns:beapolicy="http://www.bea.com/wsrm/policy">
<wsrm:RMAssertion>
<wsrm:InactivityTimeout Milliseconds="600000" />
<wsrm:AcknowledgementInterval Milliseconds="2000" />
<wsrm:BaseRetransmissionInterval Milliseconds="500"/>
<wsrm:ExponentialBackoff />
<beapolicy:Expires Expires="P1D" />
<beapolicy:QOS QOS=”ExactlyOnce InOrder" />
</wsrm:RMAssertion>
</wsp:Policy>
You must reference the WS-ReliableMessaging policy file at the <Servicegroup> level in the native WSDF file. The following segment of the WSDF file shows how to reference the WS-ReliableMessaging policy file.
<Definition ...><Policy location=”RMPolicy.xml” />
<WSBinding ...>
<Servicegroup ...><Service ... />
<Service ... />
...
</Servicegroup ...>
</WSBinding>
</Definition>
| Note: | Reliable Messaging in BEA SALT does not support process/system failure scenarios, which means SALT does not store the message in a persistent storage area. BEA SALT works in a direct mode with the SOAP client. Usually, system failure recovery requires business logic synchronization between the client and server. |
BEA SALT provides security support at both transport level and SOAP message level. The following topics explains how to configure security features for each level:
BEA SALT provides point-to-point security using SSL link-level security and supports HTTP basic authentication mechanism for both inbound and outbound service authentication.
To set up link-level security using SSL at inbound endpoints, you can simply specify the endpoint address with prefix “https://”. The GWWS server who uses this inbound endpoint creates SSL listen port and make SSL secured connections with Web Service Clients. SSL features need to specify certificates settings. For more information about certificate settings, see Configuring Certificates.
GWWS server automatically creates SSL secured connection to outbound endpoints that are published with URLs that having prefix “https://”.
BEA SALT depends on the Tuxedo security framework for Web Service client authentication. There is no special configuration at BEA SALT side to enable inbound HTTP Basic Authentication. If Tuxedo system requires user credential, HTTP Basic Authentication is simply an alternative for Web Service client program to carry the user credential.
The GWWS gateway supports Tuxedo domain security configuration for the following two authentication patterns:
The GWWS server passes the following string from the HTTP header of the client SOAP request for Tuxedo authentication.
Authorization: Basic <base64Binary of username:password>
The following is an example of a string from the HTTP header:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
In this example, the client sends the Tuxedo username “Aladdin” and the password “open sesame”, and uses this paired value for Tuxedo authentication.
If Tuxedo uses APP_PW, then the HTTP username value is ignored and the GWWS server only uses the password string as the Tuxedo application password to check the authentication.
If Tuxedo uses USER_AUTH, then both the HTTP username and password value are used. In this case, the GWWS server does not check the Tuxedo application password.
| Note: | ACL and MANDATORY_ACL are not supported for Web service clients, which means the Tuxedo system ignores any ACL-related configuration specifications. BEA SALT does not make group information available for Web service clients. |
BEA SALT supports customers to develop authentication plug-in to prepare the user credential for the outbound HTTP Basic Authentication. Outbound HTTP Basic Authentication is configured at Endpoint level. If an outbound Endpoint requires user profile in the HTTP message, you must specify the HTTP Realm for the HTTP endpoint in the WSDF file. The GWWS server invokes authentication plug-in library to prepare the username and password, and send them using HTTP Basic Authentication mechanism in the request message.
Listing 2-15 shows how to enable HTTP Basic Authentication for the outbound endpoints.
<Definition ...>
<WSBinding id="simpapp_binding">
<SOAP>
<AccessingPoints>
<Endpoint id=”...” address=”...”>
<Realm>SIMP_REALM</Realm>
</Endpoint>
</AccessingPoints>
</SOAP>
<Servicegroup id="simpapp">
....
</Servicegroup>
....
</WSBinding>
......
</Definition>
Once a service request is sending to an outbound endpoint specified with <Realm> setting, the GWWS server passes the Tuxedo client uid and gid to the authentication plug-in function, so that the plug-in can determine HTTP Basic Authentication username/password according to the Tuxedo client information. To obtain Tuxedo client uid / gid for HTTP basic authentication username/password mapping, Tuxedo security level may also need to be configured in the UBBCONFIG file. For more information, see Configuring Tuxedo Security Level for Outbound HTTP Basic Authentication.
For more information about how to develop an outbound authentication plug-in, see Programming Outbound Authentication Plug-ins in the BEA SALT Programming Web Services.
BEAL SALT supports Web Service Security 1.0 and 1.1 specification for message level security. You can use message-level security in BEA SALT to assure:
BEA SALT implementation of the Web Service Security: SOAP Message Security specification supports the following use cases:
BEA SALT includes a number of WS-Security Policy 1.0 and 1.2 files you can use for message level security use cases.
The WS-Policy files can be found at $TUXDIR/udataobj/salt/policy once you have successfully installed BEA SALT.
The following table lists the default WS-Security Policy files bundled by BEA SALT.
The above policy files except WS-Security Policy 1.2 UserToken file can be referenced at <Servicegroup> or <Service> level in the native WSDF file. The WSSP 1.2 UserToken file can only be referenced at <Servicegroup> level. The sample “wsseapp” shows how to clip the WSSP 1.2 UserToken file to be used in <Service> level.
Listing 2-16 shows a combination of policy assignment making that the service “TOUPPER” requires client send a UsernameToken (in PlainText format) and an X509v3Token in request, and also require the SOAP:Body part of message is signed with the X.509 token.
<Definition ...>
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Policy location="salt:wssp1.2-Wss1.1-X509V3-auth.xml"/>
<Service name="TOUPPER" >
<Policy location="D:/wsseapp/wssp1.2-UsernameToken-Plain.xml"/>
<Policy location="salt:wssp1.2-signbody.xml" use="input"/>
</Service>
</Servicegroup>
....
</WSBinding>
......
</Definition>
Policy is referred with “location” attribute of the <Policy> element. A prefix “salt:” means a SALT default bundled policy file is used. User-defined policy file can be used by directly specifying the file path.
| Notes: | If a policy is referred at <Servicegroup> level, it will apply to all services in this service group. |
The “signbody” policy must be used with the attribute “use” set as “input”, which specifies the policy applied only for input message. This is necessary because we do not sign the SOAP:Body of output message.
Compiling a SALT configuration file means generating a binary version of the file (SALTCONFIG) from the XML version SALTDEPLOY file. To compile a configuration file, run the wsloadcf command. wsloadcf parses a deployment file and loads the binary file.
wsloadcf reads a deployment file and all imported WSDF files and WS-Policy files referenced in the deployment file, checks the syntax according to the XML schema of each file format, and optionally loads a binary configuration file called SALTCONFIG. The SALTCONFIG and (optionally) SALTOFFSET environment variables point to the SALTCONFIG file and (optional) offset where the information should be stored.
wsloadcf validates the given SALT configuration files according to the predefined XML Schema files. XML Schema files needed by BEA SALT can be found at directory: $TUXDIR/udataobj/salt.
wsloadcf can execute for validating purpose only without generating the binary version SALTCONFIG once option “-n” is specified.
For more information about wsloadcf, see
wsloadcf reference in the BEA SALT Reference Guide.
After configuring and compiling SALT configuration, Tuxedo UBBCONFIG file needs to be updated to apply SALT components in the Tuxedo application. Table 2-9 lists the UBBCONFIG file configuration tasks for BEA SALT.
BEA SALT requires at least one TMMETADATA server defined in the UBBCONFIG file. Multiple TMMETADATA servers are also allowed to increase the throughput of accessing the Tuxedo service definitions.
Listing 2-17 lists a segment of the UBBCONFIG file that shows how to define TMMETADATA servers in a Tuxedo application.
......
*SERVERS
TMMETADATA SRVGRP=GROUP1 SRVID=1
CLOPT="-A -- – f domain_repository_file -r"
TMMETADATA SRVGRP=GROUP1 SRVID=2
CLOPT="-A -- – f domain_repository_file"
......
| Note: | Maintaining only one Service Metadata Repository file for the whole Tuxedo domain is highly recommended. To ensure this, multiple TMMETADATA servers running in the Tuxedo domain must point to the same repository file. |
For more information, see “ Managing The Tuxedo Service Metadata Repository” in the Tuxedo 9.1 documentation.
To boot GWWS instances defined in the SALTDEPLOY file, the GWWS servers must be defined in the *SERVERS section of the UBBCONFIG file. You can define one or more GWWS server instances concurrently in the UBBCONFIG file. Each GWWS server must be assigned with a unique instance id with the option “-i” within the Tuxedo domain. The instance id must be present in the XML version SALTDEPLOY file and the generated binary version SALTCONFIG file.
Listing 2-18 lists a segment of the UBBCONFIG file that shows how to define GWWS servers in a Tuxedo application.
......
*SERVERS
GWWS SRVGRP=GROUP1 SRVID=10
CLOPT="-A -- – i GW1"
GWWS SRVGRP=GROUP1 SRVID=11
CLOPT="-A -- – i GW2"
GWWS SRVGRP=GROUP2 SRVID=20
CLOPT="-A -- -c saltconf_2.xml – i GW3"
......
For more information, see “ GWWS” in the BEA SALT Reference Guide.
| Note: | Be sure that the TMMETADATA system server is set up in the UBBCONFIG file to start before the GWWS server boots. Because the GWWS server calls services provided by TMMETADATA, it must boot after TMMETADATA. |
| Note: | To ensure TMMETADATA is started prior to being called by the GWWS server, put TMMETADATA before GWWS in the UBBCONFIG file or use SEQUENCE parameters in *SERVERS definition in the UBBCONFIG file. |
| Note: | SALT configuration information is pre-compiled with wsloadcf to generated a binary version SALTCONFIG file. GWWS server reads SALTCONFIG file at start up. Environment variable SALTCONFIG must be set correctly with the binary version SALTCONFIG file entity before booting GWWS servers. |
| Note: | Option “-c” is deprecated in the current version BEA SALT. In SALT 1.1 release, option “-c” is used to specify SALT 1.1 configuration file for the GWWS server. In SALT 2.0, GWWS server reads SALTCONFIG file at start up. GWWS server specified with this option can be booted with a warning message to indicate this deprecation. The specified file can be arbitrary and is not read by the GWWS server. |
When configuring the Tuxedo domain with SALT GWWS servers, you need to plan and update Tuxedo system limitations defined in the UBBCONFIG file according to your SALT application requirements.
| Tip: | Defining enough MAXSERVERS number in the *RESOURCES section |
BEA SALT requires the following system servers to be started in a Tuxedo domain: TMMETADATA and GWWS. The number of TMMETADATA and GWWS server must be accounted for in the MAXSERVERS value.
| Tip: | Defining enough MAXSERVICES number in the *RESOURCES section |
When the GWWS server working in the outbound direction, external wsdl:operations are mapped with Tuxedo services and advertised via the GWWS servers. The number of the advertised services by all GWWS servers must be accounted for in the MAXSERVICES value.
| Tip: | Defining enough MAXACCESSERS number in the *RESOURCES section |
MAXACCESSERS value is used to specify the default maximum number of clients and servers that can be simultaneously connected to the Tuxedo bulletin board on any particular machine in this application. The number of TMMETADATA and GWWS server, maximum concurrent Web Service client requests must be accounted for in the MAXACCESSERS value.
| Tip: | Defining enough MAXWSCLIENTS number in the *MACHINES section |
When the GWWS server working in the inbound direction, each Web Service client is deemed a workstation client in Tuxedo system; therefore, MAXWSCLIENTS must be configured with a valid number in UBBCONFIG for the machine where the GWWS server is deployed. The number shares.
Configuring security password phrase is required when setting up certificates for BEA SALT. Certificates setting is desired when the GWWS servers enabling SSL link-level encryption and/or Web Service Security X.509 Token and signature features. The certificate private key file needs to be created and encrypted with a password phrase.
When the GWWS servers are specified with certificate related features, they are required to read the private key file and decrypt them using the password phrase. To configure password phrase for each GWWS server, keyword SEC_PRINCIPAL_NAME and SEC_PRINCIPAL_PASSVAR must be specified under each desired GWWS server entry in the *SERVERS section. During compiling the UBBCONFIG file with tmloadcf, the administrator must type the password phrase, which can be used to decrypt the private key file correctly.
| Note: | Only one private key file can be specified in the SALT deployment file. All the GWWS servers defined in the SALT deployment file must be provided the same password phrase for the private key file decryption. |
Listing 2-19 lists a segment of the UBBCONFIG file that shows how to define security password phrase for the GWWS servers.
......
*SERVERS
GWWS SRVGRP=GROUP1 SRVID=10
SEC_PRINCIPAL_NAME="gwws_certkey"
SEC_PRINCIPAL_VAR="gwws_certkey"
CLOPT="-A -- – i GW1"
GWWS SRVGRP=GROUP1 SRVID=11
SEC_PRINCIPAL_NAME="gwws_certkey"
SEC_PRINCIPAL_PASSVAR="gwws_certkey"
CLOPT="-A -- – i GW2"
......
For more information, see “
UBBCONFIG(5)“in the Tuxedo 9.1 documentation.
BEA SALT GWWS servers rely on Tuxedo authentication framework to check the validity of the Web Service clients. If your legacy Tuxedo application is already applied with, Web Service clients must send user credential using one of the following approaches:
Contrarily, if you want to authenticate Web Service clients for BEA SALT, you must configure Tuxedo authentications in the Tuxedo domain.
For more information about Tuxedo authentication, see “Administering Authentication” in the BEA Tuxedo 9.1 Documentation.
To obtain Tuxedo client uid / gid for outbound HTTP Basic Authentication username /password mapping, you need to configure Tuxedo Security level as USER_AUTH, ACL or MANDATORY_ACL in the UBBCONFIG file.
Listing 2-20 lists a segment of the UBBCONFIG file that shows how to define security level ACL in the UBBCONFIG file.
*RESOURCES
IPCKEY ...
......
SECURITY ACL
......
To set up GWWS servers running on multiple machines within a MP mode Tuxedo domain, each Tuxedo machine must be defined with a separate SALTDEPLOY file and a set of separate other components.
You must propagate the following global resources across different machines:
SALTDEPLOY file.SALTDEPLOY file.
You may define two GWWS servers running on different machine with the same functionality by associating the same WSDF files. But it requires manual propagation of the following artifacts:
This section describes the following two possible migrating approaches for SALT 1.1 customers who plan to upgrade to SALT 2.0 release:
After upgrading from SALT 1.1 to SALT 2.0 release, you may still want to run your existing SALT applications with the original SALT 1.1 configuration file. SALT 2.0 definitely supports that.
SALT configuration compiler utility, wsloadcf, supports to load the binary version SALTCONFIG from one SALT 1.1 format configuration file.
To run SALT 2.0 GWWS servers with SALT 1.1 Configuration file, you need to perform the following steps:
| Note: | If customers have more than one SALT 1.1 configuration files defined in a Tuxedo domain, customers need to follow step 1 to 3 to generate more binary version SALTCONFIG files and boot corresponding GWWS servers. |
When wsloadcf loads a binary version SALTCONFIG from a SALT 1.1 configuration file, it also convert this SALT 1.1 configuration file into one WSDF file and one SALTDEPLOY file.
It’s highly recommended to start using the SALT 2.0 styled configuration once you get the converted files from SALT 1.1 configuration.
| Note: | If customers want to incorporate more than one SALT 1.1 configuration files into one SALT 2.0 deployment, customers need to manually edit the SATLDEPLOY file for importing the other WSDF files. |
The following sample lists the converted SALTDEPLOY file and WSDF file from a given SALT 1.1 configuration file.
<Configuration xmlns=" http://www.bea.com/Tuxedo/Salt/200606">
<Servicelist id="simpapp">
<Service name="toupper" />
<Service name="tolower" />
</Servicelist>
<Policy />
<System />
<WSGateway>
<GWInstance id="GWWS1">
<HTTP address="//127.0.0.1:7805" />
<HTTPS address="127.0.0.1:7806" />
<Property name="timeout" value="300" />
</GWInstance>
</WSGateway>
</Configuration>
The converted SALT 2.0 WSDF file and deployment file are listed below.
<Definition name="simpapp" wsdlNamespace="urn:simpapp.wsdl"
xmlns=" http://www.bea.com/Tuxedo/WSDF/2007">
<WSBinding id="simpapp_binding">
<Servicegroup id="simpapp">
<Service name="toupper" />
<Service name="tolower" />
</Servicegroup>
<SOAP>
<AccessingPoints>
<Endpoint id="simpapp_GWWS1_HTTPPort"
address=http://127.0.0.1:7805/simpapp />
<Endpoint id=" simpapp_GWWS1_HTTPSPort"
address=https://127.0.0.1:7806/simpapp />
</AccessingPoints>
</SOAP>
</WSBinding>
</Definition>
<Deployment xmlns=" http://www.bea.com/Tuxedo/SALTDEPLOY/2007">
<WSDF>
<Import location="/home/myapp/simpapp.wsdf" />
</ WSDF>
<WSGateway>
<GWInstance id="GWWS1">
<Inbound>
<Binding ref="simpapp:simpapp_binding">
<Endpoint use=" simpapp_GWWS1_HTTPPort" />
<Endpoint use=" simpapp_GWWS1_HTTPSPort" />
</Binding>
</Inbound>
<Properties>
<Property name="timeout" value="300" />
</Properties>
</GWInstance>
</WSGateway>
</ Deployment>
|