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. E-mail, 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:
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.3, "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
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:
The custom authentication token can be of any active token type supported by a configured Oracle WebLogic Server Identity Assertion provider. |
|
Dispatch Policy |
Select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy. Dispatch policy refers to the instance of WLS Work Manager that you want to use for the service endpoint. For information about Work Managers, see "Using Work Managers to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server. |
|
Request Encoding |
The following describe request encoding for inbound and outbound transports:
|
|
Response Encoding |
Accept the default |
|
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."
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:
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:
|
|
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 "Using Work Managers to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server. |
|
Request Encoding |
Accept the default |
|
Response Encoding |
Accept the default |
|
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 |
|
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 if you use the Follow HTTP Redirects option. Redirection and authentication cannot be handled automatically in chunked mode. |
For more information on how to configure this transport, see Section 2.2, "Working with Business Services."
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.
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.
Following are XQuery examples of URI parsing using HTTP variables in a proxy server.
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>
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 run-time 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 run time 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
The HTTP transport provides the following response codes for HTTP methods:
Table 26-3 Response codes for HTTP business services
| Method | Response Codes |
|---|---|
|
POST |
200 (OK) 201 (Created) 204 (No Content) |
|
PUT |
200 (OK) 201 (Created) 204 (No Content) 301 (Moved Permanently) – The server sends the response code. The business service handles this response by re-sending the original request. |
|
HEAD, GET |
200 (OK) |
|
DELETE |
200 (OK) 202 (Accepted) 204 (No Content) |
You can select the e-mail 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 E-mail transport.
Note:
E-mail 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 e-mail transport you must set the response type to none in the Message Type configuration page.
When you configure a proxy service using the e-mail 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 e-mail transport based proxy service.
Table 26-4 Parameters for Configuring E-mail Transport for Proxy Services
| Parameter | Description |
|---|---|
|
Service Account |
This is a mandatory parameter. This is the service account resource. The service account consists of a user name/password combination required to access the e-mail account. |
|
Polling Interval |
This is a mandatory parameter. This parameter specifies the polling interval in seconds. The default value is 60. |
|
E-mail Protocol |
This is a mandatory parameter. There are two types of protocol from which you can select, |
|
Read Limit |
This is a mandatory parameter. This specifies the number of files to be read in each poll. The default value is |
|
Pass By Reference |
If this parameter is enabled, the file is staged in the archive directory and passed as a reference in the message headers. |
|
Post Read Action |
This is a mandatory parameter. This specifies whether the files should be deleted, moved, or archived after being read by the service. By default the files are deleted after reading. |
|
Attachments |
This is a mandatory parameter. This parameter specifies if the attachments are to be archived or ignored. By default this parameter is set to ignore. 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 |
This is the destination of the messages if the You must configure this field only if |
|
Download Directory |
This is a mandatory parameter. It specifies the file system directory path to download the message. |
|
Archive Directory |
This is a mandatory parameter. A file URI that points to the directory where the files are archived. This field is active only when |
|
Error Directory |
This is an optional parameter. This parameter specifies the type of encoding to read the request message. The default encoding is |
For more information on how to configure e-mail services, see Section 2.3, "Working with Proxy Services."
When you configure a business service using the e-mail transport, you can specify one or more endpoint URIs in the following formats, which lets you send e-mail 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 e-mail transport based proxy service.
Table 26-5 Parameters for Configuring E-mail Transport for Business Services
| Parameter | Description |
|---|---|
|
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 |
You must first configure mail sessions in the Oracle WebLogic Server Console. |
|
From Address |
Create a Mail Session in Oracle WebLogic Server Administration Console. You must set the Mail Session parameter or the SMTP Server parameter. |
|
Reply To Name |
This is an optional parameter. This parameter specifies the name from which the reply should be sent. |
|
Reply To Address |
This is an optional parameter. This parameter specifies the e-mail address from which the e-mail message should be sent. |
|
Connection Timeout |
This is an optional parameter. You can use this parameter to specify time in milliseconds after which the connection to the SMTP server times out. |
|
Request Encoding |
This is an optional parameter. This parameter specifies the type of encoding to read the request message. The default encoding is iso-8859-1. |
For more information on how to configure business services, see Section 4.2, "Business Service Configuration."
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.
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 |
|
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 |
|
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 |
|
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 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 |
For more information on how to configure file transport based proxy services, see Section 2.3, "Working with Proxy Services."
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."
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.
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:
|
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
Download Directory |
This is a mandatory parameter. 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 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 |
|
Advanced Settings |
Click the icon to expand the
|
For more information on how to configure file transport based proxy services, see Section 2.2, "Working with Business Services."
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:
|
|
Prefix for destination filename |
This is a mandatory parameter. This parameter specifies the prefix to be attached to the filename. |
|
Suffix for destination filename |
This is a mandatory parameter. This parameter specifies the suffix to be attached to the filename. |
|
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."
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 Oracle Service Bus services and the SFTP server, enabling file transfer. The SFTP transport supports one-way inbound and outbound connectivity.
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.
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.
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 machine 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). |
For more information, see:
"Customization" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus
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.
Transferring files by using the SFTP transport involves the following steps:
The proxy service polls the input directory at regular intervals.
Note:
A new connection is created for each poll cycle.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.A JMS task is created for the message and added to the domain-wide JMS queue.
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.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.In 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.
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:
Section 26.5.4.1, "Enabling SFTP Authentication": This section describes the authentication methods that the SFTP transport supports.
Section 26.5.4.2, "Configuring Proxy Services" and Section 26.5.4.3, "Configuring Business Services": These sections describe how you can configure proxy and business services to use the SFTP transport.
Section 26.5.4.4, "Handling Communication Errors" and Section 26.5.4.5, "Troubleshooting": These sections provide information to help you solve problems that may occur while configuring or using the SFTP transport.
Section 26.5.4.6, "Importing Resources": This section describes the SFTP services-specific policy and configuration details that you can preserve when you import resources.
Section 26.5.4.7, "Importing and Publishing Services: UDDI Registries": This section lists the properties that are published when SFTP services are published to UDDI registries. It also lists the properties that are imported when SFTP services are imported from UDDI registries.
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 machine.
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 host name, IP address, and public key of the remote SFTP servers to which the proxy service or business service can connect.
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.
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.
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.
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:
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."
Create a known_hosts file. For more information, see Section 26.5.4.1.1, "Creating the Known Hosts File."
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:
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.Create a known_hosts file. For more information, see Section 26.5.4.1.1, "Creating the Known Hosts File."
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 machine 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 machine 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 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 option to "yes" in /etc/ssh/sshd_config. This workaround does not subvert security, because the real security is in the public key matching between the known_hosts file and the SFTP server.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:
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.
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.
Create a known_hosts file. For more information, see Section 26.5.4.1.1, "Creating the Known Hosts File."
When you create a proxy service in the Transport Configuration page of the Oracle Service Bus 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 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.
|
|
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.
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 machine. 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 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 machine. 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 machine 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 machine. 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 |
For more information about configuring proxy services to use the SFTP transport, see Section 2.3, "Working with Proxy Services."
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.
|
|
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.
When you create a business service in the Transport Configuration page of the Oracle Service Bus 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 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.
|
|
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.
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 the prefix for the name of the file that is stored on the remote server. |
|
Suffix for destination File Name |
Enter the suffix for the name of the file that is stored on the remote server. |
|
Request encoding |
Accept the default value (UTF-8) as the character set encoding for requests in the SFTP transports. |
For more information about configuring business services using the SFTP transport, see Section 2.2, "Working with Business Services."
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:
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.
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 Console, see Section 2.1.14, "Importing Resources."
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.
|
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.