26 Configuring WebCenter Content Web Services for Integration

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

This chapter includes the following sections:

For general information about web services that you can use with Content Server, see Section 25.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 32, "Configuring Web Services with WSDL, SOAP, and the WSDL Generator."

26.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.

26.1.1 Technologies for Web Services

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 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.

    Notes:

    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 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 the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

26.1.2 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 30, "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 at idcws/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.

GenericSoapService automatically has oracle/wsmtom_policy applied to it. Content Server cannot accept SOAP requests that have this policy applied. For GenericSoapService to work, the following policy must be applied to it:

oracle/no_mtom_policy

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 to IdcWebRequestService. If you want to use WS-Security with IdcWebRequestService, then apply it here. Content Server supports Oracle WSM policies for SAML and username-token.


26.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.

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.

Note:

GenericSoapService automatically has oracle/wsmtom_policy applied to it. Content Server cannot accept SOAP requests that have this policy applied. For GenericSoapService to work, the following policy must be applied to it:

oracle/no_mtom_policy

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

You can use Oracle Enterprise Manager 11g Fusion Middleware Control to apply Oracle WSM policies to web services. For more information, see "Attaching Policies to Web Services" in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.

26.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.

26.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 26.3.2, "Configuring JPS for WebCenter Content to Use the Keystore":

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

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.

26.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 <serviceProviders> element, or define one.

    A provider should be defined in this element by default. If not, you need to add a <serviceProvider> element that defines a provider, as Example 26-1 shows.

    Example 26-1 Service Provider Definition in jps-config.xml

    <serviceProviders>
      <serviceProvider type="KEY_STORE" name="keystore.provider"
          class="oracle.security.jps.internal.keystore.KeyStoreProvider">
          <description>PKI Based Keystore Provider</description>
          <property name="provider.property.name" value="owsm"/>
      </serviceProvider>
    </serviceProviders>
    
  2. Verify that a keystore instance is defined in <serviceInstances>.

    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 <serviceInstance> element that defines a keystore instance, as Example 26-2 shows.

    Example 26-2 Keystore Instance Definition in jps-config.xml

    <serviceInstances>
      <serviceInstance name="keystore" provider="keystore.provider"
          location="./default-keystore.jks">
          <description>Default JPS Keystore Service</description>
          <property name="keystore.type" value="JKS"/>
          <property name="keystore.csf.map" value="oracle.wsm.security"/>
          <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
          <property name="keystore.sig.csf.key" value="sign-csf-key"/>
          <property name="keystore.enc.csf.key" value="enc-csf-key"/>
      </serviceInstance>
    </serviceInstances>
    

    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 <jpsContexts> element.

    This setting should be in the jps-config.xml file by default. If not, you need to add the setting, as Example 26-3 shows.

    Example 26-3 Keystore in the JPS Context

    <jpsContext name="default">    <serviceInstanceRef ref="credstore"/>    <serviceInstanceRef ref="keystore"/>    <serviceInstanceRef ref="policystore.xml"/>    <serviceInstanceRef ref="audit"/>    <serviceInstanceRef ref="idstore.ldap"/></jpsContext>
    
  4. Save the jps-config.xml file, and restart the WebCenter Content Managed Server and the Administration Server, as described in Section 18.4, "Restarting Content Server to Apply a Component."

26.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 26-4 shows.

    Example 26-4 Creating a Client CSF with WLST Commands

    $ ./wlst.sh
    
    $ connect()
    
    $ createCred(map="oracle.wsm.security", key="keystore-csf-key", user="keystore", password="password")
    $ createCred(map="oracle.wsm.security", key="sign-csf-key", user="orakey", password="password")
    $ createCred(map="oracle.wsm.security", key="enc-csf-key", user="orakey", password="password")
    
  2. Use WLST createCred commands to define the CSF, as Example 26-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.

26.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 26-5 shows, and save the file.

    Example 26-5 Keystore and CSF Locations in the jps-config.xml file for a Java Client

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <jpsConfig
    xmlns="http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    schema-major-version="11" schema-minor-version="1" xsi:schemaLocation=
    "http://xmlns.oracle.com/oracleas/schema/11/jps-config-11_1.xsd
    jps-config-11_1.xsd">
     
     
    <serviceProviders>        
      <serviceProvider type="CREDENTIAL_STORE" name="credstoressp"
    class="oracle.security.jps.internal.credstore.ssp.SspCredentialStoreProvider">
                
    <description>SecretStore-based CSF Provider</description>        
      </serviceProvider>
      <serviceProvider type="KEY_STORE" name="keystore.provider"
    class="oracle.security.jps.internal.keystore.KeyStoreProvider">            
    <description>PKI Based Keystore Provider</description>
    <property name="provider.property.name" value="owsm"/>
    </serviceProvider>
    </serviceProviders>    
     
    <serviceInstances>        
      <serviceInstance name="credstore" provider="credstoressp" location="./">
    <description>File Based Credential Store Service Instance</description>
      </serviceInstance>              
      <serviceInstance name="keystore" provider="keystore.provider"
    location="./default-keystore.jks">
       <description>Default JPS Keystore Service</description> <property
    name="keystore.type" value="JKS"/>
    <property name="keystore.csf.map" value="oracle.wsm.security"/>
    <property name="keystore.pass.csf.key" value="keystore-csf-key"/>
    <property name="keystore.sig.csf.key" value="sign-csf-key"/>
    <property name="keystore.enc.csf.key" value="enc-csf-key"/>
      </serviceInstance>
    </serviceInstances>
     
    <jpsContexts default="default">        
      <jpsContext name="default">            
      <serviceInstanceRef ref="credstore"/>          
      <serviceInstanceRef ref="keystore"/>        
      </jpsContext>    
    </jpsContexts>
     
    </jpsConfig> 
    
  3. 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.