12 SPML Web Service

12.4.1.1 Adding a Server Agent

To add a Server Agent:

1. Use the Web Services Manager Control (for example, http://localhost:8888/ccore) to create a server agent , and select the following values from the list:

   • Component type: Server Agent

   • Container type: Select OC4J for Oracle Application Server. Select OTHER for IBM WebSphere Application Server.

2. Select Register. This generates a server agent component with a component ID.

12.4.1.2 Defining a Policy for the Server Agent

Use the Web Services Manager Control to define the policy that you want to associate with the server agent. The default implementation of the policy is provided at the following location:

OIM_HOME/SPMLWS/OWSMPolicy

You must associate a URL pattern with the policy. To do so, select Policy Management, Manage Policies, and then Policies. Then click the Edit Mapping button and enter the following as the URL pattern to associate with the policy:

/spmlws/HttpSoap11

To configure a custom policy, you must include the class file com.oracle.xl.spmlws.ws.security.owsm.CustomPolicyStep in OIM_HOME/SPMLWS/OWSMPolicy into the following file:

ORACLE_HOME/owsm/lib/extlib/coresvagent.jar

After creating the server agent component, you must add your custom step to that component. You can do this by clicking the Steps link for your registered component. Then, select the CustomPolicyStep.xml file from its location and click Upload. This XML file is located at OIM_HOME/SPMLWS/OWSMPolicy/com/oracle/xl/spmlws/ws/security/owsm.

At this stage, your custom policy step name is added to the list of available policies.

12.4.1.3 Injecting the Server Agent

Injecting the server agent requires you to perform the following steps:

For Oracle Application Server

To inject the server agent:

1. Modify the attributes in the ORACLE_HOME/owsm/bin/agent.properties file with the following values:

   • agent.componentType: ServerAgent

   • agent.containerType: OC4J

   • agent.containerVersion: It must be "10.1.3" for Oracle Application Server.

   • agent.component.id: Enter the component ID that is generated when the agent is created and registered by using Web Services Manager Control.

2. Edit the following properties in the agent.properties file:

   • webservice.application.input - Enter the full path and name of the EAR file.

   • webservice.application.webapp.name - Uncomment and enter the WAR file name, spmlws.war.

     Note:

     the WAR file is bundled in the OIMSpmlWS.ear file.

   • webservice.application.contexturi - Enter the context root, /spmlws.

3. Run the wsmadmin installAgent command.

For IBM WebSphere Application Server

To inject the server agent:

1. Because the Server Agent for SOA 10.1.3.1 release is supported only for Oracle Application Server, for WebSphere, you must first download the required ZIP file from the following location on Oracle Technology Network:

   For UNIX:

   http://download.oracle.com/otn/linux/ias/101310/soa_linux_x86_ws_agent101310.zip
   

   For Microsoft Windows:

   http://download.oracle.com/otn/nt/ias/101310/soa_windows_x86_ws_agent101310.zip
   

2. Extract the contents of the ZIP file to any location (for example /owsm).

   Tip:

   The Readme_Agentinstall.pdf file in the extracted ZIP file for more information about injecting the server agent

3. Browse to the bin directory, open the agent.properties file, and set the following properties in the file:

   • agent.componentType: serveragent

   • agent.containerType: For example, AXIS, WEBLOGIC, WEBSPHERE, TIBCO-BW, or OC4J

   • agent.containerVersion: The version of WebSphere on which you are deploying the SPML Web Service.

   • oc4j.home:/owsm/oc4j (assuming that /owsm is where you extracted the ZIP file)

   • oc4j.j2ee.home:/owsm/oc4j/j2ee/home (here /owsm is where you extracted the ZIP file)

   • webservice.application.input: Web application input file name with path location, that is, WAR or EAR file location. For example, /owsm/wars/HelloWorldImpl.war

   • webservice.application.webapp.name: not applicable if it is a WAR file

   • webservice.application.contexturi: not applicable if it is a WAR file

   • agent.component.id: Enter the component ID that is generated when the agent is created and registered by using Oracle Web Services Manager Control.

   • agent.policymanagerURL (for example, http://hostname:8888/policymanager. Provide a system name instead of localhost)

4. Open the bin/coresv.properties file and set the following properties:

   • coresv.home=/owsm (assuming /owsm is where you extracted the ZIP file)

   • ant.home: set home directory of the ANT installation

   • java.home: set home directory of the Java installation

   • lib.dir:/owsm/lib (assuming /owsm is where you extracted the ZIP file)

   • oc4j.j2ee.home:/owsm/oc4j/j2ee/home (optional if the properties are present)

   • external.oc4j.home:/owsm/oc4j (optional if the properties are present)

5. For configuring a custom policy, you must include the class file com.oracle.xl.spmlws.ws.security.owsm.CustomPolicyStep in OIM_HOME/SPMLWS/OWSMPolicy into the following file:

   /owsm/lib/extlib/coresvagent.jar
   

   (assuming /owsm is where you extracted the ZIP file)

6. In a command window, navigate to the bin directory. Run the injectAgent command. This command injects all the JAR files into the specified WAR or EAR file. (Before running this, set the path to the ant bin directory.)

12.4.1.4 Deploying the SPML Web Service

After you have installed the client agent, deploy the SPML Web Service. For information about how to deploy the SPML Web Service, refer to the "Deploying the SPML Web Service" section.

12.4.2.1 Registering the Oracle WSM Gateway

To register the Gateway:

1. Click Add New Component in the Oracle Web Services Manager Control.

2. On the Add New Component page, enter the following values:

   • Component Name: for example, MyGateway

   • Component Type: Gateway (default value)

   • Container Type: Oracle Web Services Manager (default value)

   • Component URL: Enter the following: http://fully_qualified_host_name:http_port/gateway where fully_qualified_host_name is the URL for Oracle WSM, and http_port is the port on which Oracle WSM is hosted

   • Component Groups: accept the default values for the component groups

3. Click Register.

4. Click OK.

12.4.2.2 Registering the SPML Web Service with the Gateway

To register the SPML Web Service with the Gateway:

1. From the navigation pane of Oracle Web Services Manager Control, click Policy Management.

2. Click Register Services.

3. Click the Services link.

4. Click Add New Service. The Add New Service page is displayed. On this page, enter the following service details:

   • Service Name: SPMLService

   • Service Version: 1.0

   • Service Description: Processes SPML Requests

   • WSDL URL: The WSDL location, for example:

     http://host:port/spmlws/.../HttpSoap11?wsdl
     

5. Click Next. The Configure Messenger Step for New Service page is displayed. On this page, verify that the URL matches the URL you provided on the previous page. Click Finish to accept the default values for the remaining fields.

6. Click Commit Policy.

12.4.2.3 Adding a Custom Policy to the Gateway

Use the Oracle Web Services Manager Control to configure a policy that you want to associate with the Gateway. The default implementation of the policy is at the following location:

OIM_HOME/SPMLWS/OWSMPolicy

The policy extracts user credentials from the WSSE security tags and adds them to the SOAP header in the following custom tag.

<wsa1:OIMUser soap:mustUnderstand="0" xmlns:wsa1="http://xmlns.oracle.com/OIM/provisioning">
<wsa1:OIMUserId xlmns:wsa1="http://xmlns.oracle.com/OIM/provisioning">user1</wsa1:OIMUserId>
<wsa1:OIMUserPassword  xlmns:wsa1="http://xmlns.oracle.com/OIM/provisioning">password1</wsa1:OIMUserPassword>
</wsa1:OIMUser>

The SPML Web Service interprets and processes this tag.

For configuring a custom policy, you must include the com.oracle.xl.spmlws.ws.security.owsm.CustomPolicyStep in OIM_HOME/SPMLWS/OWSMPolicy class file into the following file:

ORACLE_HOME/owsm/lib/coresv-4.0.jar

You must include the custom policy step file because the coresv-4.0.jar file contains all the policy-specific class files. Then, restart Oracle Application Server.

After you register the Gateway, you must add a custom step. To add a custom step:

1. Upload the CustomPolicy.xml file for the custom policy on the Add Step page. This XML file is located at the following path:

   OIM_HOME/SPMLWS/OWSMPolicy/com/oracle/xl/spmlws/ws/security/owsm
   

2. To open the Add Step page in the Oracle Web Services Manager Control, expand Policy Management, click Manage Policies, Steps, and then Add Step. Select the CustomPolicy.xml file from its location and then click Upload. The name of the custom policy step is added to the list of available policies.

3. To add the custom policy to the pipeline in the Request block, browse to the Policy page. To open the Policy page, expand Policy Management, click Manage Policies, Policies, and finally click Policy.

   The Request block will enforce this configured custom policy for any valid incoming request sent to the SPML Web Service.

12.4.2.4 Deploying the SPML Web Service

After you have installed the client agent, deploy the SPML Web Service. For information about how to deploy the SPML Web Service, refer to the "Deploying the SPML Web Service" section.

12.4.2.5 Viewing the WSDL File

To view the Web Service Description Language (WSDL) file for the Web Service:

1. From the navigation pane of Web Services Manager Control, click Policy Management.

2. Click Register Services.

3. To access the Gateway (MyGateway), click Services.

4. From the list of services, click Edit for the required service.

5. In the Edit Service page, copy the URL displayed in the Service WSDL URL field.

You use this URL in the SPML client to access the SPML Web Service.

12.6.1.1 Prerequisites

The following are the prerequisites for enabling SSL communication:

• JBoss Application Server is installed and Oracle Identity Manager and the SPML Web Service are deployed on it.

• The JBoss Application Server home directory is E:\jboss-4.2.3.GA.

• The identity store is jbossserver.jks and the password is welcome.

• Certificate request is made for localhost.

• The self-sign certificate is named jbossserver.cert.

• The private key alias is serverjboss and the password is welcome.

12.6.1.2 SSL Certificate Setup

This section discusses the following procedures for setting up SSL:

1. Generating Keys

2. Signing the Certificates

3. Exporting the Certificate

4. Configuring the server.xml File

Generating Keys

Generate keys by using the keytool command. The following keytool command generates an identity keystore jbossserver.jks:

keytool -genkey -alias serverjboss -keyalg RSA -keysize 1024 -dname "CN=localhost,OU=Identity,O=Oracle,C=US" -keypass welcome -keystore E:\jboss-4.2.3.GA\server\jbossserver.jks -storepass welcome -storetype jks

Signing the Certificates

Use the following keytool command to sign the certificates that were created:

keytool -selfcert -alias serverjboss -sigalg MD5withRSA -validity 2000 -keypass welcome -keystore  E:\jboss-4.2.3.GA\server\jbossserver.jks -storepass welcome

Exporting the Certificate

Use the following keytool command to export the certificate from the identity keystore to a file (for example, jbossserver.cert):

keytool -export -alias serverjboss -file E:\jboss-4.2.3.GA\server\jbossserver.cert -keypass welcome -keystore E:\jboss-4.2.3.GA\server\jbossserver.jks -storepass welcome -storetype jks -provider sun.security.provider.Sun

Configuring the server.xml File

Make the following entry in the server.xml file:

<Connector port="8443" address="${jboss.bind.address}"
           maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
           emptySessionPath="true"
           scheme="https" secure="true" clientAuth="false"
              sslProtocol="TLS" 
           keystoreFile="E:\jboss-4.2.3.GA\server\jbossserver.jks"
           keystorePass="welcome"
           truststoreFile="E:\jboss-4.2.3.GA\server\jbossserver.jks"
           truststorePass="welcome"/>

After you have performed the preceding steps, restart the server for the changes to take effect.

12.6.2.1 Prerequisites

The following are the prerequisites for enabling SSL communication:

• Oracle WebLogic Server is installed.

• The WebLogic Domain directory is C:\bea\user_projects\domains\oim.

• The Oracle WebLogic Server home (WL_HOME) directory is C:\bea\wlserver_10.3.

• The identity store is support.jks and the password is support.

• The certificate request is made for xellerate.oracle.com host and for Oracle Identity Management Group.

• The self-sign certificate is named supportcert.pem.

• The private key alias is support, and the password is weblogic.

• The setEnv.cmd or setEnv.sh script is run to set up PATH, CLASSPATH, and other variables.

12.6.2.2 SSL Certificate Setup

This section discusses the following procedures for setting up SSL:

1. Generating Keys

2. Signing the Certificates

3. Exporting the Certificate

4. Configuring the Oracle WebLogic Server

Generating Keys

Generate private/public certificate pairs by using the keytool command provided. The following command creates an identity keystore (support.jks). Change the parameter values passed to the keytool command according to your requirements. Ensure that there is no line break in the keytool argument.

keytool -genkey
        -alias support
        -keyalg RSA
        -keysize 1024
        -dname "CN=xellerate.oracle.com, OU=Identity, O=Oracle Corporation, 
L=RedwoodShores, S=California, C=US"
        -keypass weblogic
        -keystore C:\bea\user_projects\domains\oim\support.jks
        -storepass support

Signing the Certificates

Use the following command to sign the certificates that you created.

keytool -selfcert -alias support 
        -sigalg MD5withRSA 
        -validity 2000 
        -keypass weblogic 
        -keystore C:\bea\user_projects\domains\oim\support.jks 
        -storepass support

Exporting the Certificate

Use the following command to export the certificate from the identity keystore to a file, for example, supportcert.pem:

keytool -export -alias support 
        -file C:\bea\user_projects\domains\oim\supportcert.pem 
        -keypass weblogic 
        -keystore C:\bea\user_projects\domains\oim\support.jks 
        -storepass support

Configuring the Oracle WebLogic Server

To configure the Oracle WebLogic Server:

1. In the WebLogic Server Administration Console, click Environment, Servers, Server_Name, Configuration, and then General.

2. Click Lock & Edit.

3. Select SSL listen port enabled. The default port is 7002.

4. Click the Keystores tab

5. From the Keystore list, select Custom Identity and Java Standard Trust.

6. In the Custom Identity Keystore field, specify C:\bea\user_projects\domains\oim\support.jks as the custom identity keystore file name.

7. Specify JKS as the custom identity keystore type.

8. Enter the password in the Custom Identity Keystore Passphrase and Confirm Custom Identity Keystore Passphrase fields.

9. Click Save.

10. Click the SSL tab.

11. Enter support as the private key alias.

12. Enter the password (for example, support) in the Private Key Passphrase and Confirm Private Key Passphrase fields.

13. Click Save.

14. Click Activate changes.

15. Restart the server for the changes to take effect.

keytool -import -alias serverwl -trustcacerts -file D:\bea\user_projects\domains\ mydomain\wlservercert.pem -keystore <client-trust store> -storepass <client-trust-store password>

12.6.3.1 Prerequisites

The following are the prerequisites for enabling SSL communication:

• IBM WebSphere Application Server is installed and Oracle Identity Manager and the SPML Web Service are deployed on it.

• After configuring IBM WebSphere Application Server and deploying the SPML Web Service with Oracle Identity Manager, you can access the application by using SSL and non-SSL ports.

• To access the application securely by using SSL, you use port number 9443 or WC_defaulthost_secure. Consider the following example:

  https://localhost:9443/spmlws/HttpSoap11
  

• The default identity store is key.p12, and the password is WebAS.

• The default truststore is trust.p12, and the password is WebAS.

  Note:

  For SSL communication, export the default certificate from key.p12.

12.6.3.2 SSL Certificate Setup

The steps in this section enable you to do the following:

• Exporting Certificate to a File

• Importing the Certificate File

Exporting Certificate to a File

IBM WebSphere Application Server uses the IBM WebSphere default keystore (key.p12) and its default certificate. You must export this default certificate to a file. You can use the following keytool command to achieve this:

IBM_JDK_HOME/jre/bin/keytool -export -alias default -file <Exported Certificate file> -keypass WebAS -keystore  FULL_PATH_OF_IBM_WEBSPHERE "key.p12" -storepass WebAS -storetype pkcs12 -provider com.ibm.crypto.provider.IBMJCE

In the preceding command, replace the following to point to the appropriate location:

• The full path of IBM WebSphere Application Server key.p12, which is the default IBM keystore

• IBM_JDK_HOME to the IBM WebSphere Application Server Java folder

• Location for the exported certificate

Importing the Certificate File

Use the following keytool command to import the certificate file to the SPML Web Service client truststore:

keytool -import -alias serverws -trustcacerts -file <Exported Certificate file> -keystore E:\SPMLTest\mykeystore -storepass mypass  -storetype jks

12.6.4.1 Prerequisites

The following are the prerequisites for enabling SSL communication:

• Oracle Application Server is installed and Oracle Identity Manager and the SPML Web Service are deployed on it.

• Oracle Application Server 10.1.3 installation directory is E:\product\10.1.3.1\OracleAS_1.

• The identity store is oc4jserver.jks, and the password is welcome.

• Certificate request is made for localhost.

• The self-sign certificate is named oc4jserver.cert.

• The private key alias is serveroc4j, and the password is welcome.

12.6.4.2 SSL Certificate Setup

The steps in this section enable you to do the following:

1. Generating Keys

2. Signing the Certificates

3. Exporting the Certificate

4. Configuring Oracle Application Server

Generating Keys

Generate keys by using the keytool command provided. The following keytool command creates an identity keystore oc4jserver.jks:

keytool -genkey -alias serveroc4j -keyalg RSA -keysize 1024 -dname "CN=localhost,OU=Identity,O=Oracle,C=US" -keypass welcome -keystore E:\product\10.1.3.1\OracleAS_1\oc4jserver.jks -storepass welcome -storetype jks

Signing the Certificates

Use the following keytool command to sign the certificates you created:

keytool -selfcert -alias serveroc4j -sigalg MD5withRSA -validity 2000 -keypass welcome -keystore  E:\product\10.1.3.1\OracleAS_1\oc4jserver.jks -storepass welcome

Exporting the Certificate

Use the following keytool command to export the certificate from the identity keystore to a file:

keytool -export -alias serveroc4j -file E:\product\10.1.3.1\OracleAS_1\oc4jserver.cert -keypass welcome -keystore E:\product\10.1.3.1\OracleAS_1\oc4jserver.jks -storepass welcome -storetype jks -provider sun.security.provider.Sun

Configuring Oracle Application Server

To configure Oracle Application Server:

1. Make a copy of the E:\product\10.1.3.1\OracleAS_1\j2ee\home\config\default-web-site.xml file at the same location and rename the copy to secure-web-site.xml.

2. In the secure-web-site.xml file, modify the following:

   • port attribute=4443

   • secure=true

   • protocol=https

   For example:

   web-site xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://xmlns.oracle.com/oracleas/schema/web-site-10_0.xsd"  port="4443"  secure="true" protocol ="https" display-name="OC4J 10g (10.1.3) Default Web Site" schema-major-version="10" schema-minor-version="0">
   

3. In the same file, under the web-site node, add a new element ssl-config to point to the keystore as shown in the following example:

   <ssl-config keystore="E:/product/10.1.3.1/OracleAS_1/oc4jserver.jks" keystore-password="welcome" />
   

4. In the E:\product\10.1.3.1\OracleAS_1\j2ee\home\config\server.xml file, add the following entry:

   <web-site path="./secure-web-site.xml"/>
   

5. In the E:\product\10.1.3.1\OracleAS_1\opmn\conf\opmn.xml file, add the following:

   <port id="secure-web-site" range="4443" protocol="https"> under <ias-component id="default_group">
   

6. In the opmn.xml file, add the following in the <data id="java-options" value="-Xrs" under <ias-component id="default_group"> tag:

   -Djavax.net.ssl.trustStore=E:\product\10.1.3.1\OracleAS_1\oc4jserver.jks
   -Djavax.net.ssl.trustStorePassword=welcome
   -Djavax.net.ssl.keyStore=E:\product\10.1.3.1\OracleAS_1\oc4jserver.jks
   -Djavax.net.ssl.keyStorePassword=welcome"
   

7. Restart the server for the changes to take effect.

12.6.5.1 Exporting Certificate

You must export the certificate from the default Oracle wallet ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default/ewallet.p12. This certificate is used for the Design Console to trust Oracle Application Server. To export the certificate:

1. Open the ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default/ewallet.p12 file by using the Oracle Wallet Manager Console. To do so, click Open Wallet and browse to the location of the wallet.

2. When prompted, enter the store password as welcome.

3. Right click Certificate (Ready), and click Export User Certificate.

4. Save the file as server.cert.

   See Also:

   The "Secure Sockets Layer" section in Oracle Application Server Administrator's Guide for more information about Oracle Wallet Manager