Using the Local Transport

32.1 Introduction to the Local Transport

In a Service Bus project, proxy service logic is exposed to the client, but there may be cases where you do not want that logic exposed. In this case, you can design the logic behind a local transport proxy service, and then invoke that proxy service from other Service Bus projects.

For example, if you have several services that invoke a back-end service, you can create a separate project with a local proxy service to define all the back-end (unexposed) logic. You can then invoke that local proxy service from other Service Bus projects, keeping certain processing logic private from all clients.

Local proxy services are also the only way to call pipelines contained in other projects. When the pipelines are all in the same Service Bus project, one pipeline can call another pipeline directly. However, a pipeline cannot call a pipeline in a different project directly. To achieve this, you need to use a local proxy service between the pipelines. The local transport provides the following capabilities:

Efficient and secure communication.
Propagation of transactions and transactional behavior.
Propagation of security context so the identity can be propagated end-to-end. The security context propagation also allows the client of the first proxy service in a chain of services to be authorized by the proxy services that are subsequently invoked in the chain, supporting fine-grained access control.

32.1.1 Features and Characteristics of Local Transport Proxy Services

Local transport-based proxy services can only be invoked by other proxy services or pipelines, and not by other clients. The invocation is optimized by Service Bus. Local proxy services do not have a URI; however, there are no constraints on the service and interface types supported by local transport proxy services. The one exception is that SAML is only supported in a pass through scenario.

If the quality of service (QoS) for the invoking service is defined as Exactly Once, the transaction of that service is propagated to the local transport proxy service. In other words, the invoked local transport proxy service inherits the transactional behavior of the invoking service.

A proxy service can authenticate at the transport level or the message level. If it is enabled, the effective client is the message-level authenticated client. If the message-level authenticated client is not enabled, then the transport-level authenticated client is the effective client (if that is enabled). If neither the message-level nor the transport-level authenticated client is enabled, the anonymous client becomes the effective client.

When a proxy service invokes a local transport proxy service, the effective client of the invoking service becomes the transport-level client of the invoked local proxy service. A local transport proxy service can authorize this client for access with an access control policy. In this way, it is possible to propagate the client of the first service to the subsequent proxy services in the overall end-to-end message flow.

Local transport proxy services support user-defined transport headers. Consider a scenario in which a proxy service uses the HTTP transport. It routes through a pipeline to a local proxy service, and the pipeline passes headers to the local proxy service using a transport header action. In this scenario, if the HTTP proxy service received the Content-Type header, that header is available as a user header in the local transport and is therefore accessible through the standard user header, instead of as a typed transport header.

32.2 Using Local Transport Proxy Services

Local transport proxy services are useful when you have portions of the message flow you want to keep private and other portions you want to expose.

For example, you could have projects that define back-end processing and call those projects from projects that define front-end logic such as alerting and fault handling. Using local proxy services for the back-end projects keeps them private.

The pipelines in the front-end projects route messages to the local transport proxy service. You can call the same local proxy service from multiple pipelines and from multiple projects. The following figure illustrates a local proxy service invoked by a project with an HTTP proxy service and by a project with a JMS proxy service.

Figure 32-1 Using a Local Transport Proxy Service

Description of "Figure 32-1 Using a Local Transport Proxy Service"

32.2.1 Changes from Previous Usage

In previous versions of Service Bus, the local transport could be used in cases where an Any SOAP or XML type proxy service acted as a front-end to different enterprise systems. This front-end proxy service was a generic router to the appropriate local transport. In the current Service Bus version, with the ability to create pipelines separately from the proxy service, this usage of the local transport is obsolete. You can replace the local proxy services with pipelines, as illustrated in Figure 32-2 and Figure 32-3.

As with the previous version, you can use dynamic routing to abstract the routing rules at runtime and route messages to the local transport proxy services. For an example of how dynamic routing is used, see Using Dynamic Routing.

The following figure illustrates how the local transport would be used in this scenario in release 11g.

Figure 32-2 Accessing Multiple Business Services in Previous Versions

Description of "Figure 32-2 Accessing Multiple Business Services in Previous Versions"

In the current release, the above 11g scenario would be updated to include pipelines instead of local proxy services, as shown below.

Figure 32-3 Updated Method to Access Multiple Business Services

Description of "Figure 32-3 Updated Method to Access Multiple Business Services"

32.3 Propagating SOAP Faults Between Proxy Services

When chaining local proxy services, SOAP faults in the $fault variable are not automatically propagated from one proxy service through the pipeline to another proxy service.

Consider the following example:

Client > Proxy1 > Pipeline > Proxy2 > Business Service > Back-end Service

If a SOAP fault occurs in the back-end service, it is propagated to the $fault variable in Proxy2. However, the SOAP fault value in Proxy2 is not automatically propagated to the $fault variable in Proxy1 and is therefore not returned to the client.

To propagate the SOAP fault from one proxy to another:

In the pipeline, add an error handler that contains a Reply with Failure action. This returns the SOAP message with fault information contained in the $body variable. For more information, see Adding Reply Actions in the Console.
In the pipeline, transform the $body variable as necessary to return the desired SOAP error details to the client.

For more information on how Service Bus handles SOAP faults, see Generating the Error Message, Reporting, and Replying.

32.4 Using OWSM Security with Local Proxy Services

You can attach Oracle Web Services Manager (OWSM) service policies to local proxy services with a WSDL service type, which lets you apply specific security controls to messages arriving at each local proxy.

This section describes how Service Bus processes polices at runtime when a proxy service forwards messages with security headers through a pipeline to local proxy services. Message forwarding occurs through actions such as route, service callout, and publish.

Proxy services do not perform outbound WS-Security processing when forwarding messages to other proxy services. The diagrams in this section illustrate this behavior, showing WS-Security configurations in different proxy-to-proxy scenarios. Use these scenarios to understand the behavior so that you can successfully use OWSM service policies on local proxy services that receive messages from other proxy services.

Figure 32-4 shows a client with a client policy sending a message to a front-end proxy that could have any of the following characteristics:

The front-end proxy could be active and contain an OWSM policy that performs inbound processing on all WS-Security headers in a request or only a subset of those headers. For example, it might process the authentication policy but not the message protection policy when the request contains both authentication and message protection headers. The proxy could also contain a non-security policy such as an OWSM log policy.
The front-end proxy could be passive and contain an OWSM policy.
The front-end proxy could contain no OWSM policy.

In each of these cases, the front-end proxy service encounters at least one security header in the message. The proxy service passes this message without performing outbound WS-Security processing to the pipelines, which in turn pass the message to the local proxy services. The local proxy services may or may not contain OWSM policies.

In Figure 32-4, local proxy service 2 receives the message without throwing an exception, because the message contains the expected security headers. Even if the front-end proxy service contains a policy that performs partial security processing (for example, authentication processing but no message protection processing), the forwarded message would still contain security headers.

Figure 32-4 Front-end Proxy as Security Pass-through to Local Proxies

Description of "Figure 32-4 Front-end Proxy as Security Pass-through to Local Proxies"

Figure 32-5 shows a client with a client policy sending a message to a front-end proxy service. The front-end proxy service is active and contains an OWSM service policy that processes all WS-Security headers in the message. The inbound service policy is processed, which strips the message of its security headers. Because the front-end proxy service forwards the message to other proxies, no outbound WS-Security processing is performed, and the message without security headers is forwarded to the local proxy services. One local proxy service contains an OWSM service policy that expects security headers, and an exception is thrown when the message arrives without those headers. The other local proxy contains an OWSM non-security policy where no enforcement occurs, so the message without security headers passes through successfully.

Figure 32-5 Front-end Proxy Processes All Security Headers Before Forwarding to Local Proxies

Description of "Figure 32-5 Front-end Proxy Processes All Security Headers Before Forwarding to Local Proxies"