Oracle WebCenter Content Web Services for Integration

This chapter describes how to use Oracle WebCenter Content web services with Oracle WebLogic Server web services to integrate a client application with Oracle WebCenter Content Server.

This chapter includes the following sections:

• Section 19.1, "About Configuring WebCenter Content Web Services for Integration"
• Section 19.2, "Configuring Web Service Security Through Web Service Policies"
• Section 19.3, "Configuring SAML Support"

For general information about web services that you can use with Content Server, see Section 18.2, "Overview of Web Services."

The way to use web services described in this chapter was introduced in Oracle Universal Content Management 11g. If you want to use the way introduced in Oracle Universal Content Management 10g, with Web Services Definition Language (WSDL) and SOAP (Simple Object Access Protocol) files and the WSDL generator, see Section 25, "Configuring Web Services with WSDL, SOAP, and the WSDL Generator."

19.1 About Configuring WebCenter Content Web Services for Integration

WebCenter Content web services work with Oracle WebLogic Server web services to perform management functions for Content Server. Oracle WebLogic Server web services provide SOAP capabilities, and WebCenter Content web services include several built-in SOAP requests. WebCenter Content web services are automatically installed with Content Server, but they require additional configuration to set up security.
The core enabling technologies for WebCenter Content web services follow:

• SOAP (Simple Object Access Protocol) is a lightweight XML-based messaging protocol used to encode the information in request and response messages before sending them over a network. SOAP requests are sent from WebCenter Content web services to Oracle WebLogic Server web services for implementation. For more information about SOAP, see Simple Object Access Protocol (SOAP) at http://www.w3.org/TR/soap12.
• Web Services Security (WS-Security) is a standard set of SOAP extensions for securing web services for confidentiality, integrity, and authentication. For WebCenter Content web services, WS-Security is used for authentication, either for a client to connect to the server as a particular user or for one server to talk to another as a user. For more information, see the OASIS Web Service Security web page at http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss.
• Web Service Policy (WS-Policy) is a standard for attaching policies to web services. For WebCenter Content web services, policies are used for applying WS-Security to web services. The two supported policies are username-token security and SAML security.
  Historically, Oracle used Oracle Web Services Manager (Oracle WSM) to secure its web services, and Oracle WebLogic Server used Web Services Security Policy (WS-SecurityPolicy) to secure its web services. Because web services security is partially standardized, some Oracle WSM and WS-SecurityPolicy policies can work with each other.
  
  Note:

  Use Oracle WSM policies over Oracle WebLogic Server web services whenever possible. You cannot mix your use of Oracle WSM and Oracle WebLogic Server web services policies in the same web service.
  WebCenter Content web services (idcws/ as context root) are SOAP based, while WebCenter Content native web services (idcnativews/ as context root) are JAX_WS based. Both kinds of web services can be assigned Oracle WSM policies through the Oracle WebLogic Server Administration Console.
  The generic WebCenter Content web services are JAX-WS based and can be assigned Oracle WSM policies and managed by Oracle WSM. The native WebCenter Content web Services are SOAP based and can only support WS-Policy policies managed through the Oracle WebLogic Server Administration Console.
  For more information about Oracle WSM, see the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
  A subset of Oracle WebLogic Server web services policies interoperate with Oracle WSM policies. For more information, see "Interoperability with Oracle WebLogic Server 11g Web Service Security Environments" in the Oracle Fusion Middleware Interoperability Guide for Oracle Web Services Manager.
  Web Services Security Policy (WS-SecurityPolicy) is a set of security policy assertions for use with the WS-Policy framework. For more information, see the Web Services Security Policy (WS-SecurityPolicy) specification at http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html.
• SAML is an XML standard for exchanging authentication and authorization between different security domains. For more information, see the Security Assertion Markup Language (SAML) specification at http://docs.oasis-open.org/security/saml/v2.0/.
• WebLogic Scripting Tool (WLST) is a command-line tool for managing Oracle WebLogic Server. For more information, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

19.1.1 WebCenter Content Web Services

WebCenter Content provides two types of web services: a general (generic) JAX-WS based web service, and a native SOAP based web service. The two types of web services reside in two different context roots. The context root is the primary identifier in the URL for accessing the web services.
The context roots follow:

• idcws
  Use this context root for general access to Content Server through any regular web services client.
• idcnativews
  The Remote Intradoc Client (RIDC) uses the native web services. Oracle recommends that you do not develop a custom client against these services. For more information about RIDC, see Chapter 23, "Using RIDC to Access Content Server."

The following table describes the WebCenter Content web service in the idcws context root.

WebCenter Content Web Service

Descriptions

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 Content Server when you set IsSoap=1. For details of the format, see the published WSDL atidcws/GenericSoapPort?WSDL.You can apply WS-Security to GenericSoapService through WS-Policy. Content Server supports Oracle WSM policies for 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.

The following table describes the WebCenter Content web services in the idcnativews context root.

WebCenter Content Web Services	Descriptions
IdcWebRequestService	This is the general WebCenter Content service. Essentially, it is a normal socket request to Content Server, wrapped in a SOAP request. Requests are sent to Content Server using streaming Message Transmission Optimization Mechanism (MTOM) in order to support large files.Streaming MTOM and WS-Security do not mix. As a result, do not apply WS-Security to this service because it will break the streaming file support. In order to achieve security, you must first log in using the IdcWebLoginService, then use the same JSESSIONID received from that service in the next call to IdcWebRequestService as a cookie.
IdcWebLoginService	This service is solely for adding security to IdcWebRequestService calls. There are no parameters for this service; it simply creates a session. The important field to retrieve is the JSESSIONID value for future calls toIdcWebRequestService. If you want to use WS-Security with IdcWebRequestService, then apply it here. Content Server supports Oracle WSM policies for SAML and username-token.

19.2 Configuring Web Service Security Through Web Service Policies

The WebCenter Content web services are installed and ready to use by default with the WebCenter Content EAR. However, unless you configure web service security (WS-Security) on any of the WebCenter Content web services, all connections to Content Server will use the anonymous user. To configure security for WebCenter Content web services, you configure WS-Security through WS-Policy. Additional configuration is required to enable authentication.

19.2.1 Configuring WS-Security through WS-Policy

WS-Security is set through the use of web service policies (WS-Policy). Security policies can be set for web services to define their security protocol. In particular, the WebCenter Content web services support Oracle WSM policies.
WebCenter Content supports two general classes of policies, username-token and SAML, and the following Oracle WSM policies:

• oracle/wss11_saml_token_with_message_protection_service_policy
• oracle/wss11_username_token_with_message_protection_service_policy

To configure WS-Security through WS-Policy:

1. Access the Oracle WebLogic Server Administration Console.
2. Select Deployments from the side panel.
3. Expand either WebCenter Content Native Web Services or WebCenter Content Web Services in the Deployments table.
4. Click the name of a web service, such as GenericSoapService
5. Click the Configuration tab on the Settings page for the web service, and then click the WS-Policy tab.
6. Click the main service. From here you can choose which Oracle WSM policies to add.
7. When you have finished adding Oracle WSM policies, you need to update the WebCenter Content native web services or the WebCenter Content generic web services to save your additions.

19.3 Configuring SAML Support

You can also provide SAML support for client-side certificate authentication. To provide SAML support so that the client can be the identity provider (that is, assert credentials), you need to configure a keystore, configure a Java Platform Security (JPS) provider to use the keystore, create a client credential store (CSF), and configure a Java client to use the keystore and CSF.

19.3.1 Configuring a Keystore

Both the server and client need a copy of a keystore. The server uses the keystore to authenticate the credentials passed by the client. A self-signed certificate can work for this situation, because the keystore is used only as a shared secret. You can use the keytool utility to generate a self-signed certificate. Many of the values in the following example are the default values for the domain's config/fmwconfig/jps-config.xml file, described in Section 19.3.2, "Configuring JPS for WebCenter Content to Use the Keystore":

$ keytool -genkey -alias orakey -keyalg RSA -keystore default-keystore.jks -keypass welcome -storepass welcome

You can enter any relevant data in the keytool command. The specifics do not matter except for the passwords for the keystore and the certificate, which the client uses.

19.3.2 Configuring JPS for WebCenter Content to Use the Keystore

Configuring the keystore in an Oracle WebLogic Server domain involves editing the DomainHome/config/fmwconfig/jps-config.xml file.

To configure JPS for WebCenter Content to use the keystore:

1. Verify that a provider is defined in the  element, or define one.
   A provider should be defined in this element by default. If not, you need to add a  element that defines a provider, as Example 19-1 shows.
   
   Example 19-1 Service Provider Definition in jps-config.xml

   
     
         PKI Based Keystore Provider
         
     
   
   

2. Verify that a keystore instance is defined in .
   A keystore instance should be defined by default.
   A keystore instance should be defined in this element by default. If not, you need to add a  element that defines a keystore instance, as Example 19-2 shows.
   
   Example 19-2 Keystore Instance Definition in jps-config.xml

   
           Default JPS Keystore Service                                
   
   

   The location of the keystore instance must be set to the same location as where you created the keystore.
3. Verify that a reference to the keystore is in the  element.
   This setting should be in the jps-config.xml file by default. If not, you need to add the setting, as Example 19-3 shows.
   
   Example 19-3 Keystore in the JPS Context

4. Save the jps-config.xml file, and restart the WebCenter Content Managed Server and the Administration Server, as described in Section 15.4, "Restarting Content Server to Apply a Component."

19.3.3 Creating a Client CSF

On the client, there must be a credential store to store the keys to unlock the keystore. Oracle WebLogic Server provides a variety of ways to create a Credential Store Framework (CSF). One way you can create a CSF is with Oracle WebLogic Server Scripting Tool (WLST) commands.

To create a client CSF

1. Connect to the Oracle WebLogic Server domain, as Example 19-4 shows.
   
   Example 19-4 Creating a Client CSF with WLST Commands

   $ ./wlst.sh
   
   $ connect()
   
   $ createCred(map="oracle.wsm.security", key="keystore-csf-key", user="keystore", password="welcome")
   $ createCred(map="oracle.wsm.security", key="sign-csf-key", user="orakey", password="welcome")
   $ createCred(map="oracle.wsm.security", key="enc-csf-key", user="orakey", password="welcome")
   

2. Use WLST createCred commands to define the CSF, as Example 19-4 shows.
   Change the values in the example to match the alias and passwords from the keystore you created.
   WLST creates a CSF wallet at DomainHome/config/fmwconfig/cwallet.sso. You can use the wallet only on the client.
3. Exit from WLST, and restart the Administration Server for the domain.
4. Send a copy of the wallet to the client.

19.3.4 Configuring a Java Client to Use the Keystore and CSF

Before you can configure a Java client to use the keystore and CSF, the client must have these items:

• A copy of the keystore
• A copy of the CSF wallet
• A client version of the jps-config.xml file

To configure a Java client to use the keystore and CSF:

1. Edit the jps-config.xml file for the Java client.
2. Add the locations of the keystore and the CSF wallet, as Example 19-5 shows, and save the file.
   
   Example 19-5 Keystore and CSF Locations in the jps-config.xml file for a Java Client

                           SecretStore-based CSF Provider                                   PKI Based Keystore Provider                                    location="./"

> File Based Credential Store Service Instance location="./default-keystore.jks"> Default JPS Keystore Service

Set oracle.security.jps.config, a Java system property, to point to the jps-config.xml file:

System.setProperty("oracle.security.jps.config", “jps-config.xml”);

You can set this location in the client, during execution.