| Oracle® Retail Integration Bus Installation Guide Release 15.0.2 E90690-01 |
|
 Previous |
 Next |
The RIB Integration Gateway Services (IGS) component is an optional sub system and should be installed only after the core RIB components have been installed and verified.
The IGS provides an integration infrastructure for external (third party) system connectivity to the Oracle Retail Integration Bus (RIB) in the form of a tested set of Web service providers and the configurations to connect to RIB. So it should be installed only if there is a requirement to do so.
The RIB Integration Gateway Service (IGS) component requires Oracle WebLogic Server 12.2.1.2 and Java 8.
Before installation, read the RIB Implementation Guide for the considerations and planning steps needed for the RIB IGS deployment to WebLogic Server. Also make sure $JAVA_HOME is pointing to Java 8.
The installation and base configuration of the Oracle WebLogic Server is beyond the scope of this document. Work with the Oracle WebLogic Server administration team to determine the physical and logical placement of the RIB IGS component within the WebLogic Server deployment.
This section describes the process of preparing the Oracle WebLogic Server to install the igs-service.
IGS ear file should be deployed to a separate managed server.
When naming the WebLogic instance, it is recommended (but not required) that the .ear file name is used (without the extension), along with underscore,
_server.
For example, if the .ear file name is igs-service.ear, the instance name would be igs-service_server.
Add the server start argument for IGS managed server. This can be done from the WLS console, or in the startWebLogic.sh and startManagedWebLogic.sh scripts.
To edit the scripts, add the following to startWeblogic.sh and startManagedWebLogic.sh under $DOMAIN_HOME/bin:
JAVA_OPTIONS="-Doracle.retail.soa.enabler.service.provider.engine.ServiceProviderImplLookupFactory.interceptor=com.oracle.retail.igs.integration.service.DynamicServiceProviderImpl ${JAVA_OPTIONS}"
To edit the server start arguments in the WebLogic console, click igs-server -> Server start as below:
Bounce the Admin and managed server before you deploy the IGS.
The IGS can be installed under $RIB_HOME (rib-home/tools-home/ integration-bus-gateway-services) as described below.
To run IGS under $RIB_HOME, complete the following steps:
Download the IntegrationGatewayService15.0.2ForAll15.0.2Apps_eng_ga.tar and untar it under rib-home/tools-home.
cd rib-home/tools-home/
IntegrationGatewayService15.0.2ForAll15.0.2Apps_eng_ga.tar
Copy aqapi<version>.jar and ojdbc7.jar from rib-home/integration-lib/third-party/oracle/db/12.1.0.2 to $WL_HOME/wlserver/server/lib. Bounce WebLogic servers after copying these jars.
|
Note: The above jars only need to be copied if IGS is hosted in a different domain than the RIB domain. If IGS and RIB share the domain, the jars are already copied when RIB is installed. |
Go to rib-home/tools-home/integration-bus-gateway-services/conf and edit the IgsConfig.properties as follows.
Change the value of WlsUrl to point to the WebLogic server where IGS is going to be deployed. The port in the WlsUrl should be the administration port.
Change the value of WlsTarget to the instance name where IGS is going to be deployed (for example, igs-service_wls_instance).
Go to $IGS_HOME integration-bus-gateway-services/bin. Run the igs-install.sh. Running this script does the following:
Verifies whether the attempted IGS installation is from within rib-home or in standalone mode; preconfiguration cleanup is based on this mode.
Asks the user for the WebLogic user name and password and saves it in a secure credential store.
|
Note: The WebLogic user name used here should be set up with the administrator role. |
Prepares the igs-service.ear, based on the number of channels and the number of configured AQ JMS servers.
Configures the WebLogic server with the AQ JMS server information listed in the rib-deployment-env-info.xml.
Deploys the igs-service-ear to the WebLogic server.
All of the items in Step 4 also can be performed separately, as follows:
Go to rib-home/tools-home/integration-bus-gateway-services/bin. Run the igs-admin.sh -setup-igs to set up the environment. Running this script verifies whether the attempted IGS installation is from within the rib-home or in standalone mode; the preconfiguration cleanup is based on this mode.
sh igs-admin.sh -setup-igs
Go to rib-home/tools-home/integration-bus-gateway-services/bin. Run the igs-admin.sh -setup-security-credential to set up the WebLogic user name and password information in a secure credential store.
sh igs-admin.sh -setup-security-credential
Go to $IGS_HOME /integration-bus-gateway-services/bin. Run the igs-admin.sh -prepare to prepare the igs-service.ear, based on the number of channels and configured AQ JMS.
sh igs-admin.sh -prepare
Go to rib-home/tools-home/integration-bus-gateway-services/bin. Run the igs- admin.sh -configure to configure the WebLogic server with the AQ JMS server information listed in the rib-deployment-env-info.xml.
sh igs-admin.sh -configure
Go to rib-home/tools-home/integration-bus-gateway-services/bin. Run the igs- admin.sh -deploy to deploy the igs-service.ear to the WebLogic server.
sh igs-admin.sh -deploy
If the igs-service.ear must be undeployed, run therib-home/tools-home/integration-bus-gateway-services/bin/igs-admin.sh -undeploy to undeploy an igs-service.ear.
sh igs-admin.sh -undeploy
|
Note: The log files are located here: $IGS_HOME/integration-bus-gateway-services/log If any changes are made to the rib-deployment-env-info.xml or the rib-<app>-adapters.xml, the -prepare, -configure, and -deploy steps, must be executed. |
To verify the IGS installations using the Oracle WebLogic Administration Console, complete the following steps:
|
Note: The Test Client link is visible when the server is in Development mode. |
Navigate to the Deployments page.
On the Summary of Deployments page, locate the igs-service.
To expand the tree, click the + beside the ig-service.
Locate the Web Services section.
Click any Web service (for example, ASNInPublishingService) to move to settings for ASNInPublishingService page.
Select the Testing tab.
To expand the tree, click the + beside the service name.
Locate the Test Client link. Move to the WebLogic Test Client page.
Select the Ping operation. Enter test data in the string arg0: text box. Click Ping.
The test page will include the request message and the response message.
IGS Web services can be secured in two ways. One approach is simple user name and password authentication. For the other approach, passwords are encrypted with certificates.
The following describes both approaches for server-side and client-side setup.
|
Note: The various policy files that can be used to secure Web services are listed in the ws-policy tab of the Web service in the WebLogic Server Administration Console. |
This section describes the two-step process required for securing Web services on the server side. These steps are performed using the Oracle WebLogic Server Administration Console.
The usernametoken.xml contains the policy used by the Web service and is found in the META_INF/policies folder in the .ear file. Complete the following steps to attach the policy file to a Web service.
In the Summary of Deployments screen, click the application. In the illustration below, the application is igs-service.
An overview page is displayed, including a list of modules and components installed as part of the application.
In the Web service list, click the service for which you want to enable security. The following screen is displayed to provide an overview of the Web service.
On this overview screen, click the Configuration tab. Click the WS-Policy tab. The Web service port is shown under Service Endpoints and Operations.
Click the plus sign next to the port name. The Web service operations are displayed.
You can secure all the Web service operations at once or select only the operations you want to secure. Click the name of the port. On the Configure a Web Service policy screen, you can attach the policy file to the Web service. Select WebLogic and click the Next button.
From the Available Endpoint Policies list, select policy:usernametoken.xml. Click the right arrow to move it to the drop down list below Chosen Endpoint Policies. Click OK. The Save Deployment Plan Assistant screen is displayed.
At the bottom of the Save Deployment Plan Assistant screen, click OK. The following screen is displayed, including status messages near the top.
Click Activate Changes. The following screen is displayed.
Under the Testing tab, on the Web Service page, click the WSDL to view the details of the policy just added to the Web service. The WSDL contains information similar to the following.
<?xml version='1.0' encoding='UTF-8'?> <definitions xmlns:tns="http://www.oracle.com/retail/igs/integration/services/PayTermPublishingService/v1" xmlns:ns1="http://www.oracle.com/retail/integration/bus/gateway/services/BusinessObjectId/v1"
xmlns:wsaw="http://www.w3.org/2006/05/addressing/wsdl" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns2="http://www.oracle.com/retail/integration/services/exception/v1" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/" name="PayTermPublishingService" targetNamespace="http://www.oracle.com/retail/igs/integration/services/PayTermPublishingService/v1"
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wssutil="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsp:UsingPolicy wssutil:Required="true" /> <wsp:Policy wssutil:Id="usernametoken"> <ns0:SupportingTokens xmlns:ns0="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512"> <wsp:Policy> <ns0:UsernameToken ns0:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200512/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <ns0:WssUsernameToken10/> </wsp:Policy> </ns0:UsernameToken> </wsp:Policy> </ns0:SupportingTokens> </wsp:Policy>
This section describes how to add roles and users who can access the Web services. The first step is to add users to the security realm, as described below.
In the Domain Structure window of the Oracle WebLogic Services Administration Console, click the Security Realms link.
The Summary of Security Realms screen is displayed, including the name of the default realm.
Click the name of the default realm. The settings for the realm are displayed.
On the Settings screen, click the Users and Groups tab.
In the Users and Groups tab, click the Users tab. At the bottom of the Users tab, click New. The Create a New User screen is displayed.
In the Create a New User screen, enter a user name and password. Leave the default value for Provider. Click OK to save the information. The new user is added to the list of users.
|
Note: You can add roles from the Roles and Policies tab of the security realm or through the Security tab of the Web service. The following instructions are for creating a role through the Security tab of the Web service. |
Navigate to the Security tab of the Web service. Click the Roles tab.
In the Roles tab, click New. The Create a Web Service Module role screen is displayed.
In the Create a Web Service Module Role screen, enter the role name in the Name field (for example, rmsrole). Leave the default value in the Provider Name field. Click OK. The new role is displayed in the Roles tab of the Web service.
To add the user to the role, click the name of the new role in the Roles tab. The Edit Web Service Module Scoped Roles screen is displayed.
In the Edit Web Service Module Scoped Roles screen, click Add Conditions. The "Choose a Predicate" option is displayed.
From the Predicate List, select User. Click Next. The Edit Arguments argument is displayed.
In the User Argument Name field, enter the user name created in the security realm. Click Add. The name will move down to the box below the Add button. Click Finish. The following screen is displayed.
Click Save. The same screen is displayed with this message near the top: "Changes saved successfully."
Return the Security tab of the Web service and click the Policies tab.
On the Policies tab, click Add Conditions. The "Choose a Predicate" option is displayed.
From the Predicate List, select Role. Click Next. The Edit Arguments option is displayed.
In the Role Argument Name field, enter the role name created earlier. Click Add. The role name will move down to the box below the Add button. Click Finish to return to the Policy Conditions screen.
Click Save. The Policy Conditions screen is displayed with this message near the top: "Changes saved successfully."
The following is sample code for calling a secure IGS Web service.
|
Note: The following is sample code for invoking the PayTermPublishingService service. When you generate Java consumer for a Web service, the generated jar file contains classes specific to that Web service. Use the appropriate classes in the client code. Service namespace and WSDL location also should be changed accordingly. |
package com.oracle.retail.rms.client;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PayTermPublishingPortType;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PayTermPublishingService;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PublishPayTermCreateUsingPayTermDesc;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PublishPayTermCreateUsingPayTermDescResponse;
import com.oracle.retail.integration.base.bo.paytermdesc.v1.PayTermDesc;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
import junit.framework.TestCase;
public class PayTermPublishingClient extends TestCase{
public void testCreatePayTermDesc(){
try{
//qName is namespace of the service
QName qName = new QName("http://www.oracle.com/retail/igs/integration/services/PayTermPublishingService/v1"," PayTermPublishingService");
// url is the URL of the WSDL of the web service
URL url = new URL("http://ribhost.example.com:18030/PayTermPublishingBean/PayTermPublishingService?WSDL");
//create an instance of the web service
PayTermPublishingServiceservice = new PayTermPublishingService (url,qName);
PayTermPublishingPortType = service.getPayTermPublishingPort ();
//set the security credentials in the service context
List credProviders = new ArrayList();
CredentialProvider cp = new ClientUNTCredentialProvider("<rms user>", "<rms password>");
credProviders.add(cp);
Map<String, Object> rc = ((BindingProvider)port).getRequestContext();
rc.put(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);
//populate the service method input object
PayTermDesc payTermDesc = new PayTermDesc();
payTermDesc.setTerms("terms");
PublishPayTermCreateUsingPayTermDesc payTermCreateDesc = new PublishPayTermCreateUsingPayTermDesc();
payTermCreateDesc.setPayTermDesc(payTermDesc);
//call the web service
PublishPayTermCreateUsingPayTermDescResponse response = port.publishPayTermCreateUsingPayTermDesc(payTermCreateDesc,"1");
System.out.println("response="+response);
}catch(Exception e){
e.printStackTrace();
}
}
}
WebLogic provides predefined policy files for securing Web services. This section describes the process required to secure a Web service where user name and password are encrypted and signed. Below are the steps to secure the Web service.
Follow the steps to attach the policy file to the Web service described in the section, "Attach Policy File to the Web Service," with this exception: In Step 7, select "policy:Wssp1.2-2007-Wss1.1-UsernameToken-Plain-X509-Basic256.xml" (instead of policy:usernametoken.xml). Follow the remaining steps as shown.
After attaching the policy file, the header for the WSDL of the Web service contains the following.
<wsp:UsingPolicy wssutil:Required="true"/> <wsp:Policy wssutil:Id="Wssp1.2-2007-Wss1.0-UsernameToken-Plain-X509-Basic256.xml"> <ns1:AsymmetricBinding xmlns:ns1="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <wsp:Policy> <ns1:InitiatorToken> <wsp:Policy> <ns1:X509Token ns1:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <ns1:WssX509V3Token10/> </wsp:Policy> </ns1:X509Token> </wsp:Policy> </ns1:InitiatorToken> <ns1:RecipientToken> <wsp:Policy> <ns1:X509Token ns1:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never"> <wsp:Policy> <ns1:WssX509V3Token10/> </wsp:Policy> </ns1:X509Token> </wsp:Policy> </ns1:RecipientToken> <ns1:AlgorithmSuite> <wsp:Policy> <ns1:Basic256/> </wsp:Policy> </ns1:AlgorithmSuite> <ns1:Layout> <wsp:Policy> <ns1:Lax/> </wsp:Policy> </ns1:Layout> <ns1:IncludeTimestamp/> <ns1:ProtectTokens/> <ns1:OnlySignEntireHeadersAndBody/> </wsp:Policy> </ns1:AsymmetricBinding> <ns2:SignedEncryptedSupportingTokens xmlns:ns2="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <wsp:Policy> <ns2:UsernameToken ns2:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient"> <wsp:Policy> <ns2:WssUsernameToken10/> </wsp:Policy> </ns2:UsernameToken> </wsp:Policy> </ns2:SignedEncryptedSupportingTokens> <ns3:Wss10 xmlns:ns3="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"> <wsp:Policy> <ns3:MustSupportRefKeyIdentifier/> <ns3:MustSupportRefIssuerSerial/> </wsp:Policy> </ns3:Wss10> </wsp:Policy>
The key combination used by the client to sign the message is a valid one for the server. The client certificate must be signed with a certificate authority that is trusted by the server.
WebLogic instances include a demo CA. The certificate and key for it is in $WL_HOME/Middleware/wlserver/server/lib/CertGenCA.der and CertGenCAKey.der. The key does not appear to change between WebLogic installations and is trusted by the default DemoTrust store. For this reason, the DemoTrust store must never be enabled in a production environment. Otherwise anybody can become "trusted" fairly easily.
WebLogic CertGen command can be used for generating keys of the correct key length and signing them with the demo CA noted above. A client certification/key pair is required to sign the outgoing message and server certificate to encrypt the critical information.
java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar utils.CertGen -certfile ClientCert -keyfile ClientKey -keyfilepass ClientKey -cn <rms user>
The above command generates the following files.
ClientCert.der
ClientCert.pem
ClientKey.der
ClientKey.pem
The user name is <rms user>. Replace it with the user name of the user who will access the Web service.
The command below generates the four files that follow it.
java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar utils.CertGen -certfile ServerCert -keyfile ServerKey -keyfilepass ServerKey -cn <rms user>
ServerCert.der
ServerCert.pem
ServerKey.der
ServerKey.pem
The user name is <rms user>. Replace it with user name of the user who will access the Web service
Using the following commands, import the files into key stores.
java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar utils.ImportPrivateKey -certfile ClientCert.der -keyfile ClientKey.der -keyfilepass <Client Key Password> -keystore ClientIdentity.jks -storepass <Client Key Password> -alias identity - keypass <Client Key Password>
java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar utils.ImportPrivateKey -certfile ServerCert.der -keyfile ServerKey.der -keyfilepass <Server Key Password> -keystore ServerIdentity.jks -storepass <Server Key Password> -alias identity - keypass <Server Key Password>
Using the script in Appendix: RIB Installation Checklists, configure the WebLogic server to use the key. Copy the script and save it in the location from which it will run.
Java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar weblogic.WLST configWss.py <weblogicuser> <weblogicpassword> <weblogichost> <weblogic admin port> ServerIdentity.jks ServerKey identity ServerKey
For example:
Java -classpath $WL_HOME/Middleware/wlserver/server/lib/weblogic.jar weblogic.WLST configWss.py <weblogic user> <weblogic password> localhost 7001/home/wls/ServerIdentity.jks ServerKey identity ServerKey
In the WebLogic logic console, check the Web Service Security tab to verify that the command ran properly. Note that the default_ww configuration is used for all Web services unless otherwise indicated.
After the certificate setup is completed for the Web service, follow the steps in the "Create Roles and Users" section to create a user in WebLogic to access the Web service.
Restart the server. Create a client to invoke the Web service.
Below is sample code for calling a Web service that is secured using the policy file, policy:Wssp1.2-2007-Wss1.1-UsernameToken-Plain-X509-Basic256.xm.:
package com.test;
import java.net.URL;
import java.security.cert.X509Certificate;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.WebServiceRef;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PayTermPublishingPortType;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PayTermPublishingService;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PublishPayTermCreateUsingPayTermDesc;
import com.oracle.retail.igs.integration.services.paytermpublishingservice.v1.PublishPayTermCreateUsingPayTermDescResponse;
import com.oracle.retail.integration.base.bo.paytermdesc.v1.PayTermDesc;
import weblogic.security.SSL.TrustManager;
import weblogic.wsee.security.bst.ClientBSTCredentialProvider;
import weblogic.wsee.security.unt.ClientUNTCredentialProvider;
import weblogic.wsee.security.util.CertUtils;
import weblogic.xml.crypto.wss.WSSecurityContext;
import weblogic.xml.crypto.wss.provider.CredentialProvider;
public class Client {
public static void main(String args[]){
try{
//qName is namespace of the service
QName qName = new QName("http://www.oracle.com/retail/igs/integration/services/PayTermPublishingService/v1"," PayTermPublishingService");
// url is the URL of the WSDL of the web service
URL url = new URL("http://<host>:<port>/PayTermPublishingBean/PayTermPublishingService?WSDL");
//create an instance of the web service
PayTermPublishingServiceservice = new PayTermPublishingService(url,qName);
PayTermPublishingPortType = service.getPayTermPublishingPort ();
PayTermDesc payTermDesc = new PayTermDesc();
payTermDesc.setTerms("terms");
PublishPayTermCreateUsingPayTermDesc payTermCreateDesc = new PublishPayTermCreateUsingPayTermDesc();
payTermCreateDesc.setPayTermDesc(payTermDesc);
String serverCertFile = "D:/head/retail-soa-enabler/dist/client/ServerCert.der";
String clientKeyStore = "D:/head/retail-soa-enabler/dist/client/ClientIdentity.jks";
String clientKeyStorePass = "ClientKey";
String clientKeyAlias = "identity";
String clientKeyPass = "ClientKey";
List credProviders = new ArrayList();
ClientUNTCredentialProvider unt = new "<rms user>", "<rms password>";
credProviders.add(unt);
final X509Certificate serverCert = (X509Certificate)CertUtils.getCertificate(serverCertFile);
serverCert.checkValidity();
CredentialProvider cp = new ClientBSTCredentialProvider(clientKeyStore, clientKeyStorePass,clientKeyAlias, clientKeyPass, "JKS", serverCert);
credProviders.add(cp);
Map requestContext = ((BindingProvider)port).getRequestContext();
requestContext.put(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);
requestContext.put(WSSecurityContext.TRUST_MANAGER, new TrustManager() {
public boolean certificateCallback(X509Certificate[] chain,int validateErr) {
boolean result = chain[0].equals(serverCert);
return result;
}
});
PublishPayTermCreateUsingPayTermDescResponse response = port.publishPayTermCreateUsingPayTermDesc(payTermCreateDesc,"1");
System.out.println("response="+response);
}catch(Exception e){
e.printStackTrace();
}
}
}
