Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with JMS

Software AG Products 10.5 | Administering Integration Server | Configuring Endpoint Aliases for Web Services | Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with JMS

Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with JMS

A web service endpoint alias for use with a consumer web service descriptor that has a JMS binder specifies how and where Integration Server sends a request message when executing a web service descriptor.

When creating a consumer web service descriptor, Integration Server extracts the JMS information from the WSDL document and saves it with the binder information in the web service descriptor. However, as indicated in the SOAP over Java Message Service standard, the only JMS information required in the WSDL is the lookup variant and the destination name. Consequently, it is possible that some information necessary to connect to the JMS provider is absent from the WSDL. Integration Server uses the information in a JMS consumer web service endpoint alias to replace or supplement the JMS information specified in the WSDL document.

When creating a consumer web service descriptor, the message addressing properties define the WS-addressing headers information that can be attached to the SOAP message.

Keep the following points in mind when creating a web service endpoint alias for use with a consumer web service descriptor with a SOAP over JMS binding:

A JMS consumer web service endpoint alias can specify one of the following options to connect to a JMS provider:

JNDI provider alias and a connection factory.

JMS connection alias.

Only specify a JNDI provider alias and connection factory, or JMS connection alias, if information for connecting to the JMS provider was not included in the WSDL document used to create the consumer web service descriptor or if you want to overwrite the connection information included in the WSDL document.

Note:
Using a JMS connection alias to connect to the JMS provider might offer better performance. Keep in mind that a JMS connection alias can connect to the JMS provider by using JNDI to retrieve a connection factory and then establishing a connection or by connecting natively to the webMethods Broker.

If you want to use the client side queue with the web service descriptor to which the alias is assigned, you must specify a JMS connection alias as the way to connect to the JMS provider.

Information in the JMS consumer web service endpoint alias can supplement or replace the JMS URI information obtained from a WSDL.

You can use the endpoint alias to provide information for the WS-Security header as determined by the security policy for the web service. A web service security policy can require that:

SOAP message requests include a UserName token.

SOAP message response be decrypted.

SOAP message requests to be signed.

X.509 authentication.

A Timestamp element be added to the security header.

Note:
WS-Security credentials such as private keys and public keys do not always need to be provided in a web service endpoint alias. If this information is not provided in the alias, Integration Server can obtain the information from other locations. For more information about usage and resolution order of certificates and keys for WS-Security, see the Web Services Developer’s Guide .

To create a consumer web service endpoint alias for use with JMS

1. Open Integration Server Administrator if it is not already open.

2. In the Navigation panel, select Settings > Web Services.

3. Click Create Web Service Endpoint Alias.

4. Under Web Service Endpoint Alias Properties, provide the following information:

In this field	Specify
Alias	A name for the JMS consumer web service endpoint alias. The alias name cannot include the following illegal characters: # ©\ & @ ^ ! % * : $ . / \ \ ` ; , ~ + = ) ( \| } { ] [ > < "
Description	A description for the endpoint alias.
Type	Consumer
Transport Type	JMS
Execute ACL	ACL that governs which user groups on your server can use this web service endpoint alias. Select an ACL from the drop down list. By default, only members of groups governed by the Internal ACL can use this alias.

5. Under JMS Transport Properties, do the following if you want to connect to the JMS provider using a connection factory:

In this field	Specify
Connect Using	JNDI Properties
JNDI Provider Alias	The alias for the JNDI provider that Integration Server uses to look up administered objects. For information about creating a JNDI provider alias, see Creating a JNDI Provider Alias.
Connection Factory Name	The lookup name for the connection factory to use to create a connection to the JMS provider. Note: You need to specify a connection factory only if the WSDL document used to create the consumer web service descriptor did not specify a connection factory or you want to overwrite the connection factory.

6. Under JMS Transport Properties, do the following if you want to connect to the JMS provider using a JMS connection alias:

In this field	Specify
Connect Using	JMS Connection Alias
JMS Connection Alias	The name of the JMS connection alias that you want Integration Server to use to connect to the JMS provider. For information about creating a JMS connection alias, see Creating a JMS Connection Alias.

7. Under WS Security Properties, provide the following information if the WS-Security policy for this consumer web service descriptor requires that SOAP message requests include a UsernameToken.

In this field	Specify
User Name	The user name to include with the UsernameToken.
Password	The password to include with the UsernameToken (must be plain text).
Retype Password	Re-enter the above password.

8. If the security policy (or policies) that will be used by this web service requires its requests to be signed, requires an X.509 authentication token to be included, or requires that SOAP message responses be encrypted, specify the following:

In this field	Specify
Keystore Alias	Alias to the keystore that contains the private key used to: Sign outbound SOAP requests Include an X.509 authentication token for outbound SOAP requests Decrypt inbound SOAP responses Important: To verify messages from this consumer, the web services provider must have a copy of the corresponding public key.
Key Alias	Alias to the private key used to sign and/or include X.509 authentication token for outbound SOAP messages and/or decrypt inbound SOAP responses. The key must be in the keystore specified in Keystore Alias.

9. Under WS Security Properties, specify the provider's certificate file. This certificate is used to encrypt the outbound SOAP request and/or verify the inbound SOAP response.

In this field	Specify
Partner's Certificate	The path and file name of the provider's certificate, which contains its public key.

10. Under WS Security Properties, if the security policy (or policies) that will be used by this web services consumer requires that responses be verified by a trusted authority, specify the following:

In this field	Specify
Partner's Certificate	Path and file name of the file containing the provider's certificate.
Truststore Alias	The alias for the truststore that contains the list of CA certificates that Integration Server uses to validate the trust relationship.

11. Under WS Security Properties, configure how Integration Server handles timestamps in the security headers.

In this field	Specify
Timestamp Precision	Whether the timestamp is precise to the second or millisecond. If you set the precision to milliseconds, Integration Server uses the timestamp format yyyy-MM-dd'T'HH:mm:ss:SSS'Z'. If you set the precision to seconds, Integration Server uses the timestamp format yyyy-MM-dd'T'HH:mm:ss'Z'. If you do not select a precision value, Integration Server will use the value specified for the watt.server.ws.security.timestampPrecisionInMilliseconds parameter.
Timestamp Time to Live	The time-to-live value for the outbound message in seconds. Integration Server uses the Timestamp Time to Live value to set the expiry time in the Timestamp element of outbound messages. The Timestamp Time to Live value must be an integer greater than 0. If you do not specify a time-to-live value, Integration Server will use the value specified for the watt.server.ws.security.timestampTimeToLive parameter.
Timestamp Maximum Skew	The maximum number of seconds that the web services client and host clocks can differ and still allow timestamp expiry validation to succeed. Specify a positive integer or zero. Integration Server uses the timestamp maximum skew value only when you implement WS-Security via a WS-Policy. Integration Server validates the inbound SOAP message only when the creation timestamp of the message is less than the sum of the timestamp maximum skew value and the current system clock time. If you do not specify a timestamp maximum skew value, Integration Server will use the value specified for the watt.server.ws.security.timestampMaximumSkew parameter.

For more information about timestamps in the WS-Security header, see Timestamps in the WS-Security Header.

12. Under Message Addressing Properties, provide the following addressing information relating to the delivery of a message to a web service.

In this field	Specify
Must Understand	Whether the recipients (the actor or role to which the header is targeted) are required to process the WS-Addressing headers. Recipients that cannot process a mandatory WS-Addressing header reject the message and return a SOAP fault. Must Understand determines the mustUnderstand attribute of the WS-Addressing headers.
	Select	To
	True	Indicate that processing the WS-Addressing headers is required by the recipients (the actor or role to which the header is targeted). If you select True for Must Understand and the SOAP node receives a header that it does not understand or cannot process, it returns a fault.
	False	Indicate that processing the WS-Addressing headers is optional. This is the default.
	Note: In SOAP 1.1, the values of the mustUnderstand attribute were 0 and 1 instead of True and False; however, Integration Server processes both sets of values the same and performs any necessary conversions. For more information about the mustUnderstand and actor attributes in SOAP 1.1, see the Simple Object Access Protocol (SOAP) 1.1 - W3C Note 08 May 2000 . For more information about the mustUnderstand and role attributes in SOAP 1.2, see the Simple Object Access Protocol (SOAP) 1.2 specification.
Role	Target of the WS-Addressing headers in the SOAP message. Role determines the value of the role attribute for the WS-Addressing headers. The actor or role attribute specifies a URI for the recipient of WS-Addressing header entries. Note: In SOAP 1.1, the role attribute is named actor; however, Integration Server processes both names the same and performs any necessary conversions.
	Select	To
	Ultimate Receiver	Indicate that the recipient is the ultimate destination of the SOAP message. This is the default.
	Next	Specify the following URI for the role attribute: For SOAP 1.2: "http://www.w3.org/2003/05/soap-envelope/role/next" For SOAP 1.1: "http://schemas.xmlsoap.org/soap/actor/next"
	None	Specify the following URI for the role attribute: For SOAP 1.2: "http://www.w3.org/2003/05/soap-envelope/role/none" For SOAP 1.1: "http://www.w3.org/2003/05/soap-envelope/role/none"
	Other	Specify the target of the header. Typically, this will be a URI.
To	URI of the destination of the SOAP request. In the Reference Parameters field, specify additional parameters, if any, that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the request is addressed. You can specify more than one reference parameter. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.
From	URI of the source of the SOAP message. In the Reference Parameters field, specify additional parameters, if any, that correspond to <wsa:ReferenceParameters> properties of the endpoint reference. Optionally, you can specify metadata (such as WSDL or WS-Policy) about the service in the Metadata Elements field. You can also specify Extensible Elements, which are elements other than those specified as part of the Metadata and Reference Parameters. You can specify more than one reference parameter, metadata element, or extensible element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.
ReplyTo	URI to which the response (reply) messages are to be routed. This property is optional. If this value is not specified, the default values for this URI depends on the WS-Addressing policy attached to the web service descriptor. For the Final version of WS-Addressing, ReplyTo defaults to http://www.w3.org/2005/08/addressing/anonymous. For the Submission version of WS-Addressing, ReplyTo defaults to http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous. In the Reference Parameters field, specify additional parameters, if any, that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the response message is addressed. Optionally, you can specify metadata (such as WSDL or WS-Policy) about the service in the Metadata Elements field. You can also specify Extensible Elements, which are elements other than those specified as part of the Metadata and Reference Parameters. You can specify more than one reference parameter, metadata element, or extensible element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.
FaultTo	URI to which the SOAP fault messages are to be routed. This property is optional. In the Reference Parameters field, specify additional parameters, if any, that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the fault message is addressed. Optionally, you can specify metadata (such as WSDL or WS-Policy) about the service in the Metadata Elements field. You can also specify Extensible Elements, which are elements other than those specified as part of the Metadata and Reference Parameters. You can specify more than one reference parameter, metadata element, or extensible element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows. You can specify more than one reference parameter, metadata element, or extensible element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.

13. Click Save Changes.