Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with HTTP/S

Software AG Products 10.7 | Administering Integration Server | Configuring Endpoint Aliases for Web Services | Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with HTTP/S

Creating an Endpoint Alias for a Consumer Web Service Descriptor for Use with HTTP/S

When you create an HTTP/S web service endpoint alias for use with consumer web service descriptors, you need to supply information that falls into the following categories:

Web Service Endpoint Alias. Endpoint name, description, and transport type.

HTTP/S Transport Properties.Optional. The host and port used to build the endpoint URL. If the web service provider requires transport-based authentication, these properties specify the authentication credentials to be added to the HTTP/S header. For HTTPS transport, these properties specify the keystore alias and key alias of the private key used for SSL communication with the web service provider. If the web service request must be routed through a proxy server, these properties specify the proxy server alias for the proxy server through which Integration Server routes the HTTP/S request.

WS Security Properties. 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 responses be decrypted.

SOAP message requests be signed.

X.509 authentication be supported.

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.

Message Addressing Properties. Addressing information about the response delivery. This information includes the reply endpoint where the replies should be sent, the fault endpoint that specifies where the faults should be sent, and optional metadata (such as WSDL or WS-Policy) about the service. This also includes additional parameters, called Reference Parameters, that Integration Server uses to route the message to the destination.

Reliable Messaging Properties. Provides reliable messaging information specific to the web service endpoint. By default, Integration Server applies the reliable messaging configuration defined on the Settings > Web Services > Reliable Messaging > Edit Configuration page to all web service providers and consumers. If you want to override the server-level reliable messaging configuration for a specific web service provider or consumer, define reliable messaging properties for the associated web service endpoint alias.

To create a consumer web service endpoint alias for use with HTTP/S

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

2. Go to 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 provider web service endpoint alias. The alias name cannot include the following illegal characters: # ©\ & @ ^ ! % * : $ . / \ \ ` ; , ~ + = ) ( \| } { ] [ > < "
Description	A description for the endpoint alias.
Type	Consumer
Transport Type	Specify the transport protocol used to access the web service. Select one of the following: HTTP HTTPS
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. Integration Server performs the ACL check only if the specific endpoint alias is used as the value of the endpointAlias input parameter in a web service connector or the pub.client:soapClient service. Integration Server does not perform the ACL check when the consumer web service endpoint alias is assigned to a binder used by the web service connector.

5. Under TransportType Transport Properties, provide the following information if you want to overwrite the host and/or port information in the WSDL with the host and/or port information in the web service endpoint alias. For more information about how Integration Server builds the endpoint URL, see webMethods Service Development Help.

In this field	Specify
Host Name or IP Address	Host name or IP address of the server on which the web service resides.
Port Number	An active HTTP or HTTPS type listener port defined on the host server specified in the Host Name or IP Address field.
Authentication Type	Specify the type of authentication you want to use to authenticate the consumer.
	Select...	To...
	Basic	Use basic authentication (user name and password) to authenticate the consumer.
	Digest	Use password digest to authenticate the consumer.
	NTLM	Use NTLM authentication so that clients that are already logged into a domain can be authenticated using their existing credentials.
	Kerberos	Use Kerberos authentication for the web service at the transport level. When you select this option an additional section Kerberos Transport Properties is added to this page.

6. If you are configuring the web service endpoint for transport-based authentication such as HTTPS, specify all or a combination of the following optional fields:

In this field	Specify
User Name	User name used to authenticate the consumer at the HTTP or HTTPS transport level on the host server.
Password	The password used to authenticate the consumer on the host server.
Retype Password	Re-enter the above password.
Keystore Alias	Alias to the keystore that contains the private key used to connect to the web service host securely. This field applies to the HTTPS transport type only.
Key Alias	Alias to the key in the keystore that contains the private key used to connect to the web service host securely. The key must be in the keystore specified in Keystore Alias. This field applies to the HTTPS transport type only.

7. If web service requests must be sent through a proxy server, in the Proxy Alias field, do one of the following to specify which proxy server Integration Server uses:

If you want Integration Server to use a particular proxy server, select the alias for that proxy server. Integration Server lists all the configured HTTP/S and SOCKS proxy aliases in the Proxy Alias field.

If you want Integration Server to use the default proxy server, leave this field blank.

For more information about how Integration Server uses proxy servers when sending requests, see How Integration Server Uses Proxy Servers.

8. The Kerberos Transport Properties section enables you to configure Kerberos authentication at the transport-level. You can provide Kerberos-related details that will be used for all web service requests by providers that use this endpoint alias.

Note:
Kerberos authentication is available at the transport level or message level for HTTPS, but only at the transport level for HTTP.

The following fields are available for consumer endpoint aliases when you select Kerberos as the HTTP transport Authentication Type.

Field	Description
JAAS Context	Specify the custom JAAS context used for Kerberos authentication. In the following example, JAAS Context is KerberosClient: KerberosClient { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab=alice.keytab; };
Principal	Specify the name of the principal to use for Kerberos authentication.
Principal Password	Specify the password for the principal that is used to authenticate the principal to the KDC. Specify the principal password if you do not want to use the keytab file that contains the principals and their passwords for authorization. The passwords may be encrypted using different encryption algorithms. If the JAAS login context contains useKeyTab=false, you must specify the principal password.
Retype Principal Password	Re-enter the above principal password.
Service Principal Name Format	Select the format in which you want to specify the principal name of the service that is registered with the principal database.
	Select...	To...
	host-based	Represent the principal name using the service name and the host name, where host name is the host computer. Note: Currently, this option is disabled. Integration Server supports only username.
	username	Represent the principal name as a named user defined in the LDAP or central user directory used for authentication to the KDC.
Service Principal Name	Specify the service that the Kerberos client wants to access. This can be obtained from the WSDL document published by the provider of Kerberos service. Specify the Service Principal Name in the following format: principal-name.instance-name@realm-name

9. 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, enter values for the following fields:

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.

10. 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.

11. 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.

12. Under WS Security Properties, if the security policy (or policies) that will be used by this web services consumer requires that responses be validated 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.

13. 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.
Username Token TTL	This is the permitted time difference, in seconds, between the time when the UsernameToken was created (as provided in the wsu:Created element) and the time when it reaches the server. Requests that exceed this limit are rejected by the server. The default value is 300.
Username Token Future TTL	It is possible that the wsu:Created element has a timestamp that is in the future. The server considers such requests as valid If the time at which the request was created does not exceed the time at which it reaches the server by the value (in seconds) given in this setting. The default value is 60.

Note:
The Username Token TTL and Username Token Future TTL configurations can also be set at the global level using the watt.server.ws.security.usernameTokenTTL and the watt.server.ws.security.usernameTokenFutureTTL server configuration properties. However, if there is a configuration setting at the web services endpoint level, the server will ignore the global property. For more information about the global properties, see watt.server..

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

14. Under Kerberos Properties, provide the following Kerberos-related details that will be used for all web service requests that use this endpoint alias.

Note:
These fields are available only for consumer endpoint aliases using HTTPS transport type.

In this field	Specify
JAAS Context	The custom JAAS context used for Kerberos authentication. In the following example, JAAS Context is KerberosClient: KerberosClient { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true keyTab=alice.keytab; }; The is_jaas.cnf file distributed with Integration Server includes a JAAS context named IS_KERBEROS_OUTBOUND that can be used with inbound requests.
Principal	The name of the principal to use for Kerberos authentication.
Principal Password	The password for the principal that is used to authenticate the principal to the KDC. Specify the principal password if you do not want to use the keytab file that contains the principals and their passwords for authorization. The passwords may be encrypted using different encryption algorithms. If the JAAS login context contains useKeyTab=false, you must specify the principal password.
Retype Principal Password	The above principal password.
Service Principal Name Format	Select the format in which you want to specify the principal name of the service that is registered with the principal database.
	Select	To
	host-based	Represent the principal name using the service name and the hostname, where hostname is the host computer. This is the default.
	username	Represent the principal name as a named user defined in the LDAP or central user directory used for authentication to the KDC.
Service Principal Name	The name of the principal for the service that the Kerberos client wants to access. This can be obtained from the WSDL document published by the provider of the Kerberos service. Specify the Service Principal Name in the following format: principal-name.instance-name@realm-name

15. Under Message Addressing Properties, provide the following addressing information relating to the delivery of a message to a web service. The message addressing properties define the addressing information that can be attached to the SOAP message.

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. 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 way 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 specification. 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 message. 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. Enter the URI in the Address field. Optionally, in the Reference Parameters field, specify any additional parameters that are necessary to route the message to the destination. You can also specify optional metadata (such as WSDL or WS-Policy) about the service in the Metadata Elements field. You can specify more than one reference parameter and metadata element. Click the ‘+’ icon to add more rows and the ‘x’ icon to delete the rows.
ReplyTo	URI of the destination to which the web service sends a response (reply) message. 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 a consumer endpoint alias, it defaults to: http://www.w3.org/2005/08/addressing/anonymous for Final version of WS-Addressing. http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous for Submission version of WS-Addressing. 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.

16. Under Reliable Messaging Properties, check Enable to provide reliable messaging information specific to the endpoint alias you are creating.

17. Provide the following reliable-messaging information to ensure reliable delivery of the message between a reliable messaging source and destination.

In this field	Specify
Retransmission Interval	The time interval (in milliseconds) for which a reliable messaging source waits for an acknowledgement from the reliable messaging destination before retransmitting the SOAP message. The default is 6000 milliseconds.
Acknowledgement Interval	The time interval (in milliseconds) for which the reliable messaging destination waits before sending an acknowledgement for a message sequence. Messages of the same sequence received within the specified acknowledgement interval are acknowledged in one batch. If there are no other messages to be sent to the acknowledgement endpoint within the time specified as the acknowledgement interval, the acknowledgement is sent as a stand-alone message. The default is 3000 milliseconds.
Exponential Backoff	Whether to use the exponential backoff algorithm to adjust the retransmission interval of unacknowledged messages. Adjusting the time interval between retransmission attempts ensures that a reliable messaging destination does not get flooded with a large number of retransmitted messages.
	Select	To
	true	Increase the successive retransmission intervals exponentially, based on the specified retransmission interval. For example, if the specified retransmission interval is 2 seconds, and the exponential backoff value is set to true, successive retransmission intervals will be 2, 4, 8, 16, 32, and so on if messages continue to be unacknowledged. This is the default.
	false	Use the same time interval specified in the Retransmission Interval field for all retransmissions.
Maximum Retransmission Count	The number of times the reliable messaging source must retransmit a message if an acknowledgement is not received from the reliable messaging destination. To specify that there is no limit to the number of retransmission attempts, set the value of Maximum Retransmission Count to -1. The default is 10.

18. Click Save Changes.