Making authenticated web service callouts from Salesforce to IBM Cast Iron using SSL/certificates–Part III

Introduction

The first part of this article series laid out the foundation and the second part implemented the solution without security. This article will now focus on adding one-way SSL/Certificate authentication to the web service hosted by the IBM WebSphere Cast Iron runtime appliance.

Certificates and SSL: Basics

In the first part of this article series, we briefly touched the topic of X.509 certificates. Let’s dig little deep to understand what certificate means and how this is used to secure data exchange between server and the client.

The data that travels through the public internet can always be snooped in easily. When a user visits a website that uses no security (read HTTP),  the information is returned back as a clear text. This is fine for the websites like wikipedia.org or cnn.com where the content from these websites are not sensitive (i.e., doesn’t reveal privacy, financial, kind of information). At the same time, if a user wants to shop from a website or access his health records from a health care service provider, then the privacy and the financial information can be easily compromised, if the data travels over HTTP. The data exchange between the client and the server needs to be secured in order to protect the financial / privacy information of the users. The SSL was invented to address this issue; with SSL, the entire communication between the client and the server is encrypted using PKI and only the client can decrypt the information sent by the server and vice versa. But how does the user verify that the information did originate from the server that it is talking to.

Assume that an attacker steals the public key and was able to snoop in between and interpret all communications between the client and the server; now the attacker can act as a client to the server and get access to the data, even if the data travels over SSL. Similarly, it can act as a server to the client and can provide either incorrect information or get additional sensitive information from the client. Even though the data itself is encrypted and sent over the wire, the attacker has the public key and now he can decrypt it. How do we solve this problem?

This is where the certificates come to rescue. The SSL certificate or simply a certificate enables the server to prove its identity so that the client can trust the public key that the server exchanges with the client. Once the client verifies that it is indeed talking to the server, all the traffic between the client and the server can be encrypted with a trusted key verified by a registered and trusted independent third party. This third party is called as the ‘Certificate Authority’ and they issue the certificates which certifies that the public key is owned by the same entity who is named in the certificate. This permits the client to trust the public key and sign the data that it sends to the server, since the public key corresponds to the private key which the server has it. The server uses this private key to encrypt all the data that it sends to the client and only the client, which has the public key, can decrypt it.

The process of establishing the secure communication between the server and the client is called SSL handshake. The process is as follows when a client tries to establish the secure connection with the server:

  • The client sends the list of cipher suites that it supports to the server.
  • The server chooses the best and the strongest one from the list and sends back digital certificate along with the public key.
  • The client may communicate with the CA which signed the certificate to verify the authenticity. Once the client is satisfied, it generates a hash encrypted by the public key and send it to the server to generate the mutually agreeable session key.
  • The server decrypts the session key with its private key and generates the session key. This session key is the encryption key which will be used to encrypt all subsequent communications till the end of the session.

Understanding the one-way SSL/certificate security

In a typical communication between a server and a client, it is the server which has to prove its identity to the client. For e.g. when a user visits Amazon.com to buy something, the amazon.com website has to prove that it is indeed amazon.com, so that the user can safely browser through their website, add things to shopping cart, provide credit card and place the order – all with encrypted communication (the client still need to authenticate with user name/password, but the client doesn’t need to prove its identity. In other words, the server doesn’t expect the client to prove its identity and anybody who has a particular user’s user name / password, can login into the website). This type of security is called as the one-way SSL/certificate, since only one of the parties provide its identity and the other simply use it to verify it.

For most situations, one-way SSL/certificate security is enough. We will cover the basics of two-way SSL/certificate security and how to implement it in the next part. With the basics in place, the rest of this article will show the necessary steps to add one-way SSL/certificate security to the solution that we built in the previous part.

Tutorial 2: Setting up one-way SSL/certificate authentication

This tutorial will accomplish the following:

  • Generating the CSR.
  • Getting the signed certificate.
    • Getting certificate signed by public CA.
  • Installing the certificate in IBM WebSphere Cast Iron runtime appliance’s Key Store.
  • Configuring the certificate(s) in IBM WebSphere Cast Iron runtime appliance.
  • Securing the web service with HTTPS/SSL certificate in IBM WebSphere Cast Iron Studio.
  • Updating the wrapper class and the stub in Salesforce.
  • Update the remote site settings.

Step # 1: Generating the CSR

The first step is to generate the Certificate Signing Request (CSR) that will be used to obtain the signed certificate. Most major platforms such as Windows Active Directory Certificate Services (part of Windows Server 2003/2008), Open SSL support creating the CSR’s. For this tutorial, we will use the IBM WebSphere Cast Iron runtime appliance to generate the CSR.

Login into WMC and click ‘Generate’ under Key Store panel of the Security->Certificates. This will pop up a dialog box.

A1-P3-CI-03-CSR

Figure 3a.Creating a CSR

The screenshot above contains data for a fictitious company. Update the data to reflect your needs. Here is the description of this data.

  • Alias – This will be the name of the certificate which will be referenced in the ‘Web Service’ endpoint.
  • Distinguished Name:
    • Common Name (CN): The Fully Qualified Domain Name (FQDN) of the entity to be secured. The common name can include * to indicate wild card certificate.
    • Organization (O): The registered name of the organization.
    • Organizational Unit (OU): The department / organizational unit which this is being applied for.
    • Country (C): Country, where the organization is registered. This should not be abbreviated.
    • State (ST): State, where the organization is registered.
    • Locale (L): City, where the organization is registered. This should not be abbreviated.
    • Email (EMAILADDRESS): The email address of the person who administers the certificates.
  • Key Algorithm: The algorithm used to compute the key.
  • Key Length: The length of the key.
  • Valid for: The length of time, the certificate is valid.

Click ‘Generate’ and this will generate the CSR and open up a dialog box with that has content that looks like below:

A1-P3-CI-05-CSR-Text

Figure 3b.The Certificate Request

This is called the PEM formatted CSR and it is basically a text version of binary CSR which is base-64 encoded. Click ‘Download’ and save the file (it saves as .pem file).

Step # 2: Getting the signed certificate

Certificates can be signed either by trusted public CA such as Verisign, Thawte, DigiCert, etc., or it can be self-signed. Salesforce will accept only certificates signed by public CA for one-way SSL/certificate authentication setup, where salesforce is a client consuming web services hosted elsewhere. It does support self-signed certificates in two-way SSL/certificate scenario, provided, the self-signed certificate is installed in the Key Store of the corresponding web server. This tutorial will cover the process of getting certificate signed by public CA. The Part-4 of this article series will cover the process of getting self-signed certificate.

Getting certificate signed by public CA

The CSR can be submitted to the public CA either through email or uploading through their website and in most cases the signed certificate can be obtained in a day or two. Once the CA validates the identity of your corporation, they will issue the certificate.

Step # 3: Installing the certificate in IBM WebSphere Cast Iron runtime appliance

Once the signed certificate is received, now it can be installed into the Key Store in the IBM WebSphere Cast Iron runtime appliance through WMC. Generally, all web servers will have two stores;

  • Trust Store – A Trust Store contains the certificates from public CA’s that your web server trusts. Most web servers ship with the trust certificates of the major CA’s. Naturally, the Trust Store contains only the public keys along with the certificates.
  • Key Store – A Key Store may or may not contain the certificates. If the web server provides SSL based security, then the signed certificate that you obtained (either self-signed or signed by public CA) will be stored in the Key Store. As you might have guessed, the Key Store contains both the public and private keys along with their certificates.

The following screenshot shows the certificates configuration page in IBM WebSphere Cast Iron runtime appliance.

A1-P3-CI-01-Certificates

Figure 3c. Certificate configuration page in IBM WebSphere Cast Iron runtime appliance.

Since our goal is to enable the one-way SSL/certificate, we have to import the signed certificate into the Key Store. To do this, click ‘contoso wildcard’ (or whatever the name that you entered when you created the CSR) link under ‘Key Store’ panel of the Security->Certificates. This will open up the following dialog box loaded with the certificate information.

A1-P3-CI-11-PreUploadSignedCertificate

Figure 3d. CSR information

Click ‘Upload’ and this should show the following dialog box.

A1-P3-CI-04-UploadSignedCertificate

Figure 3e. Signed certificate upload

Click ‘Browse’ and select the signed certificate file that you received from your CA and click ‘Open’. Alternatively, you can open the signed certificate file in notepad and copy the contents in its entirety which will look like below:

A1-P3-CI-06-PastingSignedCertificateContent

Figure 3f. Pasting signed certificate content

Click ‘Import’. Your signed certificate now should be imported and ready to use.

Step # 4: Configuring the certificate(s) in IBM WebSphere Cast Iron runtime appliance

Most web servers come with root certificates pre-installed from most of the major public CA’s. As said, IBM WebSphere Cast Iron comes with the default Trust Store that is loaded with the root certificates from the industry leading public CA’s. Please make sure that you have those root certificates from the public CA from whom you have bought your signed certificate(s). It is also important that all the intermediate certificates that was part of your signed certificate to be installed into the Trust Store. The public CA will provide you all the intermediate certificates along with your signed certificate. These intermediate certificates will go into the Trust Store. You can validate the presence of intermediate certificates through multiple ways; you can use online SSL utilities from your CA or other CA’s such as DigiCert, SSL Labs, etc. You can also use Open SSL tool to validate it.

Another important setting for making one-way SSL/certificate is setting the SSL Usage Type in the IBM WebSphere Cast Iron runtime appliance. To do this, click ‘Edit’ under Settings panel of the Security->Certificates.

A1-P3-CI-09-Certificates-ClientSSL-Settings

Figure 3g. Client SSL Settings section.

A1-P3-CI-10-Certificates-ClientSSL-SettingsUpdate

Figure 3h. Update Client SSL Settings section.

Click ‘Save’. This step is what defines the one-way SSL/certificate mechanism. Basically, we are instructing the server that the client doesn’t need to prove its identity using the SSL certificate.

Step # 5: Securing the web service with HTTPS/SSL certificate in IBM WebSphere Cast Iron Studio

The configuration piece on the server side is complete and now it’s time to update the configuration in the orchestration to use HTTPS and the newly installed signed certificate. In the IBM WebSphere Cast Iron Studio, open the Web Service endpoint and select the option ‘HTTPS’ under ‘Security’. Check the ‘Server Certificate Alias Name’ and replace the entry ‘Factory Supplied Identity’ with the certificate name that you entered while creating the CSR. In this case, it is ‘contoso wildcard’ (or whatever the name that you entered when you created the CSR). The best practice is to create a variable so that it can be changed through WMC. You can do this by clicking the little green dot in the bottom lower corner of the text box.

A1-P3-CI-07-SelectingHTTPSInStudio

Figure 3g. Web Service endpoint with HTTPS/SSL configuration.

Update the ‘Port’ to match the SSL port that your runtime is configured to run. Go back to WMC and stop the orchestration and undeploy it. Coming back to the Studio, publish the project to the runtime appliance using File->Publish Project. Click ‘Save’ if it is asked.

Step # 6: Updating the wrapper class and the stub in Salesforce.

Now, that the web service is secured by HTTPS/SSL certificate, it is time to update the code on the salesforce side. Go back to your browser and login into your salesforce org. Click ‘Edit’ against the file ‘UserStatusClient’ under Setup->Develop->Apex Classes. This will open the class in the editor. Update the endpoint to reflect ‘https’ instead of ‘http’. The code should look like this:

https://<yourservername>/UserManager/UpdateStatus

Replace the <yourservername> with the actual server name. Click ‘Save’. Click ‘Edit’ against the file ‘UserStatusWsdl’ under Setup->Develop->Apex Classes and update the endpoint to reflect ‘https’ instead of ‘http’ as shown above. Click ‘Save’.

Step # 7: Update the remote site settings

As explained in the previous article, the external domain should be added to the remote site settings so that Salesforce allows outbound calls. We had already did this in the previous article, but that is for ‘http’ based one; here we will update this entry to reflect ‘https’ instead of ‘http’ as shown below:

A1-P3-CI-08-RemoteSiteSettings

Figure 3h. Remote site settings

Click ‘Save’ after updating the entry.

We just completed setting up the one-way SSL/certificate authentication. Go back to the ‘Users’ page under Setup->Manager Users and repeat the test that was done in the Part-2. You should be able to see the status got updated in your database table. The communication between the server and the client now happens through HTTPS/SSL. You can verify this by using Fiddler or HTTP Watch.

Summary

This article covered the basics of certificates and SSL and continued to add the feature to setup the one-way SSL/certificate right from generating the CSR to installing the certificate into the key store. We also saw how to update the code and the settings on the Salesforce side to call the web service over HTTPS. The source for the updated cast iron studio project and the salesforce code can be downloaded from here. The Part-4 of this article series will now update this solution to include two-way SSL/certificate. Stay tuned.

Advertisements

Tagged: , , , , , ,

11 thoughts on “Making authenticated web service callouts from Salesforce to IBM Cast Iron using SSL/certificates–Part III

  1. […] Part-3 Tutorial 2: Setting up one-way SSL authentication […]

  2. Jinesh June 3, 2012 at 5:11 pm Reply

    Hi Hari,

    I have requirement in which SSL has to be implemented between salesforce and some files hosted on server.Those files are static files.The URL of the hosted files will be Http:/something.
    I need to access this URL and pass certain parameters to it.I need to implement SSL so that Http will become Https and the what ever parametes are sent from salesforce to the server will not be visible to any one.
    Please correct me if I am wrong .I am planning to implement one was SSL.My understating is that certificate for the server should be generated and installation and configuration changes should me made to the server.Am I thinking correct? .On the salesforce side I will make changes to the remote settings and make URL as Https:

    Now ,Will this ensure that whatever parameters are passed from salesforce to the server will be encrypted.In other words will not be visible to people who try to use tools such as jitterbug etc.

    Can u please answer this as soon as possible?.

    • Hari Krishnan June 4, 2012 at 5:23 am Reply

      Jinesh,
      1. If you files are static, you cannot pass the parameters (actually, you can, but if it is just a static file, those parameters will be ignored)
      2. If you use HTTPS, everything will be encrypted and the user cannot view the content. However, there are some tools like fiddler that can capture even the HTTPS traffic and decrypt it, but you no need to worry about this as this is a development thing.
      3. Yes, you need to get a public CA signed certificate and install the certificate in your server.

      • jinesh June 4, 2012 at 2:30 pm Reply

        HI Hari,

        Thanks a lot for answering these questions.

        We are working with the vendor and integrating salesforce with his website .Since he has some security issue therefore we are hosting some of his files on our server on HTPPS(443) port.

        Salesforce———server(https 443) —————–server will be redirected to the their website and that website will be visible to the customers.

        Here is what we will be doing:-

        1)We will be passing parameters from client(salesforce) to the server on which we have our files hosted.
        2)Since the information going from client to the server should not be visible to somebody using tools such as fiddler.So in order to accomplish this.Do I need to have one was SSL or two way SSL.?It looks like from your previous post that installation of certtificate on the server side will be enough to secure data transmitted from client to the server.So One was SSL should be enough.

        3)We are working on the design and then I have to do development as well.So I am not sure what we have to do to make sure tools such as Fiddler are not able to see transmitted data from salesforce to the server.Any insights into it.

        If Https information can still be seen by people using fiddler then what is the purpose of using Https

        Your expertise or any kind of help will be highly appreciated,It is needed as soon as possible.

        Thanks,
        Jinesh

        • Hari Krishnan June 5, 2012 at 4:39 am Reply

          Jinesh,
          1. In your case, one-way SSL authentication should be fine, unless, you want to make sure that only Salesforce can call your service. Otherwise, anybody who has the link can post data to your service if they know your service address.
          2. You can capture the HTTPS traffic using Fiddler only in a development environment where you have absolute control. What this means is that, the Fiddler will install a root certificate in your local trust store when you enable capturing HTTPS traffic in the Fiddler tool. Once this is done, when you browse through a HTTPS site, the Fiddler will start catching the traffic and will decrypt the content for you. To test this, install the Fiddler tool and enable the ‘Decrypt HTTPS traffic’ under Tools->Fiddler Options->HTTPS. Then, go to gmail.com and enter your user name and password and sign in. The Fiddler tool would have decrypted the content for you now. But as I said, this can happen only when you have the absolute control. A third person cannot decrypt your traffic from outside of your workstation.

          Regards,
          Hari Krishnan.

  3. betelgeuzeb March 27, 2013 at 11:57 am Reply

    Hi Hari,

    I need your help. Please advise how do i set up so that i can include the intermediate certs. I’ve checked it and its not configured correctly. I’ve got my cert from namecheap rapidssl-geotrust and i dont know how to go about getting it properly setup. just uploading the key in my keystore and the intermediate in the trust store doesn’t work. Please advise. I dont know how to operate the cast iron box thru the management console. It was setup by a previous vendor.

    • Hari Krishnan March 28, 2013 at 4:46 am Reply

      Hi Betelguezeb,
      Please check the documentation from your SSL provider and they should have the guide about setting up their certs. They may not cover the setup for Cast Iron, but you can infer from the guidelines that they may have for Apache/IIS or from the general setup instructions. They also should have some tool to troubleshoot if the certs are configured properly. Digi Cert has a tool (https://www.digicert.com/util/) and you may want to try that tool to see if there is any issue with the configuration on your cast iron server. Also, make sure that the certificate authority/provider is supported by Salesforce. You can check that here.

      As far as the Cast Iron, you can check the docs here to learn about configuring. The certification configuration help can be found under ‘Cast Iron Web Management Console->Security’ section. Another good resource would be the Getting Started with the Cast Iron Integration document.

      Hope this helps.

      Regards,
      Hari Krishnan.

  4. R September 13, 2013 at 12:54 am Reply

    Hari,
    Is Salesforce okay with our apps making calls to services that have wildcard certs? I’ve been told they usually frown upon this; wondering if this will affect our security review, in your experience.

    Great article. Thanks.

    • Hari Krishnan September 13, 2013 at 1:16 am Reply

      I’m pretty sure that there should not be any issue in using wild card certificates on your on-premise servers to be consumed by your apex classes/outbound SOAP messages in Salesforce, as this is exactly we have implemented.

  5. Vijayalakshmi Yalamanchili April 26, 2015 at 3:57 am Reply

    Awesome blogs by you.. keep going!!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: