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.
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, 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:
This security mechanism authenticates the user invoking a Web service by passing a username and an optional password in the SOAP Header of a SOAP request sent to the Web service provider.
Please note that the username/password information discussed here is the concept of Oracle E-Business Suite username/password.
If the Web service that is invoked enforces Username/Password based authentication, then the service invocation framework also supports the UsernameToken based WS-Security header during Web service invocation.
Note: A SOAP request invoking a Web service should include a security header consisting of Username and plain text password. The password received as part of the SOAP request at run time 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.
Username is a clear text. Password is the most sensitive part of the UsernameToken profile. Service invocation framework supports the UsernameToken based WS-Security during service invocation with username 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>
The PasswordText password type is the password written in clear text. There is another password type called 'PasswordDigest' which is a base64-encoded SHA-1 hash value of the UTF8-encoded password and this type of password is not supported in this release.
<Nonce>: This element is a unique, random string that identifies the password. This helps protect the UsernameToken security from being reused during a replay attack.
<Created>: This element indicates the creation time of the security.
To easily maintain UsernameToken based security, service invocation framework allows you to configure the security password through the design-time user interface.
After entering Web service details in the Create Event Subscription - Invoke Web Service wizard, the Web Service Security region is displayed letting you specify or update username and password information if appropriate. The information will then be stored in Vault securely.
Oracle Workflow allows various levels of updates on business event. Each event and subscription is assigned a customization level that determines whether you can update the event definition. The customization level is used to protect Oracle E-Business Suite seed data and to preserve your customizations in an upgrade.
An event and subscription can have one of the following customization levels:
Core - No changes can be made to the event and subscription definition. This level is used only for events seeded by Oracle E-Business Suite.
Limit - The event status can be updated to Enabled or Disabled, but no other changes can be made to the event definition. This level is used only for the events seeded by Oracle E-Business Suite.
User - Any property in the event and subscription definition can be updated. This level is automatically set for events that you define.
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:
Customization Level - User
If invoker subscriptions with Customization Level User are created on the target environment, the complete definition is editable in that environment and also on environments to which the definition is uploaded.
While WS-Security Username can be created on one environment and moved to another, password has to be configured on each target environment before it can be used to invoke that Web service.
Customization Level - Limit or Core
If invoker subscriptions with Customization Level Limit or Core are uploaded to target environment, following are the options.
Username Configured
If username is configured for the Web service, Workflow Administrator can have access to Oracle Workflow Business Event Manager and the invoker subscription, and can update a password for that user in the target environment. This can be achieved by logging on to Oracle E-Business Suite with the Workflow Administrator Web responsibility. Select Business Events from the Navigator and choose Subscriptions in the horizontal navigation. Search and locate the invoker event subscription and then update the password.
Username cannot be updated.
Username Not Defined
Workflow Administrator can configure both username and password by accessing Workflow Business Event Manager.
Note: On the system side, Module and Key values to store the password in Vault are derived on the target environment.
Module - Module name for Vault will be derived from the business event and restricted to 30 characters.
Key - Key value for Vault will be derived from the business event and username.
The following information will be stored internally as part of the subscription definition if not already available for the invoker subscription:
WFBES_SOAP_USERNAME=<entered username>
WFBES_SOAP_PASSWORD_MOD=<derived module name>
WFBES_SOAP_PASSWORD_KEY=<derived key name>
Scenario 1:
Define a new business event and subscription at Customization Level - User in the source environment and have both Username 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 enviornment. The Username value is automatically populated and the Password value is not available. You can update the new Username (optional) and a corresponding password if needed.
Use the following steps to configure WS-Security in the target instance:
Perform all the steps described in the following topics to define a new event and subscription with security username and password:
Download the event and subscription using Workflow XML Loader and upload them to a target environment.
Note: The Workflow XML Loader is a command line utility that lets you upload and download XML definitions for Business Event System objects between a database and a flat file. For download and upload events using Workflow XML Loader, see:
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.
Click the Update icon for the subscription. All fields are updatable because of the customization level - 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 username defined earlier in the source environment in Step 1.
The Password value is not available.
You can update Username if desired and enter Password information for the Web service. Click Apply.
Scenario 2:
All Oracle E-Business Suite products provide seeded events and subscriptions with Customization Level - Limit or Core for service invocation. The Username may or may not be configured during the subscription creation for the product-specific seeded event to invoke Web service that requires WS-Security.
When using the seeded event and subscription in the target instance of Oracle E-Business Suite Release 12.2, configure the WS-Security by entering username, if not already provided by the subscription owner, and password for that user to be used for service invocation.
Solution:
In the Oracle E-Busines Suite Release 12.2 target instance, log on as a user with the 'Workflow System Administrator' role (such as sysadmin). The Username field is not updatable if the username is already provided by the subscription owner. You can always enter an associated password for the user to be used for service invocation.
Use the following steps to configure WS-Security in the target instance:
Log on 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.
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 username information if it is not part of the seeded subscription definition.
If username is entered by the Subscription owner as part of the seeded definition, this field would show the username value with no option to edit it. The user needs to only enter password.
Password: Enter password information 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.
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.
WFBES_SOAP_EXPIRY_DURATION
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.