Using Fusion Middleware Enterprise Manager to Test UCM Web Service GenericSoapService (GenericSoapPort)
(Doc ID 1334114.1)
Last updated on JULY 31, 2018
Applies to:Oracle WebCenter Content - Version 18.104.22.168.0 and later
Information in this document applies to any platform.
Web services in UCM 11g differs from the model of web services in UCM 10g. In 10g the WSDLGenerator component was used. In 11g, several significant improvements to the 10g model of UCM web services have replaced the 10g model:
Using a single WSDL (GenericSoapService), customers can call any UCM service. Customers no longer need to create WSDLs to run specific services. In 10g, a WSDL needed to exist for Checkin, Search, etc, and any service not included in the component required customers to create a separate WSDL. In 11g, this overhead does not exist. This allows for greater code re-use, fewer configuration needs, and faster implementation.
The JAX-WS standard is supported. (Java API for XML Web Services). All major IDEs have built-in support for JAX-WS.
- More sophisticated security options are available for securing requests and responses to UCM web services. WS-Security can be applied using WS-Policies.
- One-shot calling to web services. Using WS-Policy, can reduce the load and traffic to the web server. In 10g UCM, when calling UPDATE_DOCINFO via SOAP, two lines would appear in the Apache access log. A "401 Unauthorized" forced an authorization challenge, followed by a "200 OK" for the update call. This meant that two HTTP requests were always needed in 10g to call web services. A 10g Apache access log looked like this:
Oracle UCM 11g provides a general (generic) JAX-WS based Web service called "GenericSoapService".
This service uses a generic format similar to HDA for its SOAP format. It is almost identical to the generic SOAP calls that you can make to the Oracle UCM Content Server when you set IsSoap=1. Details of the format can be found in the published WSDL at /idcws/GenericSoapPort?WSDL.
You can apply WS-Security to GenericSoapService through WS-Policy, which will be expanded upon in this note. The Content Server supports Oracle Web Services Manager (OWSM) policies for Security Assertion Markup Language (SAML) and username-token.
As a result of allowing WS-Security policies to be applied to this service, streaming Message Transmission Optimization Mechanism (MTOM) is not available for use with this service. Very large files (greater than the memory of the client or the server) cannot be uploaded or downloaded.
Customers that wish to use the UCM GenericSoapService (GenericSoapPort) web service with UCM can verify that their SOAP envelope and security settings are valid using Fusion Middleware Enterprise Manager. Details on testing this way follow an introduction about security options for use with GenericSoapService.
WS-Security options with GenericSoapService
Initially there is not a policy on the service GenericSoapService, which means all request act as anonymous. This is suitable for some customers but others may require WSS security headers, or SAML policies, or other policy. Adding a policy adds security to the web service. The following is from the UCM Developer's guide, Section 7.3:
"The Oracle UCM Web services are installed and ready to use by default with the Oracle UCM EAR. However, unless you configure WS-Security on any of the Oracle UCM Web services, all connections to the Oracle UCM content server will use the anonymous user. Additional configuration is required to enable authentication."
Link to the developer's guide portion on Web Services: http://download.oracle.com/docs/cd/E14571_01/doc.1111/e10807/web_services.htm#CHDDIJJB
To use any policy, OWSM (Oracle Web Services Manager) must be installed in the domain where UCM is located. Without OWSM, no policies will be available, and GenericSoapService can only be used with the anonymous or guest access. To enable OWSM, create or extend the domain according to the instructions in the following note. This must be done before proceeding in applying WS-Security to GenericSoapPort for UCM.
<Note.1332250.1> - Creating a UCM Domain With OWSM Enabled
An overview of supported polcies in UCM 11g:
No policy (default)
All connections to the Oracle UCM content server will use the anonymous user. If any service is called that doesn't allow anonymous, errors will be returned from UCM with the following StatusMessage: "System needs login authentication credentials."
The default of no policy is very limited in what services can be used. It is essentially only for calling services as a guest or public user of UCM.
In 22.214.171.124, an additional policy must be added otherwise the GenericSoapService will fail. This policy is only needed if running 126.96.36.199 or later. When attaching policies, always add the policy "oracle/no_mtom_policy" as well. This is because in 188.8.131.52, the oracle/wsmtom_policy policy will be automatically applied, thus the need to use no_mtom_policy to remove that default. If the no_mtom_policy is not applied to GenericSoapService, a "java.lang.RuntimeException: OWS-12015" error can occur when invoking the service. In addition, the error "java.io.IOException: File has already been opened in streaming mode" will occur. Bug 14137878 was opened regarding the need to add the no_mtom_policy.
This is the simplest policy to apply, that allows SOAP client to use the WSS Username Tokens in the header of the SOAP request. This option requires no keystore to be created. This option is most like the 10g variety of UCM web services.
Policy Description: This policy uses the credentials in the UsernameToken WS-Security SOAP header to authenticate users. Only plain text mechanism is supported. The credentials are authenticated against the configured identity store. This policy can be attached to any SOAP-based endpoint.
If OWSM is installed in the domain, this policy can be applied to GenericSoapPort as described in the following note.
<Note.1332300.1> - Setting up GenericSoapService in UCM 11g to use WS-Security
For this policy, a keystore is needed. See the following note for steps on creating a keystore for use with UCM 11g and web services.
<Note.1334029.1> - Configuring a Keystore in UCM 11g for Use With Web Services
Policy Description: This policy provides message-level protection and authentication for outbound SOAP requests in accordance with the WS-Security 1.1 standard. Messages are protected using WS-Security's Basic 128 suite of symmetric key technologies, specifically RSA key mechanisms for message confidentiality, SHA-1 hashing algorithm for message integrity, and AES-128 bit encryption. The keystore on the client side is configured either on a per-request basis or through the security configuration. Credentials are included in the WS-Security UsernameToken header of outbound SOAP request messages. Only plain text mechanism is supported. Credentials are provided either programmatically through the current Java Authentication and Authorization Service (JAAS) subject or by a reference in the policy to the configured credential store. This policy can be attached to any SOAP-based client.
An example of using a JAX-WS client to call GenericSoapPort with this policy applied can be seen in the following note:
<Note.1332308.1> - Calling GenericSoapService with WS-Security settings in JDeveloper using a Web Service Proxy
To view full details, sign in with your My Oracle Support account.
Don't have a My Oracle Support account? Click to get started!