1. Developing Services with Oracle Service Bus
  2. Working with JCA Adapters, Transports, and Bindings
  3. Using HTTP and Poller Transports

27 Using HTTP and Poller Transports

This chapter provides an overview of the HTTP(S) and poller transports (Email, File, FTP, and SFTP) and describes how to use and configure them in your services.

The HTTP transport section also provides information on using REST with Service Bus, but you can also use a REST binding, as described in Creating REST Services with Oracle Service Bus .

This document includes the following sections:

Introduction to Poller Transports

You can use different types of transports to configure proxy services or business services in Service Bus. The transport protocol you select depends on the service type, the type of authentication required, the service type of the invoking service, and so on. Poll-based transports have transport pollers pinned to a Managed Server. These transports poll a source directory or email server for new messages. They use the JMS framework to ensure that messages are processed at least once. Email, File, FTP, and SFTP are poll-based transports.

By default, poller transports use WebLogic Server JMS, but you can configure a clustered domain to use Oracle Advanced Queueing (AQ) JMS when you create or extend the domain. Running the Repository Creation Utility (RCU) creates all the required Service Bus queues and queue tables. The Sort by Arrival feature is not supported for poll-based transports with AQ JMS.

For information about configuring your environment to use Oracle AQ, see Using Oracle Advanced Queueing JMSin Administering Oracle Service Bus.

Using the HTTP Transport

The HTTP transport lets you send messages between clients and service providers through Service Bus using the HTTP(S) protocol.

The HTTP transport also provides support for working with Representational State Transfer (REST) environments, as described in REST Support.

HTTP Session Stickiness

Service Bus supports HTTP session stickiness, or session affinity, for business services in load balancing, which means that the same server handles all requests for a specific session. Service Bus maintains stickiness by mapping the session to a specific entry in a service URI table. In a sticky session, the URI entry that handles the first request has the session; when subsequent messages in the session arrive at the load balancer, they are routed through the same service URI entry that handled the first request.

In a standard load-balancing environment, Service Bus can balance the load across multiple servers, so if messages in a session need to be handled by the same server in a cluster, you need to configure the business services for session stickiness.

Note:

in the Oracle Service Bus Console, you can configure sticky sessions at runtime without needing to restart the service.

Service Bus does not support the following scenarios for sticky sessions:

  • Multiple business services with session stickiness in a single message flow.

  • Multiple business services with session stickiness in the same pipeline.

  • Split-join services that point to business services with session stickiness.

  • Dynamic routing to different business services with session stickiness.

Note also that throttling does not work for business services configured for session stickiness.

Retrieving the HTTP Authorization Header in a Proxy Service

Service Bus does not pass the HTTP Authorization header from the request to the pipeline because it opens a security vulnerability. You could inadvertently create a log action that writes the user name and unencrypted password to a log file.

If your design pattern requires the HTTP Authorization header to be in the pipeline, do the following:

  1. In the startup command for Service Bus, set the following system property to true:
    com.bea.wli.sb.transports.http.GetHttpAuthorizationHeaderAllowed
  2. On the Transport page of the service's definition editor in JDeveloper or the Oracle Service Bus Console, select Get All Headers or select User-specified Headers and specify Authorization.
  3. Restart Service Bus.

Compressed HTTP Request and Response Payload Support

The HTTP transport now supports gzip and deflate compression for use with compressed HTTP request and response payloads. Compression is supported for inbound and outbound payloads.

Accept-Encoding

The client specifies the encodings it supports within the Accept-Encoding header. This header can contain several encoding types as a comma separated list. Service Bus checks for the presence of an acceptable encoding according to RFC 2616, which specifies an Accept-Encoding string specifying algorithm and priorities.

The absence of a supported algorithm causes Service Bus to assume identity, which means no payload manipulation.

If the Accept-Encoding header can’t be parsed (for example, if an invalid format results in a technical error), an HTTP 406 – NOT ACCEPTABLE error is returned and the request is rejected.

A priority value of q=0 will switch off a certain algorithm. It is applied to all algorithms except for identity, which Service Bus always defaults to if no other values are accepted.

If both the gzip and deflate compression algorithms are present in the Accept-Encoding header and have the same priority, gzip compression takes precedence.

The following table contains valid combinations of Accept-Encodings and the encoding Service Bus uses for each combination.

Table 27-1 Accept-Encoding Processing

Accept-Encoding Header Values Service Bus Encoding Decision

gzip;q=1.0, deflate;q=0.5

Gzip

x-gzip,gzip;q=0.25,deflate;q=1.0

Deflate

Gzip

Gzip

gzip;q=0.0,deflate

Deflate

Deflate

Deflate

deflate;q=1.0

Deflate

gzip,deflate

Gzip

x-gzip

Identity

*

Gzip

gzip;q=0.0,deflate,*;q=1.0

Deflate

gzip;q=0.0,*

Deflate

gzip;q=0.0,deflate;q=0.0,*

Identity

deflate;q=0.25,*;q=1.0

gzip

In outbound requesst, when compression support is switched on in the business service, Service Bus always sends an Accept-Encoding header of gzip,deflate.

Content-Encoding

Content-Encoding indicates to a receiver how the payload has been manipulated

Nesting of several compressions to a single message payload is not supported. Content-Encoding may either contain gzip OR deflate.

For an inbound request or outbound response Service Bus parses this header and apply the correct decompression algorithm prior to moving the payload to the pipeline. If Service Bus is configured to send inbound responses and outbound requests with compression it will set the Content-Encoding to the applied compression algorithm.

Content-Length

Content-Length is required especially by HTTP 1.0 clients which do not understand chunked HTTP transfer.

(Optional) Enter reference information in this section.

According to the specification, the Content-Length header must be set before any data is committed to the stream. In case data exceeds the specified Content-Length, the response is committed to the client and the message is broken. Consequently, the Content-Length must be known before writing any data to the stream. This requires that the complete message is buffered while compressing to determine the final length of the compressed data.

Proxy and business service configurations have an option to switch on buffering for inbound responses and outbound requests. In buffered mode, the message will be sent with a Content-Length header. This is not a default option;. it is meant for HTTP 1.0 recipient support only.

Transfer-Encoding

The Transfer-Encoding header indicates what kind of manipulation has been performed on a particular message (in the order they have been applied). This is additional information for network components to guarantee safe message transfer.

This is additional information for network components to guarantee safe message transfer. HTTP 1.0 implementations may not understand this header. The gzip or deflate settings should only be added if the header was already present before the compression happened and applies only to inbound responses and outbound requests.

Note:

chunked must be the last encoding applied to a message.

The Transfer-Encoding header is currently omitted for outbound requests.

ETag

The ETag header indicates manipulations of payloads to content-caches/proxies.

It is possible that a cache or proxy expects a compressed payload, but the calling client doesn’t. Service Bus ensures that this header is properly maintained for inbound responses. It is not manipulated for outbound requests. Service Bus does not require this header as intermediate party.

Sample Requests and Responses

Refer to the following sample inbound and outbound requests and responses.

Example 27-1 Sample Inbound Request

GET /mySampleApp/myProxy HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip, deflate[, compress, exi, bzip2, …]

Example 27-2 Sample Inbound Response

HTTP/1.1 200 OK
Date: Mon, 23 Sep 2013 13:14:34 GMT
Server: WLS 10.3.6 (Unix)  (Red-Hat/Linux)
Content-Length: 438
Content-Type: text/xml; charset=UTF-8
Content-Encoding: gzip
Transfer-Encoding: [if present already, append gzip or deflate, otherwise omit – ALWAYS append chunked as last value]
[gzip payload]

Example 27-3 Sample Outbound Request

POST /myExternalWebApp/some.html HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip
Content-Encoding: gzip
Transfer-Encoding: [if present already, append gzip, otherwise omit. ALWAYS append chunked as last value]
[gzip payload]

Example 27-4 Sample Outbound Response

HTTP/1.1 200 OK
Date: mon, 15 Sep 2013 22:38:34 GMT
Server: Apache/1.3.3.7 (Unix)  (Red-Hat/Linux)
Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT
Etag: "3f80f-1b6-3e1cb03b"
Accept-Ranges: bytes
Content-Length: 438
Connection: close
Content-Type: text/html; charset=UTF-8
Content-Encoding: gzip

HTTP Transport WS-RM Support

Service Bus 12.2.1 supports Web Services Reliable Messaging ( WS-Reliable Messaging or WS-RM) for HTTP transport services of WSDL type.

Attaching the oracle/reliable_messaging_policy and oracle/reliable_messaging_internal_api_policy OWSM policies enables WS-RM for a proxy or business service. See WS-ReliableMessaging Support Using OWSM Policies for additional information.

HTTP Transport Configuration Reference

This section provides information about endpoint URI formats and configuring the HTTP transport in proxy and business services.

HTTP Transport Endpoint URIs

You can select the HTTP transport protocol when you configure any type of proxy or business service. Use the following endpoint URI formats:

  • Proxy Services: /service_name

  • Business Services: http://host:port/service_name

where:

  • host is the name of the system that hosts the service.

  • port is the port number at which the connection is made.

  • service_name is a target service.

    Note:

    You must specify the following endpoint URI when you configure a business service based on HTTPS.

    https://host:port/someService
Configuring Proxy Services to Use the HTTP Transport

The following table describes the properties you use to configure an HTTP transport for a proxy service. For more information, see Creating and Configuring Proxy Services.

Table 27-2 HTTP Transport Properties for Proxy Services

Property Description

HTTPS Required

Select this check box for inbound HTTPS endpoints. The HTTPS protocol uses SSL to secure communication. SSL can be used to encrypt communication, ensure message integrity, and to require strong server and client authentication

To learn more, see Configuring Transport-Level Security for HTTPS.

Authentication

Select one of the following authentication methods:

  • None: Specifies that authentication is not required. Select this option if you will specify an OWSM policy for the proxy service.

  • Basic: Specifies that basic authentication is required to access this service. Basic authentication instructs Oracle WebLogic Server to authenticate the client using a user name and password against the authentication providers configured in the security realm, such as a Lightweight Directory Access Protocol (LDAP) directory service and Windows Active Directory. The client must send its user name and password on the HTTP request header. Basic authentication is strongly discouraged over HTTP because the password is sent in clear text. However, it is safe to send passwords over HTTPS because HTTPS provides an encrypted channel.

    Warning: By default, all users (authorized and anonymous) can access a proxy service. To limit the users who can access a proxy service, create a transport-level authorization policy. See Configuring Transport-Level Security.

  • Client Certificate: Specifies encrypted communication and strong client authentication (two-way SSL). To learn more, see Configuring Transport-Level Security for HTTPS..

  • Custom Authentication: Specifies that an authentication token is contained in an HTTP header. The client's identity is established through the use of this client-supplied token. You must configure an identity assertion provider that maps the token to a Service Bus user.

    The custom authentication token can be of any active token type supported by a configured WebLogic Server Identity Assertion provider.

Dispatch Policy

Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists.

For information about Work Managers, see:

Request Encoding

Specify the character set encoding for the request message.

  • For HTTP inbound transports: If the character set encoding parameter of the Content-Type header is not specified in Client Request, enter a character set encoding parameter. If you do not enter a value, the field defaults to ISO-8859-1.

  • For HTTP outbound transports: If you have not configured a request encoding, the Service Bus runtime determines the most appropriate encoding while it makes a request to the business service. In the case of a non-pass-through scenario, the default character encoding is UTF-8 at runtime. However if it is a pass-through scenario, the runtime will pass through the encoding received with the outbound response.

Response Encoding

Specify the character set encoding for the response message.

Supports Compression

Select this option to enable compression support. The request payload is unzipped if a Content-Encoding header containing gzip or deflate is present. Nested compression is not supported. A proxy configured for compression support stills understands uncompressed requests and can send uncompressed responses.

If this option is not selected, when the client sends compressed data, the proxy service is unable to understand the data and rejects the request. In case the client sends an Accept-Encoding header that contains gzip or deflate, it will be ignored. The response will be sent uncompressed.

Enable Compression Buffer

Select this option to enable compression buffering. When enabled, the entire message will be written to an in-memory buffer in compressed format to determine the Content-Length of the compressed data. The Content-Length header will be set on the response object prior to sending any data to the client. This setting doesn't affect request processing; it only applies to inbound response data handling. Inbound requests are always streamed directly.

Authentication Header

Enter the HTTP header (any header except Authorization) from which Service Bus will extract the token. This field is available only if you selected the Custom Authentication check box.

For example, client-xyz-token.

Authentication Token Type

Select an authentication token type. Only the active token types configured for an Identity Assertion provider are available. This field is available only if you selected the Custom Authentication check box.

Access metadata with URL

If checked, the metadata in the WSDL file can be accessed with a URL in this format: http://<host>:<port>/helloworld/proxy/helloworld?wsdl. If not checked, the WSDL file cannot be accessed with a URL.

Configuring Business Services to Use the HTTP Transport

The following table describes the properties you use to configure an HTTP transport for a business service. For more information, see Creating and Configuring Business Services.

Table 27-3 HTTP Transport Properties for Business Services

Property Description

Read Timeout

Enter the read timeout interval in seconds. If the timeout expires before data is available on the connection, a connection error occurs.

A zero (0) value indicates no timeout.

Connection Timeout

Enter the connection timeout interval in seconds. If the timeout expires before the connection can be established, Service Bus raises a connection error.

A zero (0) value indicates no timeout.

HTTP Request Method

Select one of the following HTTP methods to use in requests:

  • POST: Use POST to pass all its data, of unlimited length, directly over the socket connection as part of its HTTP request body. The exchange is invisible to the client, and the URL does not change. For REST-based requests, POST tells the transport to perform a create/replace operation or perform an action with the request.

  • GET: Use GET to include as part of the request some of its own information that better describes what to get. This information is passed as a sequence of characters appended to the request URL in a query string. You can use GET in a business service with an XML service type or a messaging service type when the Request Message Type is set to "None." For REST-based requests, GET retrieves a representation of a remote resource.

  • PUT: Use PUT to tell the transport to perform a create/replace operation with a REST-based request, such as uploading a file to a known location. You can use PUT in a business service with an XML or messaging service type.

  • HEAD: Use HEAD to tell the transport to get header information for a remote resource rather than getting a full representation of the resource in a REST-based request. You can use HEAD in a business service with an XML service type or a messaging service type when the Request Message Type is set to "None."

  • DELETE: Use DELETE to tell the transport to perform a delete operation with a REST-based request. You can use DELETE in a business service with an XML or messaging service type.

Note: If a method is already set in the $outbound/transport/request/http:http-method variable, that value takes precedence over any method you select for HTTP Request Method.

Authentication

Select one of the following types of HTTP authentication:

  • None: Authentication is not required to access this service.

  • Basic: Basic authentication is required to access this service. Basic authentication instructs WebLogic Server to authenticate the client using a user name and password against the authentication providers configured in the security realm, such as a Lightweight Directory Access Protocol (LDAP) directory service and Windows Active Directory. The client must send its user name and password on the HTTP request header.

    Basic authentication is strongly discouraged over HTTP because the password is sent in clear text. However, it is safe to send passwords over HTTPS because HTTPS provides an encrypted channel.

    Warning: By default, all users (authorized and anonymous) can access a business service. To limit the users who can access a business service, create a transport-level authorization policy. See Configuring Transport-Level Security.

  • Client Certificate: Specifies encrypted communication and strong client authentication (two-way SSL). To learn more, see Configuring Transport-Level Security for HTTPS.

  • Custom Authentication: Specifies that a custom Java class defines authentication. You must specify the authentication class in the HTTP Custom Authentication Class Name field in the advanced settings (described below).

Service Account

Enter a service account that will be used for authentication to access the service. This is a required field if you select basic authentication. It is optional if you select custom authentication.

For more information, see Working with Service Accounts.

Dispatch Policy

Select the instance of WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists.

For information about Work Managers, see:

Request Encoding

Accept the default iso-8859-1 as the character set encoding for requests in HTTP transports, or enter a different character set encoding.

Response Encoding

Accept the default iso-8859-1 as the character set encoding for responses in HTTP transports, or enter a different character set encoding.

Supports Compression

Select this option to enable compression support. If enabled, you can select an outbound request compression algorithm with the Request Compression Algorithm setting. Outbound responses with either gzip or deflate compression will automatically be supported according to the outbound response's Content-Encoding header.

If this option is not selected, uncompressed payloads are sent. No headers are added. Receiving a compressed outbound response will lead to an error.

Request Algorithm Compression

When Supports Compression is selected, three options for handling compression for outbound requests are available:

  • None: does not compress an outbound request, however compressed outbound responses are understood

  • Gzip: gzip compresses outbound payloads

  • Deflate: deflate compresses outbound payloads

The Accept-Encoding header will be set to "gzip, deflate". Outbound responses containing a Content-Encoding header with any of these two compression algorithms will be understood.

Enable Compression Buffer

Select this option to enable compression buffering. When enabled, the entire message will be written to an in-memory buffer in compressed format to determine the Content-Length of the compressed data. The Content-Length header will be set on the response object prior to sending any data to the recipient.

This setting doesn't affect request processing; it only applies to inbound response data handling. Inbound requests are always streamed directly.

This option is disabled if one of the following conditions is true:

  • The Supports Compression setting is deselected

  • The Supports Compression setting is selected and None is selected in the Request Compression Algorithm list

Note: this setting is incompatible with the Use Chunked Streaming Mode setting. Only one or the other can be selected.

HTTP Custom Authentication Class Name

Enter the name of the Java class used for custom authentication. This field is only available if you selected Custom Authentication for the authentication type. For information about creating the custom authentication class, see How to Create a Custom Authentication Class for Outbound.

Proxy Server

Enter a proxy server resource or click Browse to choose an entry from the list of configured proxy server resources.

Follow HTTP redirects

Select this check box to specify that HTTP redirects (which are requests with a response code 3xx) should be automatically followed. A redirect occurs when you send an outbound request to the URL of a business service, and that service returns a response code (for example, 302) that says the URL is no longer valid and this request needs to be sent to another URL. If you select the Follow HTTP Redirects check box, Service Bus automatically resends the request to the new URL without any action on your part. Deselect this check box if you do not want the HTTP redirects to be automatically followed.

Use Chunked Streaming Mode

Select this option if you want to use HTTP chunked transfer encoding to send messages.

Note: Do not use chunked streaming with the Follow HTTP Redirects option. Redirection and authentication cannot be handled automatically in chunked mode.

Session Stickiness

Select this option if you want to use session stickiness (also known as session affinity) for HTTP requests for the business service. For more information, see HTTP Session Stickiness..

Sticky sessionID Name

Enter a unique identifying name for the session if Session Stickiness is enabled.

REST Support

The HTTP transport provides support for working with REST environments through Service Bus, whether you have REST clients that need to interact with non-REST service providers, non-REST clients that need to interact with REST-based service providers, or REST-to-REST services you want to expose through Service Bus.

In a REST pattern, you invoke HTTP methods (such as GET, PUT, HEAD, POST, and DELETE) on resources that are located at specific URLs. For example, when a user updates his own profile information in a web application that uses REST, a POST action updates the user information in the database through the service's REST API.

While Service Bus incorporates the REST binding, as described in Creating REST Services with Oracle Service Bus . Service Bus also provides the following placeholder variables for handling REST-based requests for inbound and outbound communication using the HTTP transport:

  • $inbound or $outbound/transport/request/http:http-method: For handling HTTP methods such as GET, PUT, HEAD, POST, and DELETE.

  • $inbound or $outbound/transport/request/http:parameters: For handling a query string in a URL. The parameters metadata contains one or more parameter elements that store name-value pairs. The name-value pairs are URLDecoded values in the query string. For example, in the URL http://localhost:7021/myproxy/weather?operation=temperature&pincode=94065, the query string is stored as the following query parameters: 

    <http:query-parameters>
  <http:parameter name="operation" value="temperature"/>
  <http:parameter name="pincode" value="94065"/>
</http:query-parameters>

  • $inbound or $outbound/transport/request/http:relative-URI: For handling relative portions of a REST resource URL (relative to the proxy service URI). For example, in the URL http://localhost:7021/myproxy/weather, /weather is a relative URL to http://localhost:7021/myproxy.

REST in Proxy Services

With a proxy service, you have the flexibility to interact with REST patterns, whether you are receiving REST-based requests or generating REST-based actions.

For example, to develop REST-based applications and invoke services in a non-REST service provider, you can send REST operations through a proxy service and transform those operations into a format the service provider understands; or you could transform a non-REST request into a resource URL and invoke an operation in a REST-based service provider. You can also use Service Bus as an intermediary for monitoring, auditing, and reporting on REST-to-REST implementations.

For working samples that use REST with Service Bus, see the Oracle Service Bus Samples repository, accessible from http://www.oracle.com/technetwork/middleware/service-bus/learnmore/index.html.

XQuery Examples

Following are XQuery examples of URI parsing using HTTP variables in a proxy service. URI parsing lets you transform messages between REST and non-REST environments.

Relative-URI

A proxy service has a URI of http://localhost:7001/weather, and you want to capture the relative URI parts of a request. You create the following XQuery: 

<relative-URI>
{
for $c in
fn:tokenize($inbound/ctx:transport/ctx:request/http:relative-URI, "/")
where fn:string-length($c) != 0
return
<part>
{$c}
</part>
}
</relative-URI>

If a request comes with the URI of http://localhost:7001/weather/temperature/35457, the relative URI is /temperature/35457, and the XQuery output is as follows: 

<relative-URI>
    <part>temperature</part>
    <part>35457</part>
</relative-URI>

Query-String Parameters

A proxy service has a URI of http://localhost:7001/weather, and you want to capture the URL query string parameters. You create the following XQuery: 

<query-parameters>
{
return 
<param name="$inbound/ctx:transport/ctx:request/http:parameters/param/name"
value="$inbound/ctx:transport/ctx:request/http:parameters/param/value"></param>
}
</query-parameters>

If a request comes with a URI of http://server:7001/weather?operation=temperature&pincode=35457, the query string is operation=temperature&pincode=35457, which are stored as individual parameters in the http:parameters metadata. The XQuery output is: 

<query-parameters>
    <param name='operation' value='temperature'/>
    <param name='pincode' value='35457'/>
</query-parameters>
Headers

If your service requires specific headers to handle HTTP/REST methods, create user-defined HTTP header variables in your pipeline.

REST in Business Services

With a business service, you can invoke REST-based services. For REST operations, the HTTP transport uses the value in the $outbound/transport/request/http:http-method variable. If that variable does not supply an HTTP method, the HTTP transport lets you select one of the following HTTP request methods in the transport configuration: POST, PUT, HEAD, GET, AND DELETE.

Note:

If the business service uses a WSDL service type, only the POST method is available.

Using the $outbound/transport/request-http/http-method variable, you can also supply your own methods. For example, you can use COPY, MOVE, and LOCK for WebDAV environments (Web-based Distributed Authoring and Versioning).

Use the following guidelines for setting $outbound variables:

  • The transport does not provide runtime validation for custom methods or for manually set supported methods that do not comply with the constraints described in this section.

  • Since $outbound is only available in a routing node, you cannot specify a method name at runtime for publish and service callout actions.

  • If the $outbound query string parameters are set, the business service uses outbound request encoding for building the query string from raw bytes and URL encoding for parameter name-value pairs retrieved from the parameters metadata element.

  • If the $outbound relative URI is set, the business service uses that value to generate the URI, which is relative to the business service URI.

    For example, in a business service with a URI of 

    http://service.com/purchaseOrder

    with the following HTTP variables

    $outbound/transport/request-http/relative-URI: "/PO12367" and
$outbound/transport/request-http/parameters/parameter: "item=NO1"
$outbound/transport/request-http/parameters/parameter: "color=black"

    the final resolved URI is

    http://service.com/purchaseOrder/PO12367?item=NO1&color=black

Response Codes and Error Handling for HTTP Business Services

Service Bus aligns with the HTTP 1.1 specification for handling all response codes in range 200-500. Table 27-4 describes how Service Bus handles the different response code levels.

HTTP business services must be of the following types to receive response payloads containing errors 300 and greater:

  • WSDL

  • Any SOAP

  • Messaging, with the following conditions:

    • The response message type must be MFL or XML (determined to be of type XML or SOAP). HTTP business services with response types that Service Bus determines to be other than XML or SOAP do not receive HTTP response payloads.

    • The Content-Type HTTP header in the response payload is text/xml, application/any_string+xml, or multipart/related.

Table 27-4 Response Code Handling for HTTP Business Services

Response Status Codes Description

100s

100-level status codes indicate a provisional response consisting of only the Status-Line and optional headers, terminated by an empty line. The response behavior for 100-level codes is already handled by the internal HttpURLConnection Java class, so Service Bus does not handle these.

200s

200-level status codes indicate a successful operation. Service Bus returns these as the response payload to HTTP business services regardless of the business service type.

300s

300-level status codes are errors which indicate that further action needs to be taken by the caller in order to fulfill the request. Service Bus returns these as the response payload to HTTP business services with supported message response types.

In the response pipeline, you can take appropriate action to handle 300-level codes.

To handle 300-level response codes that indicate the need for a redirect, set the "Follow HTTP Redirects" option on the HTTP business service transport configuration.

400s

400-level status codes indicate a client error. Service Bus returns these as the response payload to HTTP business services with supported message response types.

In the response pipeline, you can take appropriate action to handle 400-level codes.

500s

500-level status codes indicate a server error. Service Bus returns these as the response payload to HTTP business services with supported message response types.

In the response pipeline, you can take appropriate action to handle 400-level codes.

Large Payload Rejection with the HTTP Transport

Payloads over the default of 10MB and attachments over 1 GB are rejected for inbound messages under the HTTP transport in a Reference Configuration domain.

The rejection limit is for the payload controlled by the -Dsoa.payload.threshold.kb parameter and for the attachment by the -Dsoa.attachment.threshold.kb parameter. If either threshold is exceeded, the message is rejected.

Using the Email Transport

You can use the email transport with services that have a Messaging or Any XML service type.

The following topics describe how to configure proxy services and business service using the email transport. The email transport supports one-way messaging for services with the Messaging service type. When you create a Messaging type proxy service or business service using the email transport you must set the response type to none in the service configuration.

Email Transport Configuration Reference

This section provides information about endpoint URI formats and configuring the email transport in proxy and business services.

Email Transport Endpoint URIs

When you configure a proxy service using the email transport, specify the endpoint URI in the following format: 

mailfrom:mailserver-host:port

where mailserver-host is the name of the server hosting the mail service and port is the port number used by that server.

When you configure a business service using the email transport, you can specify one or more endpoint URIs in the following formats, which lets you send email messages to multiple recipients in multiple domains: 

mailto:name@domain_name.com

mailto:name@domain_name.com?smtp=smtp_server_resource

mailto:name@domain_name.com?mailsession=jndi_mail_session

For example:

mailto:user1@example1.com

mailto:user2@example2.com?smtp=exampleSMTP

mailto:user3@example3.com?mailsession=my.mail.Session
Configuring Proxy Services to Use the Email Transport

The following table describes the properties you use to configure an email transport for a proxy service. For more information, see Creating and Configuring Proxy Services.

Table 27-5 Email Transport Properties for Proxy Services

Property Description

SSL Required

Select this option to communicate using Secure Sockets Layer. The default SSL port numbers are:

  • POP3(S): 995

  • IMAP: 993

Note: The email server certificate must be present in the Service Bus truststore in order for SSL to work. The Email Transport supports one-way SSL communication.

Service Account

Enter a service account that will be used for authentication to access the email account. The service account consists of a user name and password combination required to access the email account.

For more information, see Working with Service Accounts.

Managed Server

Select the Managed Server to act as the polling server. All of the Managed Servers can process the message, but only one can poll for the message.

This field is available only in a clustered domain.

Polling Interval

Enter an interval in seconds between attempts to poll for new messages to process. The default value is 60.

Email Protocol

Select POP3 or IMAP as the email protocol to use to connect to the email server.

Read Limit

Specify the maximum number of messages to read for each polling sweep. Enter 0 to specify no limit. The default value is 10.

Pass By Reference

Select this check box to stage the file in the archive directory and pass it as a reference in the headers.

By default when you create a new service, the Pass By Reference option is selected and you must specify the archive directory location.

Pass Attachments by Reference

Select this check box to stage the attachments in the archive directory and pass them as a reference in the headers.

By default, when the Pass By Reference option is selected, the Pass Attachments By Reference option is implicitly true and you must specify the archive directory location.

Post Read Action

Select what happens to a message after it has been read:

  • Archive: The message is archived. If you select this option, specify an archive directory where Service Bus will archive the messages.

  • Delete: The message is deleted.

  • Move: The message is moved. If you select this option, specify an IMAP move folder to which Service Bus will move the message. Move is only available with the IMAP protocol.

Attachments

Select how attachments are handled:

  • Archive: Attachments are saved to the archive directory.

  • Ignore: Attachments are ignored.

Note: If attachments are archived, the attachment files are passed as a reference in the message headers irrespective of the settings for the Pass By Reference parameter.

IMAP Move Folder

Enter the folder to which the message is moved if the Post Read Action field is set to Move.

You must configure this field if Post Read Action is set to move.

Download Directory

Enter a temporary location for downloading emails.

Archive Directory

Specify the path to the archive location if the Post Read Action field is set to Archive.

This field is required if the Pass By Reference or Pass Attachments By Reference option is selected. It is active only when Post Read Action property is set to archive.

Error Directory

Enter the file system directory path to write the message and any attachments if there is a problem.

Request Encoding

Accept the default ISO-8859-1 as the character set encoding for requests in email transports, or enter a different character set encoding.

Configuring Business Services to Use the Email Transport

The following table describes the properties you use to configure an email transport for a business service. For more information, see Creating and Configuring Business Services.

Table 27-6 Email Transport Properties for Business Services

Property Description

SSL Required

Select this option to communicate using Secure Sockets Layer. The Email Transport supports one-way SSL communication. The default SMTP port number when using SSL is 465.

Note: The email server certificate must be present in the Service Bus truststore in order for SSL/TLS to work.

SMTP Server

Select the default SMTP server to use for endpoint URI entries of name@domain_name.com. If you provide SMTP server parameters in the endpoint URI, those server resources are used instead of this SMTP server setting.

Do not select an SMTP server if you use the Mail Session option.

You must first create the SMTP server resource. For more information, see How to Create SMTP Server Resources.

Mail Session

Enter the JNDI name of the configured mail session to use for endpoint URI entries of name@domain_name.com. If you provide JNDI mail session parameters in the endpoint URI, those mail sessions are used instead of this Mail Session setting.

Do not enter a Mail Session if you use the SMTP server option.

From Name

Enter a display name for the originating email account for this service. You must first configure mail sessions in the Oracle WebLogic Remote Console.

From Address

Enter the originating email account for this service. You need to create a Mail Session in Oracle WebLogic Remote Console. You must also set the Mail Session parameter or the SMTP server parameter.

Reply To Name

Enter a display name for the reply to email account. This is the name from which the reply should be sent.

Reply To Address

Enter an email address to send replies to.

Connection Timeout

Enter the timeout interval, in milliseconds, before the connection is dropped. If you enter 0, there is no timeout.

Socket I/O Timeout

Enter the socket I/O timeout interval in milliseconds. If this value is zero (0), there is no timeout.

Request Encoding

Accept the default ISO-8859-1 as the character set encoding for requests in email transports, or enter a different character set encoding.

Using the File Transport

Use the File transport to poll messages from files on a shared file system located in the directory you specify.

Once a file is read, Service Bus can either delete or archive the file depending on how you configure the transport. To ensure that no programs can access a file while Service Bus is writing it to the remote location, a File transport business service temporarily appends ".a" to the file name until the file is completely written.

The File transport supports the Messaging and Any XML service types. For the Messaging service type, the supported message types for the request are binary, text, MFL, and XML. The response message type must be None because the File transport supports only one-way messaging.

File Transport Configuration Reference

This section provides information about endpoint URI formats and configuring the File transport in proxy and business services.

File Transport Endpoint URIs

For both proxy services and business services using the File transport, enter the endpoint URI in the following format: 

file:///<root-dir/dir1>

where root-dir/dir1 is the absolute path to the directory where a proxy service polls for files or where a business service writes files.

Configuring Proxy Services to Use the File Transport

The following table describes the properties you use to configure a File transport for a proxy service. For more information, see Creating and Configuring Proxy Services.

Table 27-7 File Transport Properties for Proxy Services

Property Description

File Mask

Specify the files that the proxy service should poll. If the URI is a directory and you specify *.*, the service polls for all the files in the directory. You can use the wildcard characters * and ? in the file mask. Regular expressions are not supported.

Managed Server

Select the Managed Server to act as the polling server. All of the Managed Servers can process the message, but only one can poll for the message.

This field is available only in a clustered domain.

Polling Interval

Specify an interval in seconds between polling attempts for new files to process. The default value is 60.

Note: In order to verify that a file is not being modified when it is picked up for processing, the transport polls for files once and then polls again 5 seconds later and compares the file size. This might result in a delay of 5 seconds over the polling interval set here. Make sure to set this value high enough to give your system enough time to complete processing and unlock the file.

Read Limit

Specify the number of files to be read in each poll. The default value is 10. If 0 is specified, all the files are read.

Sort By Arrival

Specify the sequence of events raised in the order of the arrival of files. The default value for this parameter is False.

When this option is selected for a proxy service that is executed in a clustered environment, messages are always sent to the same server. In other words, load balancing across servers is ignored when this option is selected.

Scan Subdirectories

Select this check box to recursively scan all the subdirectories in the polling directory.

Pass By Reference

Select this check box to stage the file in the archive directory and pass it as a reference in the headers. If you select this option, you must specify an archive directory as well.

Post Read Action

Select what happens to a message after it has been read:

  • Archive: The message is archived. If you select this option, you must specify an archive directory as well.

  • Delete: The message is deleted.

Stage Directory

Enter an intermediate directory to temporarily stage the files while processing them.

This is mandatory regardless of the options you selected above. Do not put the stage directory inside of the polling directory (the directory identified in the URL of the file transport proxy service).

Archive Directory

Specify the path to the archive location if the Post Read Action option is set to Archive. The Archive Directory field is also a required field if you selected the Pass By Reference field.

Note: You must not put the archive directory inside the polling directory

Error Directory

Enter the directory in which the contents of the file will be stored in case of an error.

This is mandatory regardless of the options you selected above. Do not put the error directory inside of the polling directory.

Request Encoding

Accept the default utf-8 as the character set encoding for requests in file transports, or enter a different character set encoding.

Special Considerations for NFS File Systems

When the File transport polls for files, it first gets the list of files in the directory and their sizes. It then polls again after either 5 seconds or the polling interval, whichever is smaller. The transport gets the list of files again, and compares the file sizes to the first list. It processes only those files whose size remained constant throughout the interval. The standard NFS file system does not support the file locking mechanism required for this process. There are a few options you can use to address this.

  • Use extra signaling, such as file renaming after the file is transferred, in combination with a special file name mask.

  • To enable file growth protection on NFS, use the noac NFS mount option. This prevents caching of the files, making sure that the ls command is the actual file size, not the end-result claimed file size.

  • Use NFS version 4 or later, which introduced additional file locking features.

  • If you are using NetApp filer storage, use Mixed Qtree security on the volume, which makes the file locking mechanism usable for CIFS to NFS.

Configuring Business Services to Use the File Transport

The following table describes the properties you use to configure a File transport for a business service. For more information, see Creating and Configuring Business Services.

Table 27-8 File Transport Properties for Business Services

Property Description

Prefix

Enter a prefix that the transport prepends to the file name on the remote server.

Do not enter an asterisk (*) in this field; this character causes a runtime exception. Do not use any characters that are invalid for the target operating system.

Suffix

Enter a suffix that the transport appends to the file name on the remote server. This is a required field.

Do not enter an asterisk (*) in this field; this character causes a runtime exception. Do not use any characters that are invalid for the target operating system.

Request Encoding

Accept the default utf-8 as the character set encoding for requests in File transports, or enter a different character set encoding.

Using the FTP Transport

Use the FTP transport to poll messages from files on a remote file system located in the directory you specify.

Once a file is read, Service Bus can either delete or archive the file depending on how you configure the transport. To ensure that no programs can access a file while Service Bus is writing it to the remote location, an FTP transport business service temporarily appends ".a" to the file name until the file is completely written.

The FTP transport supports the Messaging and Any XML service types. For the Messaging service type, the supported message types for the request are binary, text, MFL, and XML. The response message type must be None because the FTP transport supports only one-way messaging.

FTP Transport Configuration Reference

This section provides information about endpoint URI formats and configuring the FTP transport in proxy and business services.

FTP Transport Endpoint URIs

For both proxy and business services using the FTP transport, enter the URI in the following format:

ftp://<hostname:port/directory>

where

  • hostname is the name of the FTP server on which the source or destination directory is located.

  • port is the port number at which the FTP connection is made.

  • directory is the destination directory on the FTP server. For proxy services, this is the location the service polls for new files. For business services, this is the location where files are written.

    The directory is relative to the working directory of the FTP session. For example, if the working directory is /home/my_ftp/ and the proxy service endpoint URI is ftp://ftp_server:21/documents, the service polls for files in /home/my_ftp/documents. Using the same working directory, if the business service endpoint URI is ftp://fpt_server:21/output, files are written to /home/my_ftp/output.

Configuring Proxy Services to Use the FTP Transport

The following table describes the properties you use to configure an FTP transport for a proxy service. For more information, see Creating and Configuring Proxy Services.

Table 27-9 FTP Transport Properties for Proxy Services

Property Description

User Authentication

Select one of the following types of user authentication:

  • anonymous: This option does not require any login credentials to log in to the FTP server, but you optionally supply your email ID for identification.

  • external user: This option references a service account resource, which contains your user name and password for the FTP server. You must select the service account to use if you select this option.

Identity (email ID)

Enter the mail ID for the anonymous user.

This field is available only if the User Authentication option is set to anonymous.

Service Account

Enter a service account that will be used for authentication to access the FTP server. This field is only available and is required when the User Authentication option is set to external user. You must have already created the service account resource in Service Bus.

For more information, see Working with Service Accounts.

Pass By Reference

Select this check box to stage the file in the archive directory and pass it as a reference in the headers. If you select this option, you must specify an archive directory below.

Remote Streaming

Select this check box to stream the FTP files directly from the remote server at the time of processing. When you select this option, the archive directory is the remote directory on the remote FTP server machine. Therefore, you should specify the archive directory as relative to the FTP user directory

File Mask

Enter the regular expression for the files to be polled by the proxy service. If the URI is a directory and the file mask is *.*, the service polls all files in the directory.

Managed Server

Select the Managed Server to act as the polling server. All of the Managed Servers can process the message, but only one can poll for the message.

This field is available only in a clustered domain.

Polling Interval

Enter the interval (in seconds) at which the service polls for files to process. The default value is 60.

Note: In order to verify that a file is not being modified when it is picked up for processing, the transport polls for files once and then polls again 5 seconds later and compares the file size. This might result in a delay of 5 seconds over the polling interval set here. Make sure to set this value high enough to give your system enough time to complete processing and unlock the file.

Read Limit

Specify the maximum number of messages to read per polling sweep. Enter 0 to specify no limit. The default is 10.

Post Read Actions

Select what happens to a message after it has been read.

  • Archive: The message is archived. If you select this option, you must also specify an archive directory below.

  • Delete: The message is deleted.

Transfer Mode

Select binary or ASCII as the file transfer mode. By default the transfer is binary.

Archive Directory

Specify the path to the archive location if the Post Read Action option is set to Archive. This field is also required if the Pass By Reference option is selected.

Note: The Archive, Download, and Error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Download Directory

Enter the directory on your local machine where files are downloaded during the file transfer.

Note: The Archive, Download, and Error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Error Directory

Enter the location where the contents of the file is stored in case of a error.

Note: The Archive, Download, and Error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Request Encoding

Specify the type of encoding to read the request message. The default encoding is utf-8.

Scan Subdirectories

Select this check box to recursively scan all directories when polling for files.

Sort By Arrival

Select this check box to deliver events in the order of arrival.

Timeout

Enter the socket timeout interval, in seconds, before the connection is dropped. If you enter 0, there is no timeout.

Retry Count

Specify the number of retries for FTP connection failures.
Configuring Business Services to Use the FTP Transport

The following table describes the properties you use to configure an FTP transport for a business service. For more information, see Creating and Configuring Business Services.

Table 27-10 FTP Transport Properties for Business Service

Property Description

User Authentication

Select one of the following types of user authentication:

  • anonymous: This option does not require any login credentials to log in to the FTP server, but you optionally supply your email ID for identification.

  • external user: This option references a service account resource, which contains your user name and password for the FTP server. You must select the service account to use if you select this option.

Identity (Email id)

Enter the mail ID for the anonymous user.

This field is available only if the User Authentication option is set to anonymous.

Service Account

Enter a service account that will be used for authentication to access the service. This field is only available and is required when the User Authentication option is set to external user. You must have already created the service account resource in Service Bus.

For more information, see Working with Service Accounts.

Timeout

Enter the socket timeout interval, in seconds, before the connection is dropped. The default is 60 seconds.

Prefix for destination File Name

Enter an optional prefix that the transport prepends to the file name on the remote server.

Do not enter an asterisk (*) in this field. This character causes a runtime exception.

Suffix for the destination File Name

Enter an optional suffix that the transport appends to the file name on the remote server.

Do not enter an asterisk (*) in this field. This character causes a runtime exception.

Transfer Mode

Select ASCII or binary as the file transfer mode.

Request Encoding

Accept the default UTF-8 as the character set encoding for requests in ftp transports, or enter a different character set encoding.

Using the SFTP Transport

The SFTP transport is a poll-based transport that allows you to transfer files securely over the SSH File Transfer Protocol (SFTP) using SSH version 2.

It polls a specified directory at regular intervals based on a predefined polling interval. After authentication, a connection is established between Service Bus services and the SFTP server, enabling file transfer. The SFTP transport supports one-way inbound and outbound connectivity.

To ensure that no programs can access a file while Service Bus is writing it to the remote location, an SFTP transport business service temporarily appends ".a" to the file name until the file is completely written.

Note:

The SFTP transport may not correctly handle file names in multi-byte character sets.

The SFTP transport supports only Messaging and Any XML service types. For the Messaging service type, the supported message types for the request are binary, text, MFL, and XML. The response message type must be None because the SFTP transport supports only one-way messaging.

SFTP Transport Features

The SFTP transport provides the following features:

  • The SFTP transport is available for the following service types: Any XML and Messaging (with request message type specified). For more information about configuring service types, see Proxy Service Definitions and Business Service Definitions.

  • The SFTP transport supports processing of large messages. When you configure a proxy service, you can enable content streaming and specify whether large messages must be buffered in memory or in a disk file. For more information, see Streaming Body Content.

  • The SFTP transport allows you to select a cipher suite and security algorithms to use, or you can allow Service Bus to find a suitable match.

  • For inbound message transfer, the QoS is set to exactly-once, which ensures that every message is processed at least once. For outbound message processing, the QoS is best-effort.

    Note:

    For messages that are not transferred, you must create the error-handling logic (including any retry logic) in the pipeline error handler.

    For more information about QoS in Service Bus messaging, see Quality of Service.

  • The SFTP transport now supports FIPS (Federal Information Processing Standards) compliance.

    See About FIPS Compliance for the SFTP Transport for more information.

General Principles of SFTP Authentication

The following principles are applicable to the SFTP authentication process for both proxy and business services:

  • Connection: The Service Bus proxy or business service always acts as the SFTP client and connects to the SFTP server.

  • Authentication by the SFTP server: Server authentication works in one of the following ways:

    • For public key and host-based authentication, the SFTP server authenticates the connection with the public key of the Service Bus service.

    • For user name and password authentication, the SFTP server authenticates the connection with the user name and password.

  • Authentication by the SFTP client: The Service Bus service always authenticates the SFTP server with the public-key/host/IP combination defined in the known_hosts file. For more information, see Creating the Known Hosts File.

  • Connection establishment: The connection is established only when both the server and client authentications are successful.

  • File transfer:

    • If the client is a proxy service, the file (message) is downloaded from the SFTP server.

    • If the client is a business service, the file (message) is uploaded to the SFTP server.

SFTP Transport Runtime Behavior

Transferring files using the SFTP transport involves the following steps:

  1. The proxy service polls the input directory at regular intervals.

    A new connection is created for each poll cycle.

  2. If the proxy service finds a file in the input directory, it renames the file with a .stage extension. This renaming ensures that the service does not pick up the same files during the next polling cycle.

    The .stage file exists in the input directory until it is delivered.

    Note:

    If the file cannot be retrieved from the input directory (due to network failure, for example), the .stage file is processed during a clean-up cycle. The clean-up cycle is performed every 15 minutes or after 15 polling cycles, whichever occurs later. If a .stage file exists during two consecutive clean-up cycles, it is processed again.

  3. A JMS task is created for the message and added to the domain-wide JMS queue.

  4. A domain-wide MDB receives the task and processes the message.

    The task uses a pooled connection for processing the message. If a connection is not available in the pool, a new connection is created.

  5. The message is delivered to the pipeline and the .stage file is deleted.

  6. If an SFTP business service is configured, the service puts the message in the outbound directory through a pooled connection.

If the message is not delivered, the transport attempts to transfer it again and repeats the process up to a predefined number of attempts. If the message cannot be delivered, it is moved to the error directory.

Enabling SFTP Authentication

The SFTP transport supports the following authentication methods:

  • User name and password authentication

  • Host-based authentication

  • Public key authentication

Service Bus services authenticate the SFTP server based on the server details defined in a known_hosts file. To enable server authentication, you must create a known_hosts file on the client machine.

Creating the Known Hosts File

The known_hosts file must exist in the server on which the Service Bus proxy services (inbound requests) or business services (outbound requests) run. The file must contain the host name, IP address, and public key of the remote SFTP servers to which the proxy service or business service can connect.

To create the known hosts file:

  1. Create a known_hosts file and enter information in the following format:
    Hostname,IP algorithm publickey

    where:

    • Hostname is the host name of the SFTP server. The hostname is optional.

    • IP is the IP address of the SFTP server.

      If you use an IPv6 address, do not use a double colon to represent multiple zeros. Write out all zeros. For example, use this format ":0:0:0:" instead of this format "::".

    • algorithm can be either DSA or RSA, based on the SFTP server configuration. Enter ssh-rsa or ssh-dss depending on the algorithm that is supported.

    • publickey is the public key of the SFTP server. It must be in the Open SSH public key format.

    Example - Known Hosts File

    getafix,172.22.52.130 ssh-rsa

AAAAB3NzaC1yc2EAAAABIwAAAIEAtR+M3Z9HFxnKZTx66fZdnQqAHQcF1vQe1+EjJ/HWYtg

Anqsn0hMJzqWMatb/u9yFwUpZBirjm3g2I9Qd8VocmeHwoGPhDGfQ5LQ/PPo3esE+CGwdnC

OyRCktNHeuKxo4kiCCJ/bph5dRpghCQIvsQvRE3sks+XwQ7Wuswz8pv58=

    The known_hosts file can contain multiple entries, but each entry must be on a separate line.

  2. Move the known_hosts file to the DOMAIN_HOME/config/osb/transports/sftp directory.

    The directory /transports/sftp is not created automatically. You must create it manually.

Enabling User Name and Password Authentication

User name and password authentication is the simplest and quickest method of authentication. It is based on the credentials of the user.

To enable user name and password authentication for a service:

  1. Create a static service account by using the user credentials on the SFTP server. For more information, see Working with Service Accounts.
  2. Create a known_hosts file. For more information, see Creating the Known Hosts File.
Enabling Host-Based Authentication

Host-based authentication uses a private host key. This method can be used when all the users share a private host.

For host-based authentication, Open SSH compares the host name provided by the client against a reverse lookup on the client IP address. Because of scenarios where the request comes from a multi-homed machine or through NAT gateway, host names may not match, resulting in authentication failure. To work around such scenarios, turn off the DNS check by setting the HostbasedUsesNameFromPacketOnly property to "yes" in /etc/ssh/sshd_config. This work around does not subvert security, because the real security is in the public key matching between the known_hosts file and the SFTP server.

To enable host-based authentication for a service:

  1. Configure a service key provider with an SSL client authentication key. For more information, see Working with Service Key Providers.

    Note:

    You can extract the public key from the key store that was used while creating the service key provider. The public key must be in the Open SSH format.

  2. Create a known_hosts file. For more information, see Creating the Known Hosts File.
  3. Configure the SFTP server to accept requests from Service Bus, which is a client to the SFTP server.

    For example, for an SFTP server on Linux, do the following:

    • Edit the /etc/ssh/shosts.equiv file and add the host name or IP address of the machine on which the Service Bus domain runs.

    • Edit the /etc/ssh/ssh_known_hosts file and add the host name or IP address of the machine on which the Service Bus domain runs, followed by a space and the public key.

Enabling Public Key Authentication

Public key authentication is performed using your own private key. This method can be used when each user has a private key.

To enable public key authentication:

  1. Configure a service key provider with SSL client authentication key. For more information, see Working with Service Key Providers.
  2. Configure the SFTP server to accept requests from Service Bus (SFTP client).

    For example, for an SFTP server on Linux, extract the public key from the key store and enter the key in the $HOME/.ssh/authorized_keys file on the SFTP server. Ensure that the path and file exist.

  3. Create a known_hosts file. For more information, see Creating the Known Hosts File.

About FIPS Compliance for the SFTP Transport

The SFTP transport now supports FIPS (Federal Information Processing Standards) compliance.

FIPS-140–2 validated cryptography algorithms are available for use with the SFTP transport. When FIPS compliance is enabled, the following Public Key Algorithms and Key Exchange Algorithms are supported:

  • Public Key Algorithm: ssh-rsa (Service Bus runtime default with FIPS Compliance enabled)

  • Key Exchange Algorithm: diffie-hellman-group14-sha1 (Service Bus runtime default wit FIPS Compliance enabled)

All other Public Key Algorithms and Key Exchange Algorithms are not supported and are not selectable.

Enabling FIPS Compliance

You can enable FIPS Compliance for proxy or business services using the SFTP transport. You can complete this task using JDeveloper or the Service Bus console.

To enable FIPS compliance for a proxy or business service:
  1. From the proxy or business service’s Transport Detail page, select Enable FIPS Compliance.
  2. Select a supported algorithm from the Preferred Public Key Algorithm list. Unsupported algorithms do not appear in the list.
  3. Select a supported algorithm from the Preferred Key Exchange Algorithm list. Unsupported algorithms do not appear in the list.
FIPS Compliance Upgrade Considerations

FIPS compliance is disabled by default. When upgrading clients, the existing SFTP Transport configurations will show FIPS Compliance as disabled.

When enabling FIPS Compliance, you must select the Preferred Cipher from the list of FIPS compliant ciphers. The following ciphers are FIPS-compliant:

  • aes128-cbc

  • aes128-ctr

  • arcfour

  • arcfour128

  • blowfish-cbc

  • 3des-cbc

  • 3des-ctr

Handling SFTP Transport Communication Errors

You can configure the SFTP transport-based business services to handle communications errors, which can occur when a connection or user authentication fails while connecting to the remote SFTP server. When you configure the business service, you can enable the business service endpoint URIs to be taken offline after a specified retry interval.

For more information, see "Managing and Monitoring Endpoint URIs for Business Services" in Administering Oracle Service Bus.

Troubleshooting the SFTP Transport

Most of the errors occur while configuring an SFTP proxy or business service. Below are some tips to help you understand and solve the errors.

  • Make sure that you have an appropriately configured known_hosts file in place.

  • For public key authentication, store the public key file on the server. For more information, see the documentation accompanying your SFTP server.

  • A Connection refused error message indicates that the SFTP server is not available on the configured host and port.

  • An Authentication failed error message indicates that the user name or password is not valid, or that the public key is not configured correctly.

  • A Connection did not complete error message is displayed after the actual error that caused the connection failure (for example: Key not found).

  • A Key not found for IP, host error message indicates that the known_hosts file does not contain an entry that corresponds to the specified IP-host combination. If the entry exists, then try with another algorithm key; for example, if the earlier attempt was with an RSA key, try again with a DSA key.

Importing SFTP Transport Services

This section provides information about importing Service Bus resources from configuration JAR files and UDDI registries.

Importing Resources Used by the SFTP Transport

When you import a resource that already exists in an Service Bus domain, you can preserve the existing security and policy configuration details of the resource by selecting the Preserve Security and Policy Configuration option. The following SFTP service-specific details are preserved when you import a resource:

  • Client authentication method

  • Reference to the service account (for services associated with user name and password authentication)

  • Reference to the service key provider (for services associated with host-based or public key authentication)

  • User name (for services associated with host-based or public key authentication)

For more information about importing resources, see Importing and Exporting Resources and Configurations .

Importing and Publishing Services: UDDI Registries

When an SFTP service is published to the UDDI registry, Authentication mode, Request encoding, Sort by arrival, and File mask are the properties that are published. After the service is imported, the default value of the load balancing algorithm is round-robin.

Table 27-11 lists the properties that are imported from the registry when an SFTP service is imported from the UDDI registry.

Table 27-11 Properties Imported from UDDI Registry

Property Description

Prefix for destination file name

The prefix for the name of the file that is stored on the remote server.

The default value is " " (null).

Suffix for destination file name

The suffix for the name of the file that is stored on the remote server.

The default value is " " (null).

Authentication mode

The authentication method that is imported from the registry.

When an SFTP business service with user authentication is imported from an UDDI registry to Service Bus, a conflict is generated.

  • For user name and password authentication, you must create a service account and associate it with the service.

  • For host-based or public key authentication, you must create a service key provider and associate it with the service.

For more information, see Working with UDDI Registries.

SFTP Transport Configuration Reference

This section provides information about endpoint URI formats, environment values, and configuring the SFTP transport in proxy and business services.

SFTP Transport Endpoint URIs

For both business and proxy services using the SFTP transport, enter the endpoint URI in the following format:

sftp://hostname:port/directory

where:

  • hostname is the host name or IP address of the SFTP server.

  • port is the port on which SFTP server is listening. The default port for SFTP is 22.

  • directory is the location where a business service writes outbound messages, or where a proxy service polls for files at regular intervals.

    The directory is relative to the SFTP session's working directory. For example, if the working directory is home/my_sftp/ and you want the SFTP proxy service to read files from home/my_sftp/documents, the URI would be similar to sftp://sftp_server:22/documents. Using the same working directory for a business service, if the URI is sftp://sftp_server:22/output, the business service writes files to home/my_sftp/output, x

Configuring Proxy Services to Use the SFTP Transport

The following table describes the properties you use to configure an SFTP transport for a proxy service. For more information, see Creating and Configuring Proxy Services.

Table 27-12 SFTP Transport Properties for Proxy Services

Property Description

User Authentication

Select the required authentication method from the following:

  • Username Password Authentication: Specifies that a static service account is associated with this authentication method and the client is authenticated using the credentials provided in the service account.

  • Host-Based Authentication: Specifies that a user name and service key provider are required. Any user connecting from a known host is authenticated using the private key of the host.

  • Public Key Authentication: Specifies that a user name and service key provider are required. Users have their own private keys.

Note: The service does not use the service key provider to authenticate any credentials from the SFTP server. It uses only the known_hosts file to authenticate the SFTP server, as described in Configuring Transport-Level Security for SFTP Transport.. The proxy service is authenticated by the SFTP server based on the specified user authentication method.

Service Account

Enter a service account that will be used for authentication to access the service. For information about using service accounts, see Working with Service Accounts.

Service Key Provider

Enter a service key provider to use for authentication.

This field is available only for the public key and host-based authentication methods. For more information, see Working with Service Key Providers.

Username

Enter the user name to log in to the SFTP server. This value is required only when you select either the host-based or public key authentication method.

  • In host-based authentication, the user name is required for polling the home directory of the user on the SFTP server.

  • In public key authentication, the user name is required for polling the home directory of the user and for identifying the location of the public key on the SFTP server.

Pass By Reference

Select this option to stage the file in the archive directory and pass it as a reference in the headers.

Note: This option is available only when remote streaming is disabled.

Remote Streaming

Select this option to stream the SFTP files directly from the remote server at the time of processing. When you select this option, the archive directory is the remote directory on the SFTP server machine. Therefore, you must specify the archive directory relative to the SFTP user directory.

File Mask

Enter a regular expression to select the files that you want to pick from the directory. Use the file mask for transferring files of specific types. The default value is *.*, which selects all files.

File Mask is a Regular Expression

Select this option to use regular expressions (regex) in the File Mask field.

Tmp File Suffix

Enter a suffix to append to the temp file used during the transfer. The default value is _tmp.

Managed Server

Select the Managed Server to act as the polling server. All of the Managed Servers can process the message, but only one can poll for the message.

This field is available only in a clustered domain.

Polling Interval

Enter the interval (in seconds) at which the input directory is polled for messages to process. Polling involves the creation of an SFTP connection. The default value is 60. Avoid setting a low polling interval, which can cause polling to occur too frequently.

Note: In order to verify that a file is not being modified when it is picked up for processing, the transport polls for files once and then polls again 5 seconds later and compares the file size. This might result in a delay of 5 seconds over the polling interval set here. Make sure to set this value high enough to give your system enough time to complete processing and unlock the file.

Read Limit

Specify the maximum number of messages to read per polling sweep. If numerous files exist in the poll directory, you can limit the number of concurrent transfers by the value you specify here.

If you do not want to specify a limit, enter 0 (zero). The default value is 10.

Note: In some cases, the SFTP server might limit the number of concurrent connections; make sure that the read limit you define is lower than the server-defined limit.

Post Read Action

Select what happens to the message after is has been read.

  • Archive: The message is archived in the specified directory. If you select this option, you must specify an archive directory below.

  • Delete: The message is deleted.

Archive Directory

Specify the path to the archive location if the Post Read Action option is set to Archive. This field is required if the Pass By Reference option is selected. When files are archived after reading, the files are moved (from either the download directory or the remote location) to the archive directory after they are read.

If remote streaming is enabled, the archive directory is with respect to the SFTP server. If remote streaming is disabled, the archive directory is available on the Service Bus machine.

Note: The archive, download, and error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Download Directory

Enter the directory on your local machine where files are downloaded during the file transfer. If remote streaming is enabled, this option is disabled.

Note: The archive, download, and error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Error Directory

Enter the location where messages are posted if there is a problem.

If remote streaming is enabled, the error directory is with respect to the SFTP server. If remote streaming is disabled, the error directory is available on the Service Bus machine.

Note: The Archive, Download, and Error directories are absolute paths, and they are automatically created. If you specify a relative path, the files are created relative to the Java process that starts the WebLogic Server.

Request encoding

Accept the default value (UTF-8) as the character set encoding for requests in the SFTP transports.

Scan Subdirectories

Select this option if you want all subdirectories within the directory that is specified in the endpoint URI to be scanned recursively.

Note: Scanning subdirectories requires additional processing overhead, so use this option judiciously.

Sort By Arrival

Select this option to deliver events in the order of arrival. This ensures that message delivery is not random, but based on the time at which the file is downloaded to the destination directory.

Timeout

Enter the socket timeout interval, in seconds, after which the connection must be dropped. If you do not want the connection to time out, enter 0. The default value is 60.

Retry Count

Specify the number of retries for SFTP connection failures. Use this setting to enable multiple attempts in case of errors such as network failure. The default value is 3.

Enable FIPS Compliance

Enables FIPS (Federal Information Processing Standards) compliance for SFTP connections. When enabled, FIPS-compatible Public Key and Key Exchange algorithms are enabled and selectable in the Preferred Public Key Algorithm and Preferred Key Exchange Algorithm lists. Incompatible algorithms are disabled and not selectable.

Preferred Cipher Suite

Select the cipher suite to use when communicating with the server from the list of available options. The cipher suite you use determines authentication and encryption settings for the network connection.

If you use the default value, Use Runtime Default, the list of supported cipher suites is sent to the server and each is tried until a match is found.

Preferred Data Integrity Algorithm

Select the bulk-hashing algorithm for data integrity checks from the list of available options.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, hmac-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Public Key Algorithm

Select the asymmetric key algorithm for public-key cryptography from the list of available options.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, ssh-dss. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

If the Enable FIPS Compliance option is selected, the runtime default changes. If you use the default value, Use Runtime Default, Oracle Service Bus sends the preferred algorithm, ssh-rsa. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Key Exchange Algorithm

Select the default key exchange protocol for negotiating the session key for encrypting the message.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, diffie-hellman-group1-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

If the Enable FIPS Compliance option is selected, the runtime default changes. If you use the default value, Use Runtime Default, Oracle Service Bus sends the preferred algorithm, diffie-hellman-group14-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Compression Algorithm

Select whether to compress in-flight data using zlib. Select zlib or zlib@openssh.com to compress data; otherwise select None. The default is None.

Configuring Transport Headers and Metadata

When you configure a proxy service, you can use a Transport Header action in the pipeline to set the header values in messages. The following table lists the transport header and metadata related to the SFTP transport.

Table 27-13 Transport Headers and Metadata

Header / Metadata Description

FileName

This value is used as the file name in the destination directory.

isFilePath

This is a metadata field. The possible values are true and false.

  • True: FileName is interpreted as the absolute path of the file.

  • False: FileName is interpreted as the name of the file.

filePath

This is a response metadata field that indicates the absolute path at which the file specified in the FileName header is written.
Configuring Transport Headers in the Pipeline

You can configure the transport headers only for outbound requests in the pipeline. Use a transport header action to set the header values in messages. For more information, see Adding Transport Header Actions in JDeveloper.

Configuring Transports Headers and Metadata in the Test Console

You can configure the FileName transport header and the isFilePath metadata values in the Test Console when you test the SFTP transport-based services during development. For more information, see Using the Test Console.

Configuring Business Services to Use the SFTP Transport

The following table describes the properties you use to configure an SFTP transport for a business service. For more information, see Creating and Configuring Business Services.

Table 27-14 SFTP Transport Properties for Business Services

Property Description

User Authentication

Select the required authentication method from the following:

  • Username Password Authentication: Specifies that a static service account is associated with this authentication method and the client is authenticated using the provided credentials.

  • Host Based Authentication: Specifies that a user name and service key provider is required to use this authentication method. Any user connecting from a known host is authenticated using the private key of the host.

  • Public Key Authentication: Specifies that a user name and service key provider is required to use this authentication method. Every user has their own private key.

Note: The Service Bus service does not use the service key provider to authenticate any credentials from the SFTP server. It uses only the known_hosts file to authenticate the SFTP server, as described in Configuring Transport-Level Security for SFTP Transport.

Service Account

Enter the service account that will be used for authentication to access the server. For information about using service accounts, see Working with Service Accounts.

Service Key Provider

Enter a service key provider to use for authentication.

This field is available only for the public key and host-based authentication methods. For more information, see Working with Service Key Providers.

Username

Enter the user name. This value is required only when you select either the host-based or public key authentication method.

  • In host-based authentication, the user name is required for polling the home directory of the user on the SFTP server.

  • In public key authentication, the user name is required for polling the home directory of the user and for identifying the location of the public key on the SFTP server.

Timeout

Enter the socket timeout interval, in seconds, before the connection is dropped. If you enter 0, there is no timeout. The default value is 60.

Prefix for destination File Name

Enter an optional prefix that the transport prepends to the file name on the remote server.

Do not enter * in this field. This character causes a runtime exception.

Suffix for the destination File Name

Enter an optional suffix that the transport appends to the file name on the remote server.

Do not enter * in this field. This character causes a runtime exception.

Tmp File Suffix

Enter a suffix to append to the temp file used during the transfer. The default value is _tmp.

Owner File Permissions

If applicable, set the explicit file permission settings for UNIX/Linux type FTP servers. This setting is ignored by server types that don’t support chmod.

Group File Permissions

If applicable, set the explicit file permission settings for UNIX/Linux type FTP servers. This setting is ignored by server types that don’t support chmod.

Other File Permissions

If applicable, set the explicit file permission settings for UNIX/Linux type FTP servers. This setting is ignored by server types that don’t support chmod.

Request encoding

Accept the default UTF-8 as the character set encoding for requests in SFTP transports.

Enable FIPS Compliance

Enables FIPS (Federal Information Processing Standards) compliance for SFTP connections. When enabled, FIPS-compatible Public Key and Key Exchange algorithms are enabled and selectable in the Preferred Public Key Algorithm and Preferred Key Exchange Algorithm lists. Incompatible algorithms are disabled and not selectable.

Preferred Cipher Suite

Select the cipher suite to use when communicating with the server. The cipher suite you use determines authentication and encryption settings for the network connection.

If you use the default value, Use Runtime Default, the list of supported cipher suites is sent to the server and each is tried until a match is found.

Preferred Data Integrity Algorithm

Select the bulk-hashing algorithm for data integrity checks from the list of available options.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, hmac-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Public Key Algorithm

Select the asymmetric key algorithm for public-key cryptography from the list of available options.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, ssh-dss. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

If the Enable FIPS Compliance option is selected, the runtime default changes. If you use the default value, Use Runtime Default, Oracle Service Bus sends the preferred algorithm, ssh-rsa. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Key Exchange Algorithm

Select the default key exchange protocol for negotiating the session key for encrypting the message.

If you use the default value, Use Runtime Default, Service Bus sends the preferred algorithm, diffie-hellman-group1-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

If the Enable FIPS Compliance option is selected, the runtime default changes. If you use the default value, Use Runtime Default, Oracle Service Bus sends the preferred algorithm, diffie-hellman-group14-sha1. If that is not supported by the server, the list of supported algorithms is sent to the server and each is tried until a match is found.

Preferred Compression Algorithm

Select whether to compress in-flight data using zlib. Select zlib or zlib@openssh.com to compress data; otherwise select None. The default is None.

SFTP Transport Environment Values

Environment values are predefined fields in the configuration data that are domain-specific. Their values are likely to change when you move the configuration from one domain to another (for example, from test to production). The following table lists the environment values associated with the SFTP transport.

Table 27-15 SFTP Transport Environment Values

Environment Value Description

SFTP Archive Directory

The archive directory for a SFTP proxy service. If direct-streaming is on, the archive directory is present on the remote SFTP server; otherwise, it is present locally.

SFTP Download Directory

The download directory for a SFTP proxy service.

SFTP Error Directory

The error directory for a SFTP proxy service. If direct-streaming is on, the error directory is present on the remote SFTP server; otherwise, it is present locally.

Managed Server for Polling

The managed server for polling in a clustered domain.

SFTP Preferred Cipher Suite

The cipher suite to use for authentication and encryption in SFTP proxy and business services.

SFTP Preferred Compression Algorithm

The compression library to use to compress in-flight data in SFTP proxy and business services.

SFTP Preferred Data Integrity Algorithm

The bulk-hashing algorithm to use integrity checks in SFTP proxy and business services.

SFTP Preferred Key Exchange Algorithm

The default key exchange protocol for negotiating the session key for encrypting the message in SFTP proxy and business services.

SFTP Preferred Public Key Algorithm

The asymmetric key algorithm for public-key cryptography in SFTP proxy and business services.

For more information about environment variables and the SFTP variables, see: