Implementing SOAP and REST Service Invocation Framework

Overview

To invoke and consume external services from Oracle E-Business Suite, Oracle E-Business Suite Integrated SOA Gateway uses service invocation framework (SIF) that leverages Oracle Workflow Java Business Event System (JBES) and seeded Java rule functions to invoke SOAP and REST services.

By using this service invocation framework, developers or implementers can interact with SOAP and REST services through service metadata descriptions instead of working directly with APIs. This approach provides service access in a manner that is independent of protocol or location.

This framework allows updated implementations of a binding to be plugged at runtime. As a result, it not only facilitates a stubless or completely dynamic web service invocation, but also allows the calling service to defer choosing a service binding until runtime. More importantly, this enhances the seamless business integration between loosely-coupled applications and accelerates service invocation and consumption.

Service Invocation Framework has the following features:

To have a better understanding on how the service invocation framework invokes web services, the following topics are described in this chapter:

Architecture Overview

Oracle Workflow is the primary process management solution within Oracle E-Business Suite; Oracle Workflow Business Event System, an essential component within Oracle Workflow, provides event and subscription features that help identify integration points within Oracle E-Business Suite.

The Business Event System consists of an Event Manager and workflow process event activities. The Event Manager lets you register subscriptions to significant events; event activities representing business events within workflow processes let you model complex business flows or logics within workflow processes.

When an event occurs, the Event Manager processes subscription to the event. Subscription processing can include running custom code on the event information, sending event information to a workflow process, and sending event information to other agents or systems.

For example, to invoke a web service through Oracle Workflow JBES, the description of WSDL URL representing the SOAP service (or the description of service endpoint for a REST service) must be consumed through the event subscription definition so that web service metadata can be parsed and stored as subscription parameters.

The runtime architecture diagrams for SOAP and REST services are explained respectively in the following sections:

SOAP Service Invocation Runtime Architecture

To better understand the service invocation process for SOAP services, the following diagram illustrates the transactional architecture details of the runtime SOAP service invocation:

SOAP Service Invocation Transactional Architecture Diagram

the picture is described in the document text

In this diagram, when an invoker event is raised at runtime, the event and subscription parameters are used to invoke a SOAP service by sending a SOAP request message. If this request or output message requires transformation in order to communicate with an external SOAP service, the XSL transformation on the output message is performed before invoking the service. If it is a synchronous request - response operation and the response is available, the XSL transformation on the input message can be performed if necessary in order to communicate or call back to Oracle E-Business Suite.

Note: If event parameters are passed with the same names as the subscription parameters that have been parsed and stored, the event parameter values override the subscription parameters.

Furthermore, the following diagram provides the topology of various components that exchange information during the end-to-end service invocation from Oracle Workflow:

the picture is described in the document text

Service invocation framework from Oracle E-Business Suite is enabled though Oracle Workflow Java Business Event System and is based on the JAX-WS (Java API for XML-based Web Services) Dispatch from Oracle JRF (Java Required Files).

Oracle Workflow Business Event System is a workflow component that allows events to be raised from both the PL/SQL and Java layers. Therefore, the service invocation from Oracle E-Business Suite can be from both layers.

  1. Service Invocation from PL/SQL

    1. Application raises a business event using PL/SQL API WF_EVENT.Raise.

      The event data can be passed to the Event Manager within the call to the WF_EVENT.Raise API, or the Event Manager can obtain the event data or message payload by calling the generate function for the event if the data or payload is required for a subscription.

      Note: See the Oracle Workflow API Reference for information about WF_EVENT.Raise API.

    2. Oracle Workflow Business Event System (BES) identifies that the event has a subscription with the Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription for SOAP services.

    3. The Business Event System enqueues the event message to the WF_JAVA_DEFERRED queue. The Java Deferred Agent Listener then dequeues and processes the subscription whose Java rule function invokes the SOAP service.

    4. If callback event and agent parameters are mentioned, the SOAP service response is communicated back to Oracle E-Business Suite using the callback information. The Java Deferred Agent Listener process that runs on the Concurrent Manager (CM) tier invokes the service.

  2. Service Invocation from Java

    1. Java Application raises a business event using Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise either from the OA Framework page controller/AMImpl or Java code running on the Concurrent Manager (CM) tier.

    2. Since the event is raised in Java where the subscription's seeded Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription for SOAP services is accessible, whether the Java Rule Function is processed inline or deferred is determined by the phase of the subscription.

      • If the invoker subscription is created with Phase greater than or equal to 100, the event is enqueued to the WF_JAVA_DEFERRED queue.

      • If the invoker subscription is created with Phase less than 100, the event is dispatched inline.

        If the event is raised from the OA Framework page, the dispatch logic processes within OACORE WebLogic Server.

After an event is raised either using the PL/SQL API or Java method, the raised event can be processed in the following ways:

While invoking the web service, the seeded Java Rule Function first reads the SOAP service metadata created for the subscription.

If web service input message requires transformation, the Java Rule Function performs XSL transformation on the request message generated during the event creation by using a PL/SQL API ECX_STANDARD.perform_xslt_transformation. Next, the Java Rule Function invokes the service.

Note: For detailed information on the XSL transformation PL/SQL API, see Execution Engine APIs, Oracle XML Gateway User's Guide.

If it is for the synchronous request - response operation, when the response message is available and XSL transformation is required on the web service output message, XSL transformation on the output (response) message will be performed.

If callback information is provided, perform callback by either raising a business event or by enqueuing the event to a given workflow agent with the response message as payload.

Note: For the service invocation from Java code, if the web service invoker subscription is synchronous with subscription phase less than 100, then the web service is invoked as soon as the event is raised, and if it's successful, the response is available immediately by using the method getResponseData() on the BusinessEvent object.

REST Service Invocation Runtime Architecture

The runtime architecture for REST service invocation framework can be depicted in the following diagram:

REST Service Invocation Transactional Architecture Diagram

the picture is described in the document text

In this diagram, when an invoker event is raised at runtime, event and subscription parameters are used to invoke an external REST service by sending a REST request message with payload. The REST service invocation framework will construct the request payload with XML or JSON format, embed the HTTP headers, and optionally add the signing message as part of the HTTP request before invoking the REST service. If it is a synchronous request - response operation and the response is available, the response message in XML or JSON format communicates or calls back to Oracle E-Business Suite.

Note: If event parameters are passed with the same names as the subscription parameters that have been parsed and stored, the event parameter values override the subscription parameters.

Similar to the service invocation framework for SOAP services, REST service invocation from Oracle E-Business Suite can be from a PL/SQL or Java layer.

  1. Service Invocation from PL/SQL

    1. Application raises a business event using PL/SQL API WF_EVENT.Raise.

      The event data can be passed to the Event Manager within the call to the WF_EVENT.Raise API, or the Event Manager can obtain the event data or message payload by calling the generate function for the event if the data or payload is required for a subscription.

      Note: See the Oracle Workflow API Reference for information about WF_EVENT.Raise API.

    2. Oracle Workflow Business Event System (BES) identifies that the event has a subscription with the Java Rule Function oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription for REST services.

    3. The Business Event System enqueues the event message to the WF_JAVA_DEFERRED queue. The Java Deferred Agent Listener then dequeues and processes the subscription whose Java rule function invokes the REST service.

    4. If callback event and agent parameters are mentioned, the service response is communicated back to Oracle E-Business Suite using the callback information. The Java Deferred Agent Listener process that runs on the Concurrent Manager (CM) tier invokes the web service.

  2. Service Invocation from Java

    1. Java Application raises a business event using Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise either from the OA Framework page controller/AMImpl or Java code running on the Concurrent Manager (CM) tier.

    2. Since the event is raised in Java where the subscription's seeded Java Rule Function oracle.apps.fnd.wf.bes.RESTServiceInvokerSubscription for REST services is accessible, whether the Java Rule Function is processed inline or deferred is determined by the phase of the subscription.

      • If the invoker subscription is created with Phase greater than or equal to 100, the event is enqueued to the WF_JAVA_DEFERRED queue.

      • If the invoker subscription is created with Phase less than 100, the event is dispatched inline.

        If the event is raised from the OA Framework page, the dispatch logic processes within OACORE WebLogic Server.

After an event is raised either using the PL/SQL API or Java method, the raised event can be processed in the following ways:

While invoking the service, the seeded Java Rule Function first reads the REST service metadata created for the subscription.

If callback information is provided, perform callback by either raising a business event or by enqueuing the event to a given workflow agent with the response message as payload.

Note: For the service invocation from Java code, if the web service invoker subscription is synchronous with subscription phase less than 100, then the web service is invoked as soon as the event is raised, and if it's successful, the response is available immediately by using the method getResponseData() on the BusinessEvent object.

Implementing Service Invocation Framework

This section discusses the following topics:

Setup Tasks

Web services can be invoked from any one of the following tiers:

Proxy Host and Port Setups

If a target web service resides within the firewall and is directly accessible from an Oracle E-Business Suite server, administrators do not need to configure proxy host and port.

However, if a target web service that is invoked resides outside the firewall and thus the request needs to be routed through the proxy, in this circumstance, administrators must set up and configure proxy host and port appropriately for the tiers that web service invocations occur in order to perform the following activities:

Common Proxy Setup at the WebLogic Server and Concurrent Manger Tier JVM

Use common setup information to configure proxy host and port. This information is applicable to the following conditions:

To configure the proxy host and port for the Oracle WebLogic Server and CM tier JVM, you need to update AutoConfig context file with the following entries and run AutoConfig:

<!-- proxy -->
                <proxyhost oa_var="s_proxyhost">myproxyhost</proxyhost>
   <proxyport oa_var="s_proxyport">80</proxyport>  
   <nonproxyhosts oa_var="s_nonproxyhosts">any domain that needs to be by-passed (such as *.us.example.com)</nonproxyhosts>

This configuration would apply to all programs and services on the CM tier JVM. If you want to set the proxy only for the Workflow container, perform the following steps:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility.

  2. Select the Oracle Applications Manager link from the Navigator and then click the Workflow Manager link.

  3. Click the Agent Listener radio button.

  4. Click the Workflow Java Deferred Agent Listener radio button.

  5. Click the Workflow Agent Listener Service row.

  6. Select "Workflow Agent Listener Service" and click Edit.

  7. Click Edit Service Parameters.

  8. Specify the following value:

    SVC_PROXY_SET=true:SVC_PROXY_HOST=<your proxy server>:SVC_PROXY_PORT=<your proxy port>

  9. Restart the CM container using the adcmctl.sh script in $ADMIN_SCRIPTS_HOME.

Proxy Host and Port Setup When Using Standalone Java Class

You must set the following entries:

java -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=80 classname

Setup Tasks for Invoking TLS-based Web Services Over HTTPS

Service invocation framework supports TLS-based web service invocation using Server Authentication method. When a client connects to a web server via HTTPS, the server sends back its server certificate to the client for verification. Once verified, the client sends the data, encrypted, to the server. Server Authentication allows the client to identify the server. Before invoking a web service from a server over HTTPS (HTTP protocol over TLS), you need to perform manual setup tasks in order to read the TLS-based WSDLs and invoke the TLS service endpoints.

A client may receive one of the following two types of server certificates:

Perform the following setup tasks for the service invocation framework to invoke a TLS-based web service:

Importing Server TLS Certificate into a SIF JVM's Certificate Store

Public Certificate Issued by a Certification Authority (CA)

If server certificate is a public certificate and is issued by a public CA such as VeriSign, then it is most likely available in a SIF JVM's certificate store or in a trusted certificate list.

Self-signed Certificate or Certificate is not in Trusted Certificate List

Perform the following tasks to import the server's TLS certificate into a SIF JVM's certificate store or add it to a trusted certificate list:

  1. Export the server certificate using either one of the following methods:

    • Use openssl Utility:

      Use openssl utility to connect to the destination server with the following syntax:

      $ openssl s_client -connect <server>:<port> -showcerts

      Important: If there is no port in destination, default HTTPS port 443 should be used.

      For example: $ openssl s_client -connect host.example.com:443 -showcerts

      Copy the certificate content from BEGIN CERTIFICATE to END CERTIFICATE (including BEGIN CERTIFICATE and END CERTIFICATE lines as shown in the sample certificate) into a file and save the file (such as my_cert.cer).

      A sample output of above openssl command can be like:

      $ openssl s_client -connect host.example.com:443 -showcerts

... 
Server certificate
-----BEGIN CERTIFICATE-----
MIIFVjCCBD6gAwIBAgIQBVWzfUyIcCa5LtuV+f9WvjANBgkqhkiG9w0BAQUFADCB
sDELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL
ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug
YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNTEqMCgGA1UEAxMh
VmVyaVNpZ24gQ2xhc3MgMyBTZWN1cmUgU2VydmVyIENBMB4XDTA5MDQyMTAwMDAw
MFoXDTEwMDUwNTIzNTk1OVowgckxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxp
Zm9ybmlhMRcwFQYDVQQHFA5SZWR3b29kIFNob3JlczEbMBkGA1UEChQST3JhY2xl
IENvcnBvcmF0aW9uMR8wHQYDVQQLFBZJbmZvcm1hdGlvbiBUZWNobm9sb2d5MTMw
MQYDVQQLFCpUZXJtcyBvZiB1c2UgYXQgd3d3LnZlcmlzaWduLmNvbS9ycGEgKGMp
MDUxGTAXBgNVBAMUECoub3JhY2xlY29ycC5jb20wgZ8wDQYJKoZIhvcNAQEBBQAD
gY0AMIGJAoGBAL/EBxxt2keWTuJbo4SogWmiaJxThYDMvy8nWkpvKIp3s7OCQW0G
t17sAirfBkUirbGRlcWi5fi0RReruGXgYxFnf12fBNAimRWVo3mjeQo8BpRBm27n
3YcTZUlaIE77FvB3913jzD9c4sbjIe2fGpVmx+X9PZmDKSY9KPGjDbFNAgMBAAGj
ggHTMIIBzzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIFoDBEBgNVHR8EPTA7MDmgN6A1
hjNodHRwOi8vU1ZSU2VjdXJlLWNybC52ZXJpc2lnbi5jb20vU1ZSU2VjdXJlMjAw
NS5jcmwwRAYDVR0gBD0wOzA5BgtghkgBhvhFAQcXAzAqMCgGCCsGAQUFBwIBFhxo
dHRwczovL3d3dy52ZXJpc2lnbi5jb20vcnBhMB0GA1UdJQQWMBQGCCsGAQUFBwMB
BggrBgEFBQcDAjAfBgNVHSMEGDAWgBRv7K+g3Yqk7/UqEGctP1WCvNfvJTB5Bggr
BgEFBQcBAQRtMGswJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNv
bTBDBggrBgEFBQcwAoY3aHR0cDovL1NWUlNlY3VyZS1haWEudmVyaXNpZ24uY29t
L1NWUlNlY3VyZTIwMDUtYWlhLmNlcjBuBggrBgEFBQcBDARiMGChXqBcMFowWDBW
FglpbWFnZS9naWYwITAfMAcGBSsOAwIaBBRLa7kolgYMu9BSOJsprEsHiyEFGDAm
FiRodHRwOi8vbG9nby52ZXJpc2lnbi5jb20vdnNsb2dvMS5naWYwDQYJKoZIhvcN
AQEFBQADggEBADBi9NfljQLuD2Tnol3pmQl717rc8kKmpLYEO6u5MxIK0+L2MslV
4NE1qbNx1dfIoW68HHXtpsF5KtKFLYk9EoOkBd7oMp7fFv31RANV3LpdAHZC9EaK
CA/oKB2RrSu7ZmaUvoRb+3v5FdhAmgtoY6Wljk0yxMvXVf/TOeXqKl8C/r1gSzyC
s/jVmy6N81Oeleqtozzt/aJNGu7xu/MdtP13eyu7RSEBRGJwEwTXH+rTUKK8mle0
Kz15DgJ6ByK2XZmD4Z+O8DTUhUhIHR1OhuLR7zjGp9W7wQuCizUcTvuKEGzVf5D/
y7orhV0U+AoXnl/5wntVMZc/Tmqr/Fkb8+g=
-----END CERTIFICATE-----

...

    • Use Web Browser:

      Access the WSDL file available through HTTPS URL (such as https://<hostname>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/?wsdl) or a REST service endpoint (such as https://<hostname>:<port>/webservices/rest/fnduserpkg/testusername/) through a web browser.

      1. After the WSDL file or the REST service endpoint has been successfully loaded in a browser, double click the Lock icon in the bottom right corner of the browser and export the certificate.

        For example, in Internet Explorer, double click the Lock icon > Details > Copy to File. In Mozilla Firefox, double click the Lock icon > Security > View Certificate> Details > Export.

      2. You can also use the browser menu to access the certificate. For example, in Internet Explorer, select Internet Options from the Tools drop-down menu to open the Internet Options pop-up window. Select the Content tab, click Certificates. Select the Personal (or Other People) tab to select your certificate and click Export.

      3. You can export or save the certificate either in DER encoded binary X.509 (.CER) or in Base 64 encoded.

        Note: Different browser versions may have different steps to export TLS certificates.

  2. Import the server's TLS certificate into an appropriate SIF JVM's certificate store to add it to the list of trusted certificates.

    Important: Information about where web services are invoked through the service invocation framework is described in the Setup Tasks.

    There are many utilities available to import certificates. For example, you can use keytool, a key and certificate management utility that stores the keys and certificates in a keystore. This management utility is available by default with JDK to manage a keystore (database) of cryptographic keys, X.509 certificate chains, and trusted certificates.

    The keytool commands have the following syntax:

    keytool -import -trustcacerts -keystore <key store location> -storepass <certificate store password> -alias <alias name> -file <exported certificate file>

    For example:

    keytool -import -trustcacerts -keystore "$AF_JRE_TOP/jre/lib/security/cacerts" -storepass password -alias xabbott_bugdbcert -file my_cert.cer

    Note: This must be typed as a single line. The file (-file) is the exported certificate file, such as my_cert.cer.

Setting Up TLS Proxy Host and Port

If a TLS-based web service resides outside the firewall, the JVM that invokes the web service has to communicate through TLS proxy. Following setup tasks are required in all appropriate tiers to use TLS proxy.

Setting Up Proxy Host and Port at WebLogic Server

For a web service invoked from OA Framework, the JBES seeded Java Rule Function would run within the OACORE WebLogic Server.

WebLogic Server start script (<EBSDomain>/bin/startWebLogic.sh) should have the following system properties setup in JAVA_OPTIONS in order for it to work:

-Dhttps.proxyHost=myproxy.host.name

-Dhttps.proxyPort=80

-Dhttps.nonProxyHosts=*.example.com|localhost

AutoConfig does not currently support properties https.proxyHost and https.proxyPort. To ensure the above properties are retained during the process of AutoConfig, the context file could be customized to add these two properties.

For information on how to customize AutoConfig-managed configurations, see Using AutoConfig to Manage System Configurations in Oracle E-Business Suite Release 12, My Oracle Support Knowledge Document 387859.1.

Setting Up Proxy Host and Port at Concurrent Manger Tier JVM

For a web service invoked from PL/SQL and Java using an asynchronous subscription, the event is raised by the application code wherever it runs and then the event is enqueued to the WF_JAVA_DEFERRED queue by the Event Manager. The event subscription is processed from the CM tier by the Java Deferred Agent Listener.

If a web service is invoked by the Java Deferred Agent Listener, then the code would run within the CM tier Java service's JVM. Workflow Agent Listener Service does not currently support Service Parameters to set the TLS proxy. The TLS proxy could be set up directly to the Concurrent Manager's JVM system properties in $APPL_TOP/admin/adovars.env using AutoConfig.

<oa_environment type="adovars">
 <oa_env_file type="adovars" oa_var="s_adovars_file" osd="unix”>
  $APPL_TOP/admin/adovars.env</oa_env_file>
...
 <APPSJREOPTS oa_var="s_appsjreopts">="-Dhttps.proxyHost=[proxyhost] 
  -Dhttps.proxyPort=[sslproxyport]</APPSJREOPTS>
...
</oa_environment>

Setting Up Proxy Host and Port When Using Standalone Java Class

You must set the following entries:

java -Dhttps.proxyHost=[proxyhost] -Dhttps.proxyPort=[sslproxyport] 
<classname>

Performing Additional Setup Tasks

Additionally, performing the following tasks to invoke services with TLS 1.2 only and TLS 1.2 with backward compatibility:

  1. Apply Patch 22612527 with the prerequisite Patch 13866584 to the FMW home (FMW_HOME).

  2. Update the 32-bit JDK 7 under $OA_JRE_TOP with the Java Cryptography Extension (JCE) updates from the following page: https://www.oracle.com/java/technologies/javase-jce7-downloads.html

  3. Update the 64-bit JDK 7 under the directory referenced by the s_fmw_jdktop context variable with the Java Cryptography Extension (JCE) updates.

  4. Update the Oracle E-Business Suite context variables using Oracle Applications Manager.

    1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility.

    2. Select the Oracle Applications Manager link from the Navigator, and then select AutoConfig.

    3. Select the application tier context file, and choose Edit Parameters.

    4. Update the following context variables:

      • s_afjsmarg = -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2 or -Dhttps.protocols=TLSv1.2

        • To enable TLS 1.2 with backward compatibility, add the following:

          s_afjsmarg = -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2

        • To enable TLS 1.2 only, add the following:

          s_afjsmarg = -Dhttps.protocols=TLSv1.2

      • s_proxyhost = fully qualified host.domain name

      • s_proxyport = port value

      • s_proxybypassdomain = domain name (For example, example.com)

      • s_nonproxyhosts = wildcard domain name (For example, *.example.com)

  5. Run AutoConfig using the adautocfg.sh script in the application tier $ADMIN_SCRIPTS_HOME directory.

  6. Run the adstpall.sh script and the adstrtal.sh script in the same $ADMIN_SCRIPTS_HOME directory to stop and restart all services.

For more information about enabling TLS in Oracle E-Business Suite Release 12.2, see My Oracle Support Knowledge Document 1367293.1.

Implementing Service Invocation Framework for SOAP Services

Service invocation framework allows you to invoke or consume external SOAP services from Oracle E-Business Suite. To successfully achieve this, both integration administrators and integration developers need to collaboratively perform and implement certain tasks. Specifically, an integration administrator needs to perform the following tasks:

An integration developer needs to perform the following tasks:

For more information about these tasks, see Using Service Invocation Framework to Invoke SOAP Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Understanding and Configuring WS-Security for the SOAP Service Invocation Framework

Web service security (WS-Security) is a communication protocol providing a means for applying security to web services. It describes enhancements to SOAP messaging to provide quality of protection through message integrity and single message authentication. It also describes how to attach security tokens to SOAP messages to enhance security features.

The SOAP service invocation framework supports WS-Security in a general-purpose mechanism for associating security tokens with messages to authenticate web service requests and service invocations from Oracle E-Business Suite.

To accomplish this goal, the SOAP service invocation framework supports WS-Security through UsernameToken based security. The following sections explain the UsernameToken based security and the security configuration through the event subscription user interface:

UsernameToken Based Security

This security mechanism authenticates the user invoking a SOAP service by passing a user name and an optional password in the SOAP Header of a SOAP request sent to the web service provider.

The user name and password information discussed here is the concept of Oracle E-Business Suite user name and password.

If the SOAP service that is invoked enforces Username/Password based authentication, then the SOAP service invocation framework also supports the UsernameToken based WS-Security header during the SOAP service invocation.

Note: A SOAP request invoking a web service should include a security header consisting of a user name and plain text password. The password received as part of the SOAP request at runtime will be validated against the encrypted password stored in Oracle E-Business Suite. After validation, the plain text password from the SOAP request will be discarded.

User name is a clear text. Password is the most sensitive part of the UsernameToken profile. The SOAP service invocation framework supports the UsernameToken based WS-Security during the service invocation with a user name and an optional password with Type PasswordText.

For example, a WS-Security header with UsernameToken can be like:

<wsse:Security>
...
        <wsse:UsernameToken wsu:Id="UsernameToken-1" 
 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                <wsse:Username>myUser</wsse:Username>
                <wsse:Password 
 Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
                <wsse:Nonce 
        EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">RDyVo/jbXJdSKuVEPrQW6Q==</wsse:Nonce>
                <wsu:Created>2013-09-02T04:56:48.597Z</wsu:Created>
        </wsse:UsernameToken>
</wsse:Security>

Configuring Web Service Security Through Event Subscription User Interface

To easily maintain UsernameToken based security, the SOAP service invocation framework allows you to configure the security password through the design-time user interface.

After an integration developer enters web service details in the Create Event Subscription - Invoke Web Service wizard, the Web Service Security region is shown letting the developer specify or update the user name and corresponding password if appropriate. The information will then be stored in Vault securely.

Configuring Security Password with Customization Level

Oracle Workflow allows various levels of updates on business event. Each event and subscription is assigned a customization level that determines whether the event data can be updated or not. The customization level is used to protect Oracle E-Business Suite seed data and to preserve your customizations in an upgrade.

Event and subscription can have one of the following customization levels:

Configuring Security Information Between Instances

When configuring web service security with the consideration of moving event subscription definitions between instances, whether you can enter or update the security information is based on the customization level as explained in the following:

Examples of Configuring WS-Security with Different Subscription Customization Levels

Scenario 1:

Define a new business event and subscription with a Customization Level of User in the source environment and have both user name and password manually entered to invoke a web service that requires WS-Security. Move the event and subscription defined earlier to a target environment and configure the WS-Security if required.

Solution:

In this scenario, both the Username and Password fields are editable in the target environment. The Username field value is automatically populated and the Password field value is not available. You can update the new user name (optional) and a corresponding password if needed.

Use the following steps to configure WS-Security in the target instance:

  1. Perform all the steps described in the following topics to define a new event and a subscription with security user name and password:

    • Creating a Web Service Invoker Business Event, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide

    • Creating a Local Subscription to the SOAP Service Invoker Event, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide

  2. Download the event and subscription using the Workflow XML Loader and upload them to the target environment.

    Note: The Workflow XML Loader is a command line utility that lets you upload and download XML definitions for the Business Event System objects between a database and a flat file. For information on downloading and uploading events using the Workflow XML Loader, see:

    • Locate and Download Business Events, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide

    • Upload Annotated File to the Database, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide

  3. Search and locate the invoker business event you defined earlier, such as oracle.apps.xxx.user.webservice.invoke, in the source instance and click the Subscription icon from the result table.

  4. Click the Update icon for the subscription. All fields are updatable because of the customization level of User. Click Next to the last stop of the Update Subscription - Invoke Web Service page.

    In the Web Service Security region, both the Username and Password fields are editable.

    • The Username field, such as weblogic, is automatically populated based on the user name defined earlier in the source environment in Step 1.

    • The Password field value is not available.

    You can update the user name if desired and enter a corresponding password for the web service. Click Apply.

Scenario 2:

All Oracle E-Business Suite products provide seeded events and subscriptions with a Customization Level of Limit or Core for service invocation. The user name may or may not be configured during the subscription creation for the product-specific seeded events to invoke web services that require WS-Security.

When using the seeded events and subscriptions in the target instance of Oracle E-Business Suite Release 12.2, configure the WS-Security by entering a user name, if not already provided by the subscription owner, and the corresponding password for that user to be used for service invocation.

Solution:

In the Oracle E-Business Suite Release 12.2 target instance, log in as a user who has the 'Workflow System Administrator' role, such as sysadmin. The Username field is not updatable if the user name is already provided by the subscription owner. You can always enter an associated password for the user to be used for the service invocation.

Use the following steps to configure WS-Security in the target instance:

  1. Log in to Oracle E-Business Suite 12.2 target instance. Search and locate the product-specific seeded event and click the Subscription icon from the result table.

  2. Click the Update icon for the subscription to load the Subscription details. All fields are disabled except the Status field because the Customization Level is set to Limit.

    Click Next to the last stop of the Update Subscription - Invoke Web Service page.

    In the Web Service Security region, enter the following security information:

    • Username: Enter a user name if it is not part of the seeded subscription definition.

      If the user name is entered by the Subscription owner as part of the seeded definition, this field would show the user name value with no option to edit it. The user needs to only enter the password.

    • Password: Enter a corresponding password for WS-Security.

    • Repeat Password: Enter the same password that you entered in the Password field.

    Click Apply. With WS-Security configured, the web service is ready to be invoked.

For more information about using customization level for an event, see Reviewing the Customization Level and License Status for an Event, Managing Business Events, Oracle Workflow Developer's Guide.

Specifying Expiration Time Parameter for the Security Header

When creating the subscription to the Invoker event, you can add the following parameter in the Web Service Invoker Parameters region to set the expiration time for the security header. This helps protect the header from being reused during a replay.

By default, the header is set to expire 60 seconds in the <wsu:Timestamp> element (with <wsu:Created> and <wsu:Expires>) after it is created. When a different time is specified in the WFBES_SOAP_EXPIRY_DURATION parameter, it overrides the default 60 seconds expiration time for the header.

<wsse:Security soapenv:mustUnderstand="1" 
 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
                <wsu:Timestamp wsu:Id="Timestamp-2" 
 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                        <wsu:Created>2013-09-02T04:56:59.592Z</wsu:Created>
                        <wsu:Expires>2013-09-02T04:57:59.592Z</wsu:Expires>
                </wsu:Timestamp> 
        <wsse:UsernameToken>
...
        </wsse:UsernameToken>
</wsse:Security>

Similar to other subscription parameters added in this region, if a different expiration time is passed as the event parameter, then the event parameter overrides the subscription parameter.

Managing SOAP Service Errors

The SOAP service invocation framework uses the same way of handling errors in the Business Event System to manage errors if occur during the implementation of business event subscriptions. If the service invocation returns a fault message, the event is enqueued to an error queue to trigger error processing. If an exception occurred during the invocation process is due to service unavailability, the service faults should be logged and error subscription should be invoked.

To effectively process runtime exceptions for the events that are enqueued to an error queue, the SOAP service invocation framework uses the following event ERROR process to specifically trigger error processing during the service invocation:

For example, if there is a runtime exception when the Workflow Java Deferred Agent Listener processes an event subscription to invoke a web service, the event is enqueued to the WF_JAVA_ERROR queue. If the event has an Error subscription defined to launch the Error workflow process WFERROR:DEFAULT_EVENT_ERROR2, the Workflow Java Error Agent Listener processes the error subscription which sends a notification to SYSADMIN with the web service definition, error details, and event details. Since Oracle Workflow default event error handler provides options for SYSADMIN to retry the web service invocation process after verifying that the reported error has been corrected, SYSADMIN can invoke the web service again from the notification if necessary.

However, if there is a runtime exception when invoking the web service by raising the Invoker event with synchronous subscription (phase less than 100), the exception thrown to the calling application. It is the responsibility of the calling application to manage the exception.

Enabling Error Processing During Service Invocation

To enable the error processing feature during the service invocation, you must create an Error subscription with the following values:

To access the Create Event Subscription page, log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. Select Business Events from the navigation menu and choose the Subscriptions subtab. In the Event Subscriptions page, click Create Subscription.

For detailed information on how to create an error subscription for service invocation, see Create an Error subscription with 'Launch Workflow' Action Type, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Understanding Implementation Limitation and Consideration for the SOAP Service Invocation Framework

While implementing the SOAP service invocation framework, consider the following limitations:

Implementing Service Invocation Framework for REST Services

Similar to invoking SOAP services through the service invocation framework, as an integration administrator, you need to perform the following tasks to implement the framework to invoke REST services from Oracle E-Business Suite:

An integration developer needs to perform the following tasks:

For more information about these tasks performed by the developer, see Using Service Invocation Framework to Invoke REST Services, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Supporting REST Service Security and Configuring Security with Customization Level

This section describes the REST service security that the REST service invocation framework supports and the customization level that affects the security settings. Specifically, it includes the following topics:

Understanding REST Service Security

The REST service security this framework supports includes:

HTTP Basic Authentication

When an HTTP request message is sent to invoke a REST service from Oracle E-Business Suite, user security credentials (user name/password) should be provided as input data in the HTTP header as part of the request message.

Security credentials provided in the Create Event Subscription - Invoke REST Service page during the event subscription creation are stored internally as subscription parameters.

At runtime, the password is retrieved from FND Vault and Authorization header is included in the HTTP header part of the request to the REST service. Authorization header as per HTTP Basic Authentication scheme is:

Authorization Basic base64 encoded value of <usernmae>:<password>

For example, Authorization Basic xxxxxxxxxxxxxxxxxxxxxxx

Digest HTTP Header

In addition to the HTTP Basic Authentication security that is required to authenticate users before invoking the REST service, the REST service invocation framework provides another layer of security allowing you to optionally extend the HTTP header request with Digest and Signature header options.

Advanced Configuration Page for Adding the Digest Algorithm

To define the Digest HTTP Header security, you must select a digest algorithm in the HTTP Headers region of the Create Event Subscription - Invoke REST Service Advanced Configuration page, when defining the REST service invoker's event subscription.

The Digest HTTP Header has the following format:

Digest: <digest-algorithm>=<digest-value>

For example: Digest: sha-512=xxxxxxxxxxxxxx...

Signature HTTP Header

The Signature HTTP Header is part of the REST service security this framework supports. It lets you optionally add another layer of authentication before invoking the REST service. In this security model, the sender must authenticate itself with a digital signature produced by a private asymmetric key, such as rsa-sha256.

Advanced Configuration Page for Adding the Signature HTTP Header

When defining the REST service invoker's event subscription for the signature header security, you must select a value in the Signing Algorithm field of the Create Event Subscription - Invoke REST Service Advanced Configuration page.

Once the signing algorithm is selected in the HTTP Headers region, you must enter additional fields corresponding to the selected signing algorithm. This provides values for the following four components contained in the Signature header:

For example, a signature HTTP Header could be like:

Signature: keyId="xxxxxxxxxxxxxxxxxxxx... ", algorithm="rsa-sha512", headers="(request-target) host date digest", signature="xxxxxxxxxxxxxxxxx/xxxxxxx/xxxxx... "

The signature header or RSA-based signature is generated based on the headers to be signed and its value. The signing string is generated as:

        header1: value1\n
        header2: value2\n
        ..
        headerX: valueX

Then, the base64-encoded value of the RSA signature of the signing string is added as the signature component in the Signature HTTP Header.

Configuring REST Service Security with Customization Level

Similar to the behaviors of the customization level described in the SOAP service invocation framework, the REST service invocation framework handles the REST service security for user name, password, keystore file, keystore password, and certificate alias depending on the customization level in the invoker's event subscription:

When configuring REST service security, whether you can update or configure these security fields is based on the following conditions:

For information about usage examples of configuring REST service security with different customization levels, see Configuring Security Password with Customization Level.

Managing REST Service Invocation Errors

The REST service invocation framework leverages the Business Event System to manage errors and exceptions, similar to the error handling mechanism used in the SOAP service invocation framework.

For details on handling errors and exceptions, see Managing SOAP Service Errors.

If there is an error or exception, HTTP Return Status Code should be captured and available to the consuming program.

Understanding Implementation Consideration for the REST Service Invocation Framework

Oracle E-Business Suite Adapter with Oracle Integration has leveraged the REST service invocation framework for Business Event capabilities in integrations.

For the event subscriptions created automatically from Oracle E-Business Suite Adapter with Oracle Integration, in the Create Event Subscription page you can only update the values of the Status and Phase fields. All other fields in the page are displayed as read-only fields and are not updatable.

For more information about the Oracle E-Business Suite Adapter with Oracle Integration, see Using the Oracle E-Business Suite Adapter with Oracle Integration, available in the Oracle Cloud Library on the Oracle Help Center.