|Oracle® Fusion Middleware Administrator's Guide for Imaging and Process Management
11g Release 1 (11.1.1)
Part Number E12782-01
Oracle I/PM runs as a managed server within a WebLogic Server domain. Access to Oracle I/PM and the Oracle Content Server repository is controlled by WebLogic Server. System security, including SSL configuration, is handled through the WebLogic Server console. For additional information, see the following:
|Task||Where to Go For More Information|
|Administering Oracle WebLogic Server||Oracle Fusion Middleware Administrator's Guide|
|Administering Universal Content Management||See the following Oracle Universal Content Management guides:
You can configure Oracle Fusion Middleware to secure communications between Oracle Fusion Middleware components using SSL, which is an industry standard for securing communications. Oracle Fusion Middleware supports SSL version 3, as well as TLS version 1:
Table 2-3 SSL Documentation
|For Information On...||See The Following Guide...|
Configuring SSL with Oracle Fusion Middleware: Web Tier, Middle Tier, and Data Tier
Configuring SSL with Oracle WebLogic Server
To connect to a Content Server repository over SSL, the following steps must be taken:
Enable SSL on the Content Server Connection Content Server Settings Page
Add and configure an SSL incoming socket provider to the Content Server using the procedure described in "Configuring SSL Connection to Content Server Repository".
Oracle I/PM connects to BPEL at the following times, using different mechanisms for each:
Oracle I/PM connects to a BPEL server when application fields are mapped to BPEL payload elements. To connect, the provider, port, and credential information are passed using a BPEL JNDI-based API. Java Naming and Directory Interface (JNDI) and Enterprise JavaBeans use the T3 protocol, which is a WebLogic Server version of Remote Method Invocation (RMI). This API is used to enumerate the list of available composites, the web services exposed by each composite, and the WSDL URI for each service.
Once a composite and service are selected, the WSDL document is read from the server and parsed to obtain the list of available operations as defined by the service bindings in the WSDL. The protocol for reading the WSDL is HTTP and the address and port used are contained in part of the WSDL URI. Note that the address and port used may be different than the connection hostname and port if the BPEL server is configured with an HTTP front end load balancer such as Oracle HTTP Server (OHS).
Once read, the WSDL is used to obtain the schema of the operation payload so that application fields can be mapped to it.
Details of the connection, composite name, service name, operation name, and application field to payload mapping are stored in the Application.BpelConfig section for use at runtime.
Runtime communication occurs when BPEL Agent has received a notification that a document has been created in Oracle I/PM and a BPEL process instance must be created for the document. For this communication, the connection, composite, and service name stored in BpelConfig is first used through the BPEL JNDI/EJB API to obtain the service WSDL URI.
The WSDL URI is read to obtain the operation payload schema. The payload schema is used to construct the XML for the payload and the application field values are then inserted into the XML as defined by the mapping.
Once the payload is fully defined to include the mapped field values, the payload is submitted to the BPEL service operation as a web service call using the address as specified in the WSDL document. The web service call is submitted using the HTTP protocol.
The first step in configuring the Oracle I/PM-BPEL integration is to create a connection definition for the BPEL system within Oracle I/PM. The procedure for creating a BPEL connection is detailed in "Creating a BPEL Connection".
It is important to understand that the connection is used when connecting through the BPEL EJB API, so the information is used to communicate though the T3 protocol and not HTTP.
The parameters required for the configuration are described as follows:
|Provider||Specifies the hostname or names used for the connection. If the BPEL server is a single instance, it is the machine name or IP of the BPEL machine. If the BPEL server is operating within a cluster, this may be a comma separated list of machine names or IP addresses of servers in the cluster or it may be the cluster name.
If multiple machines provided in a comma separated list, they must all be defined to use the same port as supplied by the port parameter. If the BPEL server instance in the cluster needs to be defined with different ports, then the cluster name configuration must be used.
When the cluster name is used, the cluster name must be defined in domain name server to resolve to the multiple machines within the cluster. Neither Oracle I/PM nor BPEL defines this behavior. Rather, it is defined by the WebLogic support for JNDI in a cluster. For details on clustered JDNI support, see the section “Using WebLogic JNDI in a Clustered Environment” in the Oracle Fusion Middleware Programming JNDI for Oracle WebLogic Server guide.
|Port||This specifies the port number used in the connection. For WebLogic, this is the standard listening port for the server. If the SSL option is enabled, then the port provided must be the SSL listening port for the server and T3 communication will use T3S, the SSL version of T3.|
|SSL||This indicates whether or not the port parameter is the SSL listening port of the BPEL server.|
|Credential Alias||Provides the alias of a user name and password that are stored in the Credential Store Framework (CSF). These credentials are required to make the remote JNDI connection. The parameter is not the actual user name or password, but rather an alias, or key used to look up the user name and password in the CSF, which encrypted them to provide for proper security.
The credential must be created in the CSF before the BPEL connection configuration can be completed. A credential can be created in the CSF in one of two ways: through Enterprise Manager (EM) or through WebLogic Scripting Tool (WLST).
The Oracle I/PM integration can be configured to use SSL to secure communications with the BPEL server instance. The procedure for enabling and configuring an SSL connection to a BPEL server is detailed in "Configuring SSL for the BPEL Server".
Working with the Default Demo Credential Store Framework and Credential Certificates
Once SSL is enabled on the BPEL server instance, T3 communication to the server will work properly for testing if both BPEL and Oracle I/PM servers are configured to use the default DemoTrust certificates, because WebLogic configures a specific self-signed demo certificate and trust configuration when it is installed. These files are located in $WL_HOME/server/lib and are named DemoIdentity.jks and DemoTrust.jks. By default, WebLogic is configured to use these files.
Note:These files should be used for test and demonstration purposes only. In a production environment, you should obtain proper and valid certificates and follow appropriate procedures for importing and configuring those certificates to establish identity and trust. When properly signed certificates are used and configured properly, SSL will work properly without special configuration.
You can use the demo certificate to test and confirm a BPEL SSL connection. The SSL configuration allows Oracle I/PM to enumerate the composites and services, but when Oracle I/PM goes to read the WSDL, it will fail. This is because two SSL stacks are being used within the server:
The WLS SSL stack, which is integrated with the demo identity and trust configuration, is used for T3 communication.
The native Java SSL stack, which is not integrated with the WebLogic demo identity and trust configuration, is used by the WSLD reader, which uses a native Java API.
To make the WSDL reader work, the Java SSL stack on the Oracle I/PM server instance must be told to trust the self-signed certificate on the BPEL server.
To do this, the javax.net.ssl.trustStore system property must be set on the Oracle I/PM managed server JVM to point to the SSL trust store. To configure this to point to the DemoTrust.jks, add the following to the JAVA_OPTIONS in the setDomainEnv script:
After pointing to the DemoTrust.jks, restart the managed I/PM server.
This works because all WebLogic Server shares use the same DemoTrust.jks file.
At runtime, there is still a potential that when WebLogic is installed and automatically generates an identity keystore (DemoIdentity.jks), the identity is keyed to the machine name. In some cases, the identity may only be hostname with no domain (so, sta00319, not sta00319.us.oracle.com). When Oracle I/PM goes to send the BPEL process message, WebLogic performs hostname verification as part of its SSL handshake that attempts to validate that the hostname in the HTTPS request matches the identity to the server. However, the URL that the BPEL system is giving is full DNS name, not just the hostname. So the handshake fails verification and the communication fails.
The simplest solution for demo purposes is to disable host name verification on the Oracle I/PM system. This is probably the easiest solution, but not a real world production solution. The procedure for this is documented here:
Configuring New CSF Credentials
You can also create self-signed CSF credentials instead of using the default demo credentials. For information on configuring a CSF credential for a BPEL connection, see "Configuring a BPEL Connection CSF Credential".
WebLogic Web Services are implemented according to the Web Services for Java EE 1.2 specification, which defines the standard Java EE runtime architecture for implementing Web Services in Java. The specification also describes a standard Java EE Web Service packaging format, deployment model, and runtime services, all of which are implemented by WebLogic Web Services.
Table 2-4 Web Services Documentation
|For Information On...||See The Following Guide...|
Web Services consumed by JAX-WS clients
Oracle Fusion Middleware Getting Started with JAX-WS Web Services for Oracle WebLogic Server
Apply OWSM security to Web Services
Use MTOM with Web Services
Invoke secured Web Service from BPEL
Invoke Web Service using Oracle Server Bus
Invoke Web Service using Oracle Enterprise Server Bus
Access to Oracle I/PM through web services is controlled by Oracle Web Services Manager (OWSM) policies. Policies are configured through the WebLogic Server console. Some policies require a keystore be defined. For example, Oracle I/PM must use access credentials stored in Credential Store Framework (CSF) to communicate with a BPEL server or to use SSL. Keystores can be defined using Keytool from the Java Development Kit. Credentials can be added to defined keystores using WebLogic Scripting Tool (WLST).
Oracle Web Services Manager is designed to be flexible by allowing the end user to define the security policy that will be used rather than to have them predefined.
When no policy is applied, the services default to using Http Basic Auth security. Http Basic Auth passes user credentials in the HTTP header in the Authorization field. The value of this field contains a base64 encode of the username and password. The BasicUserToken client class is intended to use this form of authentication. Because the password is transmitted unencrypted when using basic authentication, Oracle I/PM includes a configuration MBean called RequireBasicAuthSSL, allowing the service to require that SSL be used with this form of authentication.
For more robust security, OWSM polices can be applied to the services. OWSM policies can enforce various ws-security token usage, including message level encryption, transport level encryption, or supplying credentials in the SOAP header rather than HTTP header. Because SSL can be specified as part of the applied policies, the RequireBasicAuthSSL MBean setting does not apply when security policies are in use.
During domain creation, the Oracle I/PM application is supplied with a default deployment plan defined in the applications directory, although this plan is not yet assigned to the deployment. The default plan uses the wss_username_token_service_policy which enforces simple username and password in the ws-security soap header and requires no encryption. This default plan assigns the wss_username_token_service_policy to all Oracle I/PM services.
To assign the default plan, do the following:
Login to the WebLogic Server Console.
Click Deployments, enable imaging in the Deployments table, then click Update. The Update Application Assistant is displayed.
Click Change Path next to Deployment plan path. Changing the source path does not redeploy with a new plan.
Using the links in the Current Location field, browse to $MW_HOME/user_projects/applications/<domain_name>/server/ipm and enable the Plan.xml file.
Continue through the wizard to complete the deployment.
Once this process is complete, services all have the wss_username_token_service_policy applied.
If you want to change the policies at runtime, do the following:
Login to WebLogic Server console
Click Deployments and then expand imaging in the Deployments table. A list of Oracle I/PM web services is displayed. You may need to scroll to see them.
Click the service name for each service you want to configure and do the following:
Note:No policy should ever be applied to the DocumentContentService service.
Select the Configuration tab
Select the Ws-Policy tab. The currently applied policy is displayed.
Click the service end point. For example, the ApplicationServicePort. A listing of Available Message Policies and Chosen Message Policies is displayed.
Select the currently applied policy from the Chosen Message Policies list on the right and click the arrow to move it to remove it from the Chosen Message Policy list.
Select the preferred policy from the Available Message Policies list on the left and click the arrow to move it to the Chosen Message Polices list on the right.
Note:You need to apply the same policy to all Oracle I/PM services with the exception of DocumentContentService. No policy should be applied to the DocumentContentService service.
When changes are made to all services, update the deployment with the newly edited plan.
Enable imaging in the Deployments table on the main deployments page, then click Update. The Update Application Assistant is displayed.
Check the top option to update only the deployment plan.
To facilitate deployment, alternative deployment plan descriptors have been created. The are located in $MW_HOME/user_projects/applications/<domain_name>/server/ipm/plan/imaging-ws.war/WEB-INF directory. You can copy any one of the policy-<X> files on to weblogic-webservices-policy.xml in that same directory, and then update the deployment with the plan. Note that for the default plan, weblogic-webservices-policy.xml = policy-username_token.xml.
It is important that all services be assigned the same policies. In the client API the ServicesFactory is coded to obtain the appropriate client policy from the provide UserToken. along with the required configuration parameters for the policy, and use that client policy configuration on all service interfaces. In order to work, client code must know what service policy is in effect. The following are examples of how to code the client for each of the predefined policy types within the UserToken class.
The UserToken class exposes a number of new properties to facilitate configuring client side policies. The set of parameters exposed is a subset of the full set of possible Oracle Web Service Manager parameters, but is commonly used. Note that the properties are wrappers around a name/value pair map which is directly exposed using the securityParameters property. All properties in this map get passed along to the web service request context and therefore any OWSM policy is usable.
The following examples are detailed here:
Example 2-1 No Policy: Http Basic Auth
The simplest and the default. Because this is the default the BasicUserToken provides the client implementation.
UserToken userToken = new BasicUserToken("weblogic", "weblogic"); ServicesFactory.login(userToken, wsurl);
BasicUserToken is functionally equivalent to the following.
UserToken userToken = new UserToken(); userToken.setUserName("weblogic"); userToken.setPassword("weblogic");
When OWSM policies are applied to the services, the WsmUserToken is used to provide the client side policy configurations. This is done as follows for various policies.
Example 2-2 Policy: wss_username_token_client_policy
This is the simplest policy.
WsmUserToken userToken = new WsmUserToken ("weblogic", "weblogic"); userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_POLICY); ServicesFactory.login(userToken, wsurl);
Example 2-3 Policy: wss11_username_token_with_message_protection_client_policy
Message_protection policies provide message level encryption. However to make them work, client and server keystores need to be configured. See the section "Working With Keystores" for how to create and configure the key stores. When a keystore is used client side by a JSE client, the client code needs to configure the location, type, and password for the keystore. The client side keystore must contain a RecipientAlias which is the key used to encrypt the message sent to the server. This same key must exist server side to decrypt and encrypt the responses.
WsmUserToken userToken = new WsmUserToken ("weblogic", "weblogic"); userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY); userToken.setKeystore(".\\config\\default-keystore.jks", "JKS", "welcome"); userToken.setRecipientAlias("orakey");
If this policy were being used server side, for example, from a web app or servlet, the key store would be configured underneath JPS security and therefore the client would not need to specify the keystore configuration parameters. This behavior can be replicated in JSE as well by setting the oracle.security.jps.config environment property to point to a jps-config file.
System.setProperty("oracle.security.jps.config", ".\\config\\jps-config.xml"); WsmUserToken userToken = new new WsmUserToken ("weblogic", "weblogic"); userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY);
Once JPS is configured for the client, you can also leverage the Credential Store Framework (CSF) to define the username and password credentials. See the section "Working with the CSF through WLST". To use, create the credentials on the server and copy them to your client. You can use any alias in the credential store, but the standard default is the alias basic-credentials.
System.setProperty("oracle.security.jps.config", ".\\config\\jps-config.xml"); WsmUserToken userToken = new WsmUserToken (); userToken.setClientPolicy(WsmUserToken.USERNAME_TOKEN_MP_POLICY); userToken.setCsfKey("basic.credentials");
Example 2-4 Policy: wss10_saml_token_client_policy
This policy is similar to username token but only the passes the username in the saml token header. Also, its not encrypted and therefore not secure.
WsmUserToken userToken = new WsmUserToken ("weblogic"); userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_POLICY);
Example 2-5 Policy: wss11_saml_token_with_message_protection_client_policy
This option encrypts and signs the message using keys and certificates from the keystore. This is the most secure of all the options and requires the most configuration. Typically, service-side code has the user identity in the form of a java.security.Principal object. So server-side code might look as simple as the following.
WssUserToken userToken = new WssUserToken (principal.getUserName(); userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY); ServicesFactory.login(userToken, wsurl);
For JSE, the jps configuration trick works here as well.
System.setProperty("oracle.security.jps.config", ".config\\jps-config.xml"); WssUserToken userToken = new WssUserToken ("weblogic"); userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY);
Without JPS configuration, the client can provide the full set of keys. Since this seems like an extreme use case, the UserToken does not provide full access to all of the key properties required by the policy. This demonstrates how any policy parameters can be supplied through the securityParameters property.
WssUserToken userToken = new WssUserToken (); userToken.setUserName("weblogic"); userToken.setClientPolicy(WsmUserToken.SAML_TOKEN_MP_POLICY); userToken.setKeystore(".\\config\\default-keystore.jks", "JKS", "welcome"); userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_ENC_KEY_ALIAS, "orakey"); userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_ENC_KEY_PASSWORD, "welcome"); userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_SIG_KEY_ALIAS, "orakey"); userToken.getSecurityParameters().put(SecurityConstants.ClientConstants.WSS_SIG_KEY_PASSWORD, "welcome");
In these configuration examples, the same key is used in all cases. In a production environment, the keystore should contain client and service-side certificates or signing and encrypting respectively.
For any of the message_protection policies, client and server keystores need to be configured. In a production environment, you should obtain proper and valid certificates and follow appropriate procedures for importing and configuring those certificates to establish identity and trust. This example is meant to provide a workable solution for development and testing. You can create a keystore using a build in JDK tool called KeyTool. You use the following command to generate a keystore.
>keytool -genkey -alias orakey -keyalg RSA -keystore default-keystore.jks Enter keystore password: ß welcome Re-enter new password: ß welcome What is your first and last name? [Unknown]: Joe Smith What is the name of your organizational unit? [Unknown]: Human Resources What is the name of your organization? [Unknown]: Our Company What is the name of your City or Locality? [Unknown]: What is the name of your State or Province? [Unknown]: What is the two-letter country code for this unit? [Unknown]: US Is CN=Joe Smith, OU=Human Resources, O=Our Company, L=Unknown, ST=Unknown, C=US correct? [no]: yes Enter key password for <orakey> (RETURN if same as keystore password): ß RETURN...so welcome >
You can list keys in a keystore with
> keytool -list -keystore default-keystore.jks
The above example creates the single common key used in all of the examples above. The same default-keystore.jks was used on both the server and the client.
The following command can be used from WLST to add credentials into the keys store. However, to use these commands, you have to run WLST from the $ORACLE_HOME/common/bin directory rather than from the WLS home common/bin. In JDeveloper, this is located in Oracle/Middleware/jdeveloper/common/bin and not Oracle/Middleware/wlserver_10.3/common/bin. From the $ORACLE_HOME/common/bin, run wlst.sh (Linux) or wlst.cmd (Windows) and the run connect().
The full set credential store commands are documented in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference, but the main two used in these examples are:
createCred(map="oracle.wsm.security", alias="<alias>", user="<user>", password="<pwd>")
The credential store can store any userid and password pair accessed by an alias. For WSM policies, the acsf aliases are used to obtain keystore aliases and passwords. These CSF aliases are configured in the jps-config.xml file in the following element.
<!-- KeyStore Service Instance --> <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="enc-csf-key"/> <property name="keystore.enc.csf.key" value="enc-csf-key"/> </serviceInstance>
The keystore needs one alias named keystore-csf-key that includes the password for the key store. In this example, it is the first password entered in the keytool, above. The username here is ignored. Then the keystore needs a second alias named enc-csf-key. The username is a keystore alias and the password is the private password for that keystore alias, which is the second password in the keytool, above.