Best Practices from Oracle Development's A‑Team

Cloud Security: Using Fusion Application Web Services with Message Protection

Olaf Heimburger
A-Team Cloud Solution Architect


Oracle Fusion Applications offers a number of WebServices to allow other applications to incorporate the Fusion Applications functionality. To prevent data leakage, these WebServices follow a common security pattern that requires access authentication and message protection using message signing and/or message encryption.

To use such a WebService, the WSDL of each service provides all the information that tells the WebService client what needs to be provided to call it successfully.

For Fusion Applications, nearly all WebServices use message protection, i.e., message signing and/or message encryption, to ensure that the message arrives as it has been sent by the client. Like many Oracle products, Fusion Applications implements this by using Oracle WebService Manager (OWSM). OWSM also publishes the WebService's base64-encoded public key certificate in the WSDL.

This article explains how to get this public key certificate and its related signing root certificate and how to put in the correct keystore.


WebServices are a well known technique used by many applications to expose APIs that allow to build bigger applications in service-oriented architectures (SOA). WebServices may receive or send sensitive information and should be secured to avoid non-authorized usage. To allow a WebService developer to work on the service implementation only, Oracle provides a security layer for WebServices called Oracle Web Service Manager (OWSM). This layer allows to configure security measures, profiles in OWSM parlance, by service administrators at runtime. The WebService security profile will be implemented by OWSM adapters that intercept the WebService incoming or outgoing traffic and free the developer from implementing all possible security measures and allow them fully focus on the service implementation only.

Certificates, Certificates, Certificates

Well secured WebServices require a number of certificates for proper message protection and secured transport. For Fusion Application Web Services these certificate types are very common:

  • Transport Level Security Certificate – The certificate used for securing the transport level (i.e., HTTPS). It can be easily retrieved from the browser session when inspecting the WSDL file. It is usually stored in the JDK truststore.
  • The Owner Certificate – This certificate is part of the WSDL, and used for message signing and/or encryption and may be installed in the client keystore.
  • The Issuer Certificate – (Optional) The Issuer Certificate name is part of the WSDL description. In later versions of OWSM the Issue Certificate is included in the WSDL, too.

Finding the OWSM Security Policy

A WebService WSDL protected by OWSM lists the security policies used for the WebService. The implementer of a client for the WebService can easily spot the security related contents.

The <wsp:Policy> tags may include OWSM policies, if the wsu:Id attribute specifies OWSM policy names like these:

<wsp:Policy wsu:Id="wss11_saml_or_username_token_with_message_protection_service_policy">
<wsp:Policy wsu:Id="wss11_saml_token_with_message_protection_client_policy">

If the <wsp:Policy wsu:Id> attribute includes the text message_protection, the related information, i.e., the certificates, for the message protection policies must be found.

Message protection uses X.509 certificates for a public key which can be used to encrypt and/or sign the SOAP message (see X.509 for a detailed description). An OWSM protected WebService may include one or more X.509 certificates, which can be found within the <wsdl:service> tag (for example: <wsdl:service name="FinancialUtilService"> ).

The <wsdl:service> tag has a few subtags. The most interesting is the <wsid:Identity> tag.

     <dsig:X509IssuerName>CN=Cloud9CA, DC=cloud, DC=oracle, DC=com</dsig:X509IssuerName>
    <dsig:X509SubjectName>CN=FAEncryption, DC=cloud, DC=oracle, DC=com</dsig:X509SubjectName>

The important tags here are <dsig:X509Certificate>, <dsig:X509IssuerName>, <dsig:X509SubjectName>. The tag <dsig:X509Certificate> holds the actual certificate required for message protection. The tag <dsig:X509SubjectName> specifies the name of the certificate. And finally, the tag <dsig:X509IssuerName> specifies the name of the certificate that was used for signing the certificate in <dsig:X509Certificate>. This is usually the name of the root certificate.

If the <dsig:X509SubjectName> and the <dsig:X509IssuerName> match, the <dsig:X509Certificate> is a self-signed certificate and only this certificate is needed.

Extract the Certificate

Once the certificate has been located, it needs to be extracted and stored into a Java keystore (jks file). To do this, the value between <dsig:X509Certificate> and </dsig:X509Certificate> needs to be selected and copied into an editor. Before saving the content into a file, it must have a line -----BEGIN CERTIFICATE----- before the certificate and a line -----END CERTIFICATE----- after it. It should look like this:


When done, this should be stored in a file (for example owner_cert.cer).

Setting up the Keystore

Next, this certificate should be imported into a JKS keystore file. Although, there are many tools for doing this, the standard JDK keystore tool is a reliable tool for this task. To import the certificate, use the command keytool -importcert.

Note: Searching the Internet for a certificate import procedure often shows a two step process. However, even if there is no keystore file available, the keytool -importcert command creates a keystore with just the new certificate.
$ keytool -importcert -trustcacerts -alias orakey -keystore client.jks -file owner_cert.cer
Enter keystore password:
Re-enter new password:
Owner: CN=service, DC=us, DC=oracle, DC=com Issuer: CN=CertGenCA, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US
Serial number: 15633202a8b
Valid from: Thu Jul 28 22:09:21 CEST 2016 until: Tue Jul 27 22:09:21 CEST 2021
Certificate fingerprints:
          MD5:  B3:58:A8:61:A1:97:A2:DB:A6:5F:B3:EB:36:41:87:73
          SHA1: 9A:95:96:23:60:06:55:30:17:58:51:75:AF:2D:A4:A0:AF:65:1F:B9
          SHA256: EC:48:17:95:E6:6C:3A:7D:29:22:3E:21:9A:60:43:06:F5:57:DF:A6:E8:0B:FD:B9:4B:07:8B:E6:6A:73:35:FE
          Signature algorithm name: SHA256withRSA
          Version: 3
 #1: ObjectId: Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: A8 67 A3 DA E8 52 2E D6   0D 07 93 83 96 3F 9E 09  .g...R.......?.. 0010: EF E8 2F 56
                                        ../V ] ]
 Trust this certificate? [no]:  yes
 Certificate was added to keystore

The values of Owner and Issuer match their respective values of the <dsig:X509SubjectName> and <dsig:X509IssuerName> tags.

Owner vs Issuer

Owner and Issuer are the values that help to identify the certificate. Both values are the parties who created the certificate. Both values can match or be distinct. If they match, we have a root or self-signed certificate.

Root certificates are issued by an Certificate Authority (CA). These play a role similar to government authorities that issue ID cards and passports. They can be trusted. On the other hand, a self-signed certificate can be issued by everyone and may not be trusted.

If the imported certificate have distinct values for Owner and Issuer, this surely means that at least two different certificates are required:

  • the certificate of the Owner
  • the certificate of the Issuer

Normally, OWSM includes the Owner certificate in the WSDL file.

Getting the Issuer Certificate

If the Owner certificate is not a self-signed certificate there are two options to get the Issuer certificate:

Getting the Issuer Certificate From the WSDL

In later versions of OWSM, even the Issuer certificate can be included in the WSDL, too. Here is how the tag of such a WSDL looks like.

     <dsig:X509IssuerName>CN=CertGenCA, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US</dsig:X509IssuerName>
    <dsig:X509SubjectName>CN=service, DC=us, DC=oracle, DC=com</dsig:X509SubjectName>

The second <dsig:X509Certificate> tag may hold the certificate of the Issuer. This certificate should be copied into a file as described above. To import the Issuer certificate see the import command in the Developer Tasks below.

Getting the Issuer Certificate From the Administrator

The Administrator can be any person who manages a Fusion Applications environment on-premises or on Oracle Cloud. The Administrator steps for both installation options are the same. The steps for the WebService client developer are similar but involve different routes:

  • Cloud – File a Service Request on My Oracle Support
  • On-premises – File a Service Request internally

The steps for the Administrator are as follows:

  • Open the Domain FMW Console
  • Navigate to WebLogic Domain > DomainName > Security > Keystore > system
  • Select castore
  • Click on Manage
  • Find the certificate which has the matching Issuer name (in column Subject Name)
  • Select the certificate
  • Click on Export
  • Click on Export Certificate
  • Send the file to the WebService client developer

Developer Tasks

A developer needs to do these steps:

  • Ask the Administrator to get the certificate whose Subject Name matches the value of the Issuer
  • When the Issuer certificate has been received from the Administrator, these steps are needed:
    • Import the Issuer certificate into the client keystore:
      $ keytool -importcert -trustcacerts -alias democa -keystore client.jks -file issuer_cert.cer
       Enter keystore password:
       <b>Owner: CN=CertGenCA, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US</b>
       <b>Issuer: CN=CertGenCA, OU=FOR TESTING ONLY, O=MyOrganization, L=MyTown, ST=MyState, C=US</b>
       Serial number: 40044886c441ef3b643a8066409afca0
       Valid from: Sat Dec 01 04:07:51 CET 2012 until: Thu Dec 02 04:07:51 CET 2032
       Certificate fingerprints:
                MD5:  F2:33:C1:AF:A6:95:8B:A3:5C:CE:DF:0D:16:05:07:AD
                SHA1: CA:61:71:5B:64:6B:02:63:C6:FB:83:B1:71:F0:99:D3:54:6A:F7:C8
                SHA256: 57:10:7C:2C:B3:07:B9:8B:F8:FD:EB:69:99:36:53:03:7A:E1:E7:CB:D3:7A:E7:CF:30:F3:B3:ED:F3:42:0A:D7
                Signature algorithm name: SHA256withRSA
                Version: 3 Extensions:
       #1: ObjectId: Criticality=true BasicConstraints:[ CA:true PathLen:1 ]
       #2: ObjectId: Criticality=true KeyUsage [ Key_CertSign ]
       #3: ObjectId: Criticality=false SubjectKeyIdentifier [ KeyIdentifier [ 0000: 34 38 FD 45 D8 80 CF C7   D2 E8 DF 1D F8 A1 39 B0  48.E..........9. 0010: 11 88 00 6A                                        ...j ] ] Trust this certificate? [no]:  yes Certificate was added to keystore $ 

Using the Certificate

Finally, when every certificate is in place, the WebService client code can be written in any programming language but should use the certificates stored in the client keystore when calling the WebService.

Java code for OWSM Client

One of the best ways to implement a Java Client is to use the JDeveloper WebService Proxy generator. The code uses the OWSM client libraries and frees the developer from coding the details for the security policies.

Once the code has been created, the following code lines help to get started. (Your mileage for the authentication may vary. For simplicity Username/Password have been used.)

// (Optional) If the SSL certificate is not present in the standard truststore
// we may override it with these lines:
 if (overrideTruststore) {
   System.setProperty("javax.net.ssl.trustStore", trustStore);
   System.setProperty("javax.net.ssl.trustStorePassword", trustStorePassword);
 // ...
 WSBindingProvider wsbp = (WSBindingProvider)service;
 Map<String, Object> requestContext = wsbp.getRequestContext();
 requestContext.put(BindingProvider.USERNAME_PROPERTY, username);
 requestContext.put(BindingProvider.PASSWORD_PROPERTY, password);
 requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endPointURL);
 requestContext.put(ClientConstants.WSSEC_KEYSTORE_TYPE, "JKS");
 requestContext.put(ClientConstants.WSSEC_KEYSTORE_LOCATION, clientJKS);
 requestContext.put(ClientConstants.WSSEC_KEYSTORE_PASSWORD, clientJKSPassword);
Note: If the OWSM client library finds an Owner certificate in the WSDL, it may override the certificate stored in the WSSEC_KEYSTORE_LOCATION. This is a pretty useful feature and frees the client developer from importing the Owner certificate. However, if the keystore will be shared between different WebService client implementations it must contain both certificates. In any case, the Issuer certificate must be present in the WSSEC_KEYSTORE_LOCATION.


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha