26 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 guidance on using REST with Oracle Service Bus.

You can use different types of transports to configure proxy services or business services in Oracle 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 are transports with transport pollers pinned to a Managed Server. These transports use the JMS framework to ensure that the processing of a message is done at least once. Email, File, FTP, and SFTP are poll-based transports. This section describes the poll-based transports and the HTTP transport.

This document includes the following sections:

26.1 HTTP Transport

The HTTP transport lets you send messages between clients and service providers through Oracle Service Bus using the http/s protocol. The HTTP transport also provides support for working with REST (Representational State Transfer) environments, as described in Section 26.1.4, "REST Support."

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: /someService

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

where someService is the name of proxy service or a business service.

26.1.1 HTTP Session Stickiness

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

Oracle 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 with session stickiness.

26.1.2 Configuring Proxy Services using the HTTP Transport

Table 26-1 describes the parameters you can specify to configure the HTTP transport for a proxy service.

Table 26-1 Parameters for Configuring HTTP Transport for Proxy Service

Parameter Description

HTTPS Required

Select this check box for inbound HTTPS endpoints.

To learn more, see Chapter 49, "Configuring Transport-Level Security."

Authentication

You must configure one of the following authentication methods:

  • None - Specifies that authentication is not required.

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

    Caution: 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 "Editing Transport-Level Access Policies" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

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

  • 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 an Oracle Service Bus user.

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

Dispatch Policy

Select the instance of Oracle 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

The following describe request encoding for inbound and outbound transports:

  • 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 Oracle Service Bus runtime decides 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

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

Authentication Header

Enter the HTTP header (any except Authorization) from which Oracle Service Bus is to 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.


For more information on how to configure HTTP transport based proxy services and advanced settings, see Section 2.3, "Working with Proxy Services."

26.1.3 Configuring Business Services using the HTTP Transport

You must select HTTP as the transport protocol when you configure any type of business service based on HTTP and the endpoint URI is of the form:

http://<host:port/someService>

where:

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

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

  • someService: 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>
    

Table 26-2 describes all the parameters you can specify to configure HTTP transport for a business service.

Table 26-2 Parameters for Configuring HTTP Transport for Business Service

Parameter Description

Read Timeout

Enter the read timeout interval in seconds.

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, Oracle Service Bus raises a connection error.

A zero (0) value indicates no timeout.

HTTP Request Method

This parameter lets you to use one of the following HTTP methods in a request:

  • POST – Passes 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 – You can 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 a Service Type of "Any XML Service," or with a Service Type of "Messaging Service" when the Request Message Type is set to "None." For REST-based requests, GET retrieves a representation of a remote resource.

  • PUT – You can use PUT in a business service with a Service Type of "Any XML Service" or "Messaging Service." PUT tells the transport to perform a create/replace operation with a REST-based request, such as uploading a file to a known location.

  • HEAD – You can use HEAD in a business service with a Service Type of "Any XML Service," or with a Service Type of "Messaging Service" when the Response Message Type is set to "None." HEAD tells the transport to get header information for a remote resource rather than getting a full representation of the resource in a REST-based request.

  • DELETE – You can use DELETE in a business service with a Service Type of "Any XML Service" or "Messaging Service." DELETE tells the transport to perform a delete operation with a REST-based request.

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:

  • None - Specifies that authentication is not required to access this 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.

    Caution: 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 "Editing Transport-Level Access Policies" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

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

Service Account

A service account is an alias resource for a user name and password. This is a required field if you selected the Basic Authentication Required field.

For more information, see Section 2.1.15, "Creating Service Account Resources."

Dispatch Policy

Select the instance of Oracle 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.

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, Oracle Service Bus automatically re-sends the request to the new URL without any action on your part. Clear this check box if you do not want the HTTP redirects to be automatically followed.

Use Chunked Streaming Mode

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

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

Session Stickiness

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

Sticky sessionID Name

If Session Stickiness is enabled, enter a unique identifying name for the sticky session.


For more information on how to configure this transport, see Section 2.2, "Working with Business Services."

26.1.4 REST Support

The HTTP transport provides support for working with REST (Representational State Transfer) environments through Oracle 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 Oracle 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.

Oracle Service Bus provides the following placeholder variables for handling REST-based requests for inbound and outbound communication:

  • $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.

26.1.4.1 REST in Proxy Services

With an Oracle Service Bus 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, if your team wants 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.

26.1.4.1.1 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 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 will be /temperature/35457, and the XQuery output will be:

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

Query-String Parameters

A proxy service has a URI 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 will be operation=temperature&pincode=35457, which are stored as individual parameters in the http:parameters metadata. The XQuery output will be:

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

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

26.1.4.2 REST in Business Services

With an Oracle Service Bus 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 Service Type of WSDL Web Service, 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 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
    

    and 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
    
26.1.4.2.1 Response Codes and Error Handling for HTTP Business Services

Oracle Service Bus aligns with the HTTP 1.1 specification for handling all response codes in range 200-500. Table 26-3 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 Web Service

  • Any SOAP Service

  • Messaging Service, 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 26-3 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.


26.2 Email Transport

You can select the email transport protocol when you configure a Messaging Type or Any XML Service type of proxy service or business service. The following topics describe how to configure proxy services and business service using the email transport.

Note:

The email transport supports one-way messaging for services of Messaging Services type.

When you create a messaging type proxy service or a messaging type business service using email transport you must set the response type to none in the Message Type configuration page.

26.2.1 Configuring Proxy Services Using the Email Transport

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

mailfrom:<mailserver-host:port>

where mailserver-host is the name of the host mail server port: is the port used by the mail server host.

Table 26-4 describes the parameters you can configure for an email transport based proxy service.

Table 26-4 Parameters for Configuring Email Transport for Proxy Services

Parameter 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 Oracle Service Bus truststore in order for SSL to work. The Email Transport supports one-way SSL communication.

Service Account

Enter a service account name, or click Browse to select service accounts from a browser. This is the service account resource. The service account consists of a user name/password combination required to access the email account.

Managed Server

This field is available only in a clustered domain.

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.

Polling Interval

Enter a polling interval, in seconds. The default value is 60.

Email Protocol

Select POP3 or IMAP as the server type for the email account.

Read Limit

Specify the maximum number of messages to read per 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.

Post Read Action

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

  • Archive - The message is archived.

  • Delete - The message is deleted.

  • Move - The message is moved. 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 parameter 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.


For more information on how to configure email services, see Section 2.3, "Working with Proxy Services."

26.2.2 Configuring Business Services Using the Email Transport

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

Table 26-5 describes the parameters you can configure for an email transport based proxy service.

Table 26-5 Parameters for Configuring Email Transport for Business Services

Parameter Description

SSL Required

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

Notes:

  • The email server certificate must be present in the Oracle Service Bus truststore in order for SSL to work.

  • If you are using TLS, you must either place the trust certificate in the default trust store ($JAVA_HOME/jre/lib/security/cacerts) or place it in any trust store and add the path in the $DOMAIN_HOME/bin/setDomainEnv.* file, as shown below:

    set EXTRA_JAVA_PROPERTIES=%EXTRA_JAVA_PROPERTIES%
    -Djavax.net.ssl.trustStore=<path to trustStore>
    

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 Section 2.1.17, "Creating 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 Server Console.

From Address

Enter the originating email account for this service. You need to create a Mail Session in Oracle WebLogic Server Administration 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 reply 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 the enter 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.


For more information on how to configure business services, see Section 4.2, "Business Service Configuration."

26.3 File Transport

You can select the File transport protocol when you configure a Messaging Type or Any XML Service type of proxy service and the endpoint URI is of the form:

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

where root-dir/dir1 is the absolute path to the destination directory.

Note:

File transport supports one-way messaging only for services of Messaging Service type.

When you create a messaging type proxy service or a messaging type business service using file transport you must set the response type to none in the Message Type configuration page.

To ensure that no programs can access a file while Oracle 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.

26.3.1 Configuring Proxy Services using the File Transport

Table 26-6 describes the parameters you can specify to configure the file transport for a proxy service.

Table 26-6 Parameters for Configuring File Transport for Proxy Services

Parameter 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. Only the wildcard characters * and ? are allowed in the File Mask. Regular expressions are not supported.

Polling Interval

This is a mandatory parameter. The length of time in seconds that Service Bus waits to poll for new files to read. The default value is 60.

Read Limit

This is a mandatory parameter. This specifies 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

This is an optional parameter. This parameter indicates the sequence of events raised in the order of the arrival of files. The default value for this parameter is False.

Scan Subdirectories

This is optional. If enabled, the sub-directories are also scanned.

Pass By Reference

If this parameter is enabled, the file is staged in the archive directory and passed as a reference in the headers.

Post Read Action

This parameter is mandatory. This specifies whether the files should be deleted or archived after being read by the service. By default the files are to be deleted after reading.

Stage Directory

This is a mandatory parameter. This file URI points to the staging directory.

Note: You must not put the stage directory inside the polling directory.

Archive Directory

This is a mandatory parameter. This file URI points to the directory where the files are archived. This field is active only when Post Read Action parameter is set to archive.

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

Error Directory

This is a mandatory parameter. This URI points to a directory, in which the contents of the file will be stored in case of a error.

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

Request Encoding

This is an optional parameter. This parameter specifies the type of encoding to read the request message. The default encoding is utf-8.


For more information on how to configure file transport based proxy services, see Section 2.3, "Working with Proxy Services."

26.3.2 Configuring Business Services using the File Transport

When you configure a business service using the file transport you must specify the endpoint URI in the following format:

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

where root-dir/dir1 is the absolute path to the destination directory.

Table 26-7 describes the parameters you can specify to configure the file transport for a proxy service.

Table 26-7 Parameters for Configuring File Transport for Business Services

Parameter Description

Prefix

This is an optional parameter. This parameter specifies the prefix to be attached to the filename.

Suffix

This is an optional parameter. This parameter specifies the suffix to be attached to the filename.

Request Encoding

This is an optional parameter. This specifies the type of encoding to read the message. The default encoding which will be used is utf-8.


For more information on how to configure this transport, see Section 2.2, "Working with Business Services."

26.4 FTP Transport

You can select the FTP transport protocol when you configure a Messaging Type or Any XML Service type of proxy service and the endpoint URI is of the form:

ftp://<hostname:port/directory>

where

  • hostname – The name of the host on which the destination directory is stored.

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

  • directory – The destination directory.

    The directory is relative to the FTP session's working directory. For example, if you want the FTP service to copy a file to home/my_ftp/documents, and the working directory is home/my_ftp/, the URL would be ftp://example:21/documents.

    Note:

    File transport supports one-way messaging for services of Messaging Services type.

    When you create a messaging type proxy service or a messaging type business service using FTP transport you must set the response type to none in the Message Type configuration page.

To ensure that no programs can access a file while Oracle 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.

26.4.1 Configuring Proxy Services using the FTP Transport

Table 26-8 describes the parameters you can specify the parameters to configure the FTP transport for a proxy service.

Table 26-8 Parameters for Configuring FTP Transport for Business Services

Parameter Description

User Authentication

You must select one of the following types of user authentication:

  • anonymous–If you select anonymous, you do not require any login credentials to login to the FTP server, but you optionally supply your email ID for identification.

  • external user–If you select external user, you have to reference a Service Account resource, which contains your user name/password for the FTP server.

Pass By Reference

This is an optional parameter. If this parameter is enabled, the file is staged in the archive directory and passed as a reference in the headers.

Remote Streaming

This is an optional parameter. Setting this parameter to True will poll FTP files directly from the remote server at processing time.

File Mask

This is a mandatory parameter. This specifies the files that should be polled by the proxy service. If the URI is a directory and *.* is specified, then the service will poll all the files in the directory.

Polling Interval

This is a mandatory parameter. This specifies the value for the polling interval in seconds. The default value is 60.

Read Limit

This is a mandatory parameter. This specifies the number of files to be read in each poll. The default value is 10.

Post Read Actions

This is a mandatory parameter. This specifies whether the files should be deleted or archived after being read by the service. By default, the files are deleted after reading.

Transfer Mode

This parameter specifies whether the mode of file transfer is binary or ASCII. By default the transfer is binary.

Archive Directory

This is a mandatory parameter. This file URI points to the directory where the files are archived. This field is active only when Post Read Action parameter is set to archive.

Download Directory

This is a mandatory parameter. Enter the directory on your local computer 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 Oracle WebLogic Server.

Error Directory

This is a mandatory parameter. This URI points to a directory location, where the contents of the file will be stored in case of a error.

Request Encoding

This is an optional parameter. This parameter specifies the type of encoding to read the request message. The default encoding is utf-8.

Advanced Settings

Click the icon to expand the Advanced Settings section. Configuring parameters in this section is optional. The parameters you can set in this section are:

  • Scan Subdirectories–This is optional. If enabled the sub-directories are also scanned.

  • Sort By Arrival

  • Timeout

  • Retry


For more information on how to configure file transport based proxy services, see Section 2.2, "Working with Business Services."

26.4.2 Configuring Business Services using the FTP Transport

You can select the FTP transport protocol when you configure a Messaging Type or Any XML Service type of business service and the endpoint URI is of the form:

ftp://<hostname:port/directory>

where

  • hostname – The name of the host on which the destination directory is stored.

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

  • directory – The destination directory.

    The directory is relative to the FTP session's working directory. For example, if you want the FTP service to copy a file to home/my_ftp/documents, and the working directory is home/my_ftp/, the URL would be ftp://example:21/documents.

Table 26-9 describes the parameters you must specify to configure the FTP transport for a business service.

Table 26-9 Parameters for Configuring FTP Transport for Business Service

Parameter Description

User Authentication

You must select one of the following types of User Authentication:

  • anonymous–If you select anonymous, you do not require any login credentials to login to the FTP server. But you optionally supply your email ID for identification.

  • external user–If you select external user, you have to reference a Service Account resource, which contains your user name/password for the FTP server.

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.

Request Encoding

This is an optional parameter. This parameter specifies the encoding for the request message.


For more information on how to configure this transport, see Section 2.2, "Working with Business Services."

26.5 SFTP Transport

The SFTP transport is a poll-based transport that lets you 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 Oracle Service Bus services and the SFTP server, enabling file transfer. The SFTP transport supports one-way inbound and outbound connectivity.

Note:

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

The following are the key features of SFTP transport:

  • The SFTP transport is available for the following service types:

    • Messaging service (with request message type specified)

    • Any XML service

    For more information about configuring service types, see Section 2.2, "Working with Business Services" andSection 2.3, "Working with Proxy Services."

  • 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" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

  • The SFTP transport lets you select a preferred cipher suite and public-key, data integrity, key exchange, and compression 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 Oracle Service Bus messaging, see "Modeling Message Flow in Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

To ensure that no programs can access a file while Oracle 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.

26.5.1 Environment Values

Environment values are predefined fields in the configuration data and 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 26-10 Environment Values

Environment Value Description

Archive Directory

The directory to which the files are moved from either the download directory or the remote location.

Download Directory

The directory on your local computer to which files are downloaded during the file transfer.

Error Directory

The location where messages are posted if there is a problem.

Managed Server for Polling

The Managed Server that is used for polling (in a cluster scenario).

Preferred Cipher Suite

The cipher suite to use when communicating with the server. Enter any of the cipher suites listed in the Preferred Cipher Suite field for the SFTP transport.

SFTP Preferred Data Integrity Algorithm

The bulk-hashing algorithm to use for data integrity checks. Enter any of the algorithms listed in the Preferred Data Integrity Algorithm field for the SFTP transport.

SFTP Preferred Public Key Algorithm

The asymmetric key algorithm for public-key cryptography. Enter any of the algorithms listed in the Preferred Public Key Algorithm field for the SFTP transport.

SFTP Preferred Key Exchange Algorithm

The key exchange protocol for negotiating the session key for encrypting the message. Enter any of the algorithms listed in the Preferred Key Exchange Algorithm field for the SFTP transport.

SFTP Preferred Compression Algorithm

An indicator of whether to compress in-flight data using zlib. Enter zlib to compress data; otherwise enter None.


For more information, see:

26.5.2 General Principles of SFTP Authentication

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

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

  • Authentication by the SFTP server

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

    • For username-password authentication, the SFTP server authenticates the connection with the username and password.

  • Authentication by the SFTP client: The Oracle 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 Section 26.5.4.1.1, "Creating the Known Hosts File."

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

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

26.5.3 Runtime Behavior

Transferring files by using the SFTP transport involves the following steps:

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

    Note:

    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.

    Note:

    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.

    Note:

    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.

26.5.4 Using the SFTP Transport

You can use the SFTP transport to transfer files securely using SSH File Transfer Protocol (SFTP).

The following sections describe how you can use the SFTP transport to transfer files securely:

26.5.4.1 Enabling SFTP Authentication

The SFTP transport supports the following authentication methods:

  • Username-password authentication

  • Host-based authentication

  • Public key authentication

Oracle Service Bus services authenticate the SFTP server based on the server details defined in a known_hosts file. So to enable server authentication, you must create a known_hosts file on the client computer.

26.5.4.1.1 Creating the Known Hosts File

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

  1. Create a known_hosts file and enter details 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

    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 directories /transports/sftp are not created automatically. You must create the directories.

26.5.4.1.2 Enabling Username-Password Authentication

Username-password authentication is the simplest and quickest method of authentication. It is based on the credentials of the user.

To enable username 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 Section 2.1.15, "Creating Service Account Resources."

  2. Create a known_hosts file. For more information, see Section 26.5.4.1.1, "Creating the Known Hosts File."

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

To enable host-based authentication for a service:

  1. Configure a service key provider with an SSL client authentication key. For more information, see "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

    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 Section 26.5.4.1.1, "Creating the Known Hosts File."

  3. Configure the SFTP server to accept requests from Oracle Service Bus, which is a client to the SFTP server.

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

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

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

      Note:

      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 computer 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 option 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.

26.5.4.1.4 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 "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

  2. Configure the SFTP server to accept requests from Oracle Service Bus (SFTP client).

    For example, for an SFTP server on Linux, you must 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 Section 26.5.4.1.1, "Creating the Known Hosts File."

26.5.4.2 Configuring Proxy Services

When you create a proxy service in the Transport Configuration page of the Oracle Service Bus Administration Console, you must select the transport protocol as sftp and specify the endpoint configuration in the following format:

sftp://hostname:port/directory

Following is a description of each part of the endpoint URI:

  • 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 that is polled for files at regular intervals.

    The directory is relative to the SFTP session's working directory. For example, if you want the SFTP service to copy a file to home/my_sftp/documents, and the working directory is home/my_sftp/, the URL would be sftp://example:21/documents.

    Note:

    Since the SFTP transport supports only message and XML service types, you must select Messaging Service or Any XML Service as the service type in the General Configuration page of the Oracle Service Bus Administration Console.

    When you select Messaging Service as the service type,

    • You must specify Binary, Text, MFL, or XML as the request message type.

    • You must set the response message type to None because the SFTP transport supports only one-way messaging.

    For more information, see Section 2.3, "Working with Proxy Services."

Configure the proxy service as described in the following table.

Table 26-11 Configuring SFTP Proxy Service

Field Description

User Authentication

The proxy service is authenticated by the SFTP server based on the specified user authentication method.

Select the required authentication method.

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

Service Account

Enter the service account for the user, or click Browse and select a service account. For information about using service accounts, see Section 2.1.15, "Creating Service Account Resources."

Service Key Provider

This field is available only for the public key and host-based authentication methods.

Enter a service key provider, or click Browse and select a service key provider. For more information, see "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Username

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.

Enter the user name.

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. Therefore, you must specify the archive directory relative to the SFTP user directory.

File Mask

You can use the file mask for transferring files of specific types.

Enter a regular expression to select the files that you want to pick from the directory. The default value is *.*.

Polling Interval

Polling interval is the frequency at which the input directory is polled. Polling involves creation of an SFTP connection.

Enter the interval (in seconds) at which the file must be polled from the specified location. The default value is 60.

Note: Avoid setting a low polling interval because a low interval causes frequent polls on the directory.

Read Limit

If numerous files exist in the poll directory, you can limit the number of concurrent transfers by selecting an appropriate value in this field.

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

Note: In some cases, the SFTP server may 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 the action that must be performed on the message after the file is transferred.

  • Archive: The message is archived in the specified archived directory.

  • Delete: The message is deleted.

Archive Directory

If Post Read Action is set to Archive, then, after the files are transferred, they are moved (from either the download directory or the remote location) to the archive directory.

If you selected the Pass By Reference option, you must specify the archive directory.

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 Oracle Service Bus computer.

Specify the absolute path of the archive directory.

Note: If the directory does not exist, it is created automatically. If you specify a relative path, the directory is created at a path that is relative to the Java process that starts the Oracle WebLogic Server.

Download Directory

During file transfer, the files are downloaded to this directory.

If remote streaming is enabled, this option is disabled.

Specify the absolute path of the directory on your local computer to which files are downloaded during the file transfer.

Note: If the directory does not exist, it is created automatically. If you specify a relative path, the directory is created at a path that is relative to the Java process that starts the Oracle WebLogic Server.

Error Directory

If a problem occurs during file transfer, the messages are posted to the error directory.

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 Oracle Service Bus computer.

Specify the absolute path of the error directory.

Note: If the directory does not exist, it is created automatically. If you specify a relative path, the directory is created at a path that is relative to the Java process that starts the Oracle 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

You can use this setting to enable multiple attempts in case of errors such as network failure.

Specify the number of retries for SFTP connection failures. The default value is 3.

Preferred Cipher Suite

Enter the cipher suite to use when communicating with the server.

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.

If you use the default value, Use Runtime Default, Oracle 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.

If you use the default value, Use Runtime Default, Oracle 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.

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, Oracle 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.

Preferred Compression Algorithm

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


For more information about configuring proxy services to use the SFTP transport, see Section 2.3, "Working with Proxy Services."

26.5.4.2.1 Configuring Transport Headers and Metadata

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

Table 26-12 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 Oracle Service Bus Message Flow

You can configure the transport headers only for outbound requests in the Oracle Service Bus message flow. In the pipeline, use a transport header action to set the header values in messages. For more information, see Section 2.4.32, "Adding and Configuring Transport Headers Actions in Message Flows."

Configuring Transports Headers and Metadata in the Test Console

You can configure the FileName transport header and the isFilePath metadata values in the Oracle Service Bus Test Console when you test the SFTP transport-based services during development. For more information, see "Using the Test Console" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

26.5.4.3 Configuring Business Services

When you create a business service in the Transport Configuration page of the Oracle Service Bus Administration Console, you must select the transport protocol as sftp and specify the endpoint URI (location of the service) in the following format:

sftp://hostname:port/directory

Following is a description of each part of the endpoint URI:

  • 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 in which the outbound message is stored or written.

    The directory is relative to the SFTP session's working directory. For example, if you want the SFTP service to copy a file to home/my_sftp/documents, and the working directory is home/my_sftp/, the URL would be sftp://example:21/documents.

    Note:

    Since the SFTP transport supports only message and XML service types, you must select Messaging Service or Any XML Service as the service type in the General Configuration page of the Oracle Service Bus Administration Console.

    When you select Messaging Service as the service type,

    • You must specify Binary, Text, MFL, or XML as the request message type.

    • You must set the response message type to None because the SFTP transport supports only one-way messaging.

    For more information, see Section 2.2, "Working with Business Services."

Configure the business service as described in the following table.

Table 26-13 Configuring SFTP Business Service

Field Description

User Authentication

The proxy service is authenticated by the SFTP server based on the specified user authentication method.

Select the required authentication method.

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

Service Account

Enter the service account for the user, or click Browse and select a service account. For information about using service accounts, see Section 2.1.15, "Creating Service Account Resources."

Service Key Provider

This field is available only for the public key and host-based authentication methods.

Enter a service key provider, or click Browse and select a service key provider. For more information, see "Service Key Providers" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Username

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.

Enter the user name.

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.

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.

Request encoding

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

Preferred Cipher Suite

Enter the cipher suite to use when communicating with the server.

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.

If you use the default value, Use Runtime Default, Oracle 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.

If you use the default value, Use Runtime Default, Oracle 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.

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, Oracle 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.

Preferred Compression Algorithm

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


For more information about configuring business services using the SFTP transport, see Section 2.2, "Working with Business Services."

26.5.4.4 Handling 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 the following topics in "Monitoring" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus:

26.5.4.5 Troubleshooting

Most of the errors occur while configuring an SFTP proxy or business service. The following are a few 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, you must store the public key file on the server. For more information, see the documentation accompanying your SFTP server.

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

  • The Authentication failed error message indicates that the username or password is not valid, or that the public key is not configured correctly.

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

  • The 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.

26.5.4.6 Importing Resources

When you import a resource that exists in an Oracle 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 username-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 from the Oracle Service Bus Administration Console, see Section 2.1.14, "Importing Resources."

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

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

Table 26-14 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 Oracle Service Bus, a conflict is generated.

  • For username-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.


After the service is import imported, the default value of the load balancing algorithm is round-robin.

For more information, see "UDDI" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.