How to Configure a WCF-WebHttp Send Port
Collapse the table of content
Expand the table of content

How to Configure a WCF-WebHttp Send Port

 

This section provides information on how to configure an WCF-WebHttp send port using the BizTalk Server Administration Console.

To configure a WCF-WebHttp send port

  1. In the BizTalk Administration console, create a new send port or double-click an existing send port to modify it. For more information, see How to Create a Send Port. Configure all of the send port options and specify WCF-WebHttp for the Type option in the Transport section of the General tab.

  2. On the General tab, in the Transport section, click the Configure button.

  3. In the WCF-WebHttp Transport Properties dialog box, on the General tab, configure the endpoint address for the REST interface where the message is sent.

    Use this

    To do this

    Address (URI)

    Required. Specify the URI for the REST interface where the message is sent.

    Endpoint Identity

    Optional. Specify the endpoint identity. These settings enable the endpoint to authenticate this send port. In the handshake process between the endpoint and the receive location, the Windows Communication Foundation (WCF) infrastructure will ensure that the identity of the expected service matches the values of this element.

    The default is an empty string.

    HTTP Method and URL Mapping

    BTS Operation Mapping allows users to map incoming HTTP requests to BTS Operation in the message context, based on the incoming HTTP Method and the URL sub-path. The incoming HTTP Method and the URL sub-path are matched against a set of HTTP method and the URI Template. If a match is found, the adapter promotes the BTS.Operation property to the BizTalk Message Context with the value specified in the message.

    You can specify HTTP method to URL mapping as a singular format or a multi-mapping format. The multi-mapping format resembles the following:

    <BtsHttpUrlMapping>
    <Operation Name = "DelCust" Method="DELETE" Url="/Customer/12345" />
    </BtsHttpUrlMapping>
    

    In the above snippet, notice that the customer ID is provided as a constant value, which is 12345. However, there could be scenarios when the customer ID, or any other query variable, must be determined at runtime. To enable such scenarios, you must provide the variable component of the URL within curly brackets { }. For example, in the above snippet, if you specify the customer ID as a variable, it would look like:

    <BtsHttpUrlMapping>
    <Operation Name = "DelCust" Method="DELETE" Url="/Customer/{ID}" />
    </BtsHttpUrlMapping>
    

    In such a case, you must also specify where the value for the variable ID must be picked from at runtime. You specify that using Variable Mapping.

    Variable Mapping

    If you specified variables for the HTTP Method URL Mapping, you must specify what the variable maps to at runtime. Click the Edit button to launch the Variable Mapping dialog box. Under the Variable column, the dialog box lists the variables that you defined for HTTP Method and URL Mapping. In the Property Name field you must specify the name of the property that provides the value to be associated to the variable. You must have already defined/promoted this property as part of your solution. You must also provide the namespace for the property in the Property Namespace field.

  4. In the WCF-WebHttp Transport Properties dialog box, on the Binding tab, configure the time-out and encoding-related properties.

    Use this

    To do this

    Open timeout (hh:mmss)

    Specify a time span value that indicates the interval of time provided for a channel open operation to complete. This value should be greater than or equal to System.TimeSpan.Zero.

    Default value: 00:01:00

    Maximum value: 23:59:59

    Send timeout (hh:mmss)

    Specify a time span value that indicates the interval of time provided for a send operation to complete. This value should be greater than or equal to System.TimeSpan.Zero. If you use a request-response receive port, this value specifies a time span for the whole interaction to complete, even if the client returns a large message.

    Default value: 00:01:00

    Maximum value: 23:59:59

    Close timeout (hh:mmss)

    Specify a time span value that indicates the interval of time provided for a channel close operation to complete. This value should be greater than or equal to System.TimeSpan.Zero.

    Default value: 00:01:00

    Maximum value: 23:59:59

    Maximum received message size (bytes)

    Specify the maximum size, in bytes, for a message including headers, which can be received on the wire. The size of the messages is bounded by the amount of memory allocated for each message. You can use this property to limit exposure to denial of service (DoS) attacks.

    The WCF-WebHttp adapter leverages the WebHttpBinding class in the buffered transfer mode to communicate with an endpoint. For the buffered transport mode, the WebHttpBinding.MaxBufferSize property is always equal to the value of this property.

    Default value: 65536

    Maximum value: 2147483647

  5. In the WCF-WebHttp Transport Properties dialog box, on the Security tab, define the security capabilities of the WCF-WebHttp send port.

    Use this

    To do this

    Security mode

    Specify the type of security that is used. Valid values include the following:

    • None: Messages are not secured during transfer.

    • Transport: Security is provided using the HTTPS transport. The SOAP messages are secured using HTTPS. The CA certificate chain for the service's X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the service can be authenticated to the send port using the service's certificate.

    • TransportWithMessageCredential: Integrity, confidentiality, and service authentication are provided by the HTTPS transport. The CA certificate chain for the service's X.509 certificate must be installed in the Trusted Root Certification Authorities certificate store on this computer so that the service can be authenticated to the send port using the service's certificate. The send port authentication is provided by SOAP message security.

    The default is None.

    Transport client credential type

    Specify the type of credential to be used when performing the client authentication. Valid values include the following:

    • None: No authentication occurs at the transport level.

    • Basic: Basic authentication. In Basic authentication, user names and passwords are sent in plain text over the network. You must create the domain or local user accounts corresponding to the credentials.

    • Digest: Digest authentication. This authentication method operates much like Basic authentication, except that passwords are sent across the network as a hash value for additional security. Digest authentication is available only on domains with domain controllers running Windows Server operating systems authentication. You must create the domain or local user accounts corresponding to client credentials.

    • Ntlm: NTLM authentication. Clients can send the credentials without sending a password to this receive location. You must create the domain or local user accounts corresponding to client credentials.

    • Windows: Windows integrated authentication. Windows Communication Foundation negotiates Kerberos or NTLM, preferring Kerberos if a domain is present. If you want to use Kerberos it is important to have the client identify the service with a service principal name (SPN). You must create the domain or local user accounts corresponding to client credentials.

    • Certificate: Client authentication using the client certificate. The CA certificate chain for the client X.509 certificates must be installed in the Trusted Root Certification Authorities certificate store of this computer so that the clients can be authenticated to this receive location.

    System_CAPS_noteNote

    The Transport client credential type property must match the authentication scheme of the IIS virtual directory hosting this receive location. For example, if the property is set to Windows, you also need to enable Integrated Windows authentication for the virtual directory that hosts it. Similarly if the property is set to None, you must allow anonymous access to the virtual directory that hosts this receive location.

    The default is Windows.

    Client certificate -  Thumbprint

    Specify the thumbprint of the X.509 certificate for authenticating this send port to the endpoint. You can select the thumbprint by navigating to the My store in the Current User location with the Browse button.

    System_CAPS_noteNote

    You must install the client certificate into the Current User location of the user account for the send handler hosting this send port.

    Minimum length: 0

    Maximum length: 40

    The default is an empty string.

    Service certificate - Thumbprint

    Specify the thumbprint of the X.509 certificate for authenticating the endpoint to which this send port sends messages. You can select the thumbprint navigating to the Other People store in the Local Machine location with the Browse button.

    Minimum length: 0

    Maximum length: 40

    The default is an empty string.

    User name credentials

    Specify the credentials for sending messages. You can specify the property by clicking the Edit button. You must set the credentials if you selected the Username option for Message client credential type.

    The default value is Do not use Single Sign-On.

    Use ACS service identity

    Select this checkbox and click Edit and provide the following values to authenticate with the Service Bus. This is required only when invoking a REST interface for Service Bus related entities.

    • Access Control Service STS Uri – Set this to https://<Namespace>-sb.accesscontrol.windows.net/, where <namespace> is your Service Bus namespace.

    • Issuer Name – Specify the issuer name. Typically this is set to owner.

    • Issuer Key – Specify the issuer key.

  6. In the WCF-WebHttp Transport Properties dialog box, on the Behaviors tab, configure the endpoint behavior for this send port. This is similar to the endpoint behavior configuration for a WCF-Custom send port. For more information, see http://msdn.microsoft.com/library/bb246084

  7. In the WCF-WebHttp Transport Properties dialog box, on the Proxy tab, configure the proxy setting for the WCF-WebHttp send port.

    Use this

    To do this

    Use send handler proxy settings

    Specify whether this send port uses the proxy settings in the send handler hosting this send port.

    This is the default setting.

    Do not use proxy

    Indicate whether this send port uses a proxy server.

    The default value is cleared.

    Use proxy

    Indicate whether this send port uses the proxy server specified in the Address property.

    The default value is cleared.

    Address

    Specify the address of the proxy server. Use the https or the http scheme depending on the security configuration. This address can be followed by a colon and the port number. For example, http://127.0.0.1:8080.

    This property requires a value only if Use proxy is selected.

    Type: String

    Maximum length: 256

    The default is an empty string.

    User name

    Specify the user name to use for authentication. If integrated authentication is used, the user name includes the domain, that is, domain\username. If Basic or Digest authentication is used, the user name does not include domain\. This property requires a value only if Use proxy is selected.

    System_CAPS_noteNote

    The WCF-WebHttp send adapter uses the basic authentication for the proxy.

    Type: String

    Minimum length: 0

    Maximum length: 256

    The default is an empty string.

    Password

    Specify the password to use for authentication.

    This property requires a value only if Use proxy is selected.

    Type: String

    Minimum length: 0

    Maximum length: 256

    The default is an empty string.

  8. In the WCF-WebHttp Transport Properties dialog box, on the Messages tab, specify how the message is sent to the REST interface.

    Use this

    To do this

    Outbound HTTP Headers

    Specifies the HTTP headers that are stamped on the response message, if any.

    Suppress Body for Verbs

    Based on the verb you use to invoke a REST endpoint, you may or may not require a message payload. For example, you may not need a message payload while using the GET or DELETE verbs. However, to trigger a call to the REST endpoint using the send port, you may use a dummy message that includes a message payload. Before the message is sent to the REST endpoint, the message payload from the dummy message must be removed. You can specify the verbs for which the message payload must be removed using the Suppress Body for Verbs property.

    For example, if you want to remove the message payload while using a GET verb, specify the value for this property as GET.

  9. Click OK and OK again to save settings.

Community Additions

ADD
Show:
© 2016 Microsoft