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

Introduction

Salesforce has rich set of features to integrate the data and functionality with other external systems, be it cloud based applications such as Facebook, DocuSign or on-premise systems such as Peoplesoft, SAP, .NET applications. These features allow integration at both directions such as the APEX web services and REST based services that enables the in-bound integrations and the outbound SOAP messages and web service callouts  that enables the out-bound integrations.

Most enterprises use some kind of third party integration products such as IBM WebSphere Cast Iron to integrate between Salesforce and their on-premise systems as these tools offer reduced development time and efficient use of resources.

This article series explains how to make an authenticated web service callouts from Salesforce to IBM Cast Iron which sits within the enterprise network (usually on a DMZ) to integrate with the on-premise systems using the certificates. It will also show how to authenticate using both one-way SSL and two-way SSL and the common problems that may occur and solution to address these problems. All of these topics are addressed in the following articles.
This article series will use Salesforce and IBM WebSphere Cast Iron to demonstrate the two way SSL/certificates concept. The implementation steps are specific to Salesforce and IBM WebSphere Cast Iron, but the concept is very generic and can be applied to any products/services. Each part of this article will also cover the basics before going into the details to help you understand how this works.

X.509 Certificates: A quick primer

The X.509 standard specifies standard formats for public key certificates, certification revocation lists, and many other that is part of the PKI implementation. The X.509 certificates are primarily used to encrypt the traffic between the server and the client with a ‘trusted’ key verified by a third party named Certificate Authority (CA). When an enterprise secure their web server with a certificate signed by a trusted public CA , the client can check the certificate with the CA to verify its authenticity, whenever it communicates with the server. A certificate only verifies that the entity which owns the certificate is same as the entity who runs the domain. The actual encryption of data and transport are all carried through the SSL/TLS.
There are two types of CA available; public CA and private CA. Anybody can run private CA using either commercial software such as Windows Active Directory Certificate Services which comes as part of the Windows Server System or the open source openssl[windows distribution].

Certificate standards and formats


There are various formats of certificates supported by the PKI standards and the following list gives a brief explanation on these formats:
  • PEM – (.pem) PEM certificates are base64 encoded and usually implemented using three separate files; a key file, certificate (can contain multiple certificates in one file)and signing certificate .
  • DER – (.der) DER certificates are base64 encoded and the certificate file can contain only one certificate.
  • PKCS#12 (.p12) – The PKCS#12 format supports multiple certificates, and a key in a standard manner in one single file.
Salesforce accepts  only PKCS#12 format files as a client certificate. This will be further explained in part-4.

One-way SSL

In one-way SSL, the server alone presents the certificate to the client and the client doesn’t provide any certificate to the server to prove the identity. For e.g. when a user does a transaction with ebay.com, it is the server who has to prove its identity to the client; hence the server has to be secured with the certificate and present it to client. The modern browser clients will accept the certificate and show the status in green if the certificate is signed by public CA and is valid. If it is a self-signed certificate or signed by private CA, then the browsers will show the warning.

Two-way SSL

In two-way SSL, both the server and the client proves their identity by exchanging the certificates. This type of security is mostly needed where both the server and the client needs to establish their identities to each other. By exchanging the certificates, both the client and server proves their identities. The digital certificate is used as the identity and this digital certificate should be signed by the Certificate Authority. The Force.com platform only supports certificates signed by public CA such as Verisign, DigiCert, Thawte, etc, when making HTTP/REST/WSDL requests to third party/enterprise server(s). A complete list of the public CA that Force.com platform supports can be found in the saleforce wiki. When making outbound web service callouts, the Salesforce can use either, a certificate signed by public CA or self-signed certificates to present it to the third party/enterprise server(s). We will cover more on this later.

Prerequisites

  • A salesforce org with admin access. If you cannot get admin access to your company’s dev/sandbox org’s, then you can sign up for the developer edition which is free.
  • IBM WebSphere Cast Iron Studio (This article series uses 6.1.0.3 – but I believe any version above 4 should work).
  • IBM WebSphere Cast Iron Appliance
  • Signed certificate (A public CA signed certificate or self-signed certificate)
  • OpenSSL or Windows Active Directory Certificate Services (for self-signed certificate)
  • Windows Certificates MMC (comes default in XP/Windows 7)

Use Case Scenario

The Contoso Corporation has a salesforce implementation where it maintains their work force information. Whenever a user is termed, this information has to be updated in the Contoso Corporation’s internal home grown ERP system. The Contoso Corporation has decided to implement a web service to accept the user information and update their system accordingly. The web service will be designed as a cast iron orchestration and will be called by a trigger attached to the user object. This trigger gets invoked when a user’s status is updated and calls the web service to update the user status in the internal system. (Outbound SOAP messaging is not supported for the User object; hence the trigger approach).
Now that we laid out the basic understanding on the SSL/certificates, let’s go ahead and implement the use case. The Part-2 article of this series will discuss about this.
Advertisements

Tagged: , , , , , ,

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

  1. Gerardo Van der Molen February 6, 2012 at 8:11 pm Reply

    This is a great post! We’re in this exact scenario, but with SSL! Is there a way for you to answer a couple of questions I have? I’m really struggling with this and I have very little time to make it work. Thank you!

    • Hari Krishnan February 7, 2012 at 12:34 am Reply

      Sure. Let me know your questions and I’ll try to answer to my best.

      • Gerardo Van der Molen February 7, 2012 at 11:24 am Reply

        I basically did all you mentioned on the first and second part of your document, the issue is that I need to enable external call outs using SSL. I’ve created a orchestration in CastIron, also I’ve created the connection classes using the SFDC button ‘General from WSDL’. Right now I’m getting the following error when trying to make the call out: IO Exception: java.security.cert.CertificateException: No subject alternative names matching IP address [IP address] found. Do you have any idea where this error is coming from and how to work around it? Thanks a lot!

        • Hari Krishnan February 7, 2012 at 5:09 pm Reply

          On the salesforce side, when you make the callout, you have to use the same name that you specified in ‘DN’ of your certificate. For e.g. if you specified ‘contoso.com’, then you have to use this name in the endpoint_x member variable instead of aliases or IP addresses. After all, the certificate is to prove that the entity that is mentioned in the DN is who owns the domain from where the request is sent to – so it has to match the DN. Make sure you use this same name in ‘Remote Site Settings’ configuration in Salesforce. Let me know if this solves the issue.

          • Gerardo Van der Molen February 7, 2012 at 7:36 pm Reply

            Thank you very much for your quick response, Hari! One thing to clarify, if it’s one-way certificate, is there a need to install a signed CA certificate in SFDC? Or with the certificate installed in Cast Iron is enough? Thank you!

            • Hari Krishnan February 7, 2012 at 7:59 pm Reply

              You are welcome.

              In one-way SSL/certificate, there is NO need to install signed CA certificate in SFDC. I’ll be publishing the 3rd part of this article series tonight and that will cover this scenario.

          • Gerardo Van der Molen February 7, 2012 at 7:46 pm Reply

            We also found that there is no value in DN. There is a value on CN, which is just the IP of the server. Is there anything different to do in that scenario? Thanks again!

            • Hari Krishnan February 7, 2012 at 8:00 pm Reply

              The DN is comprised of CN, OU, and O. You have to use the value in CN on the salesforce side.

              • Gerardo Van der Molen February 7, 2012 at 8:36 pm Reply

                That’s what we did. This is the value of CN on the certificate: CN = 205.203.81.16, and this is the value on endpoint_x member on the Apex class variable: ‘https://205.203.81.16/SFDCToBOBJ’. What is it what we’re missing? Thank you!

                • Hari Krishnan February 7, 2012 at 9:53 pm Reply

                  I suspect there is an issue with your certificate. I tried to validate your certificate through public SSL testers (DigiCert – http://www.digicert.com/help/ and Verisign – https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR1130) and also with openssl installation from my machine – all of them error’d out. Check with your admin and try to get a brand new certificate. Make sure you have all the intermediate certificates also get installed into your castiron runtime.

                  • ariel June 22, 2012 at 8:11 pm Reply

                    Hi, this is a great post!. I work with Gerardo, let me explain the scenario, we are doing an https call, we have a certificate on cast iron, the CN is 205.203.81.16. now digicert cannot enter to that ip because we have firewall rules, but we set all SFDC ids in the firewall so we shouldn’t have any issues. we have an outbound message that points to https://205.203.81.16/SFDCToBOBJ. this is working great, it activate the orchestration. now, we want to make the same call but via apex, an http call. when we do this, it give us the certificate error about the common name. we are not sure why this is happening, if the outbound mesage is working, why is it that the http call is not? do you know if we have to do something different, or if SFDC do different things for an outbound that an http call?. I would really apreciate your help.
                    thanks in advance
                    Ariel
                    Ariel

                    • Hari Krishnan June 22, 2012 at 9:02 pm

                      Hi Ariel,
                      If you use one-way SSL authentication, then there will be no difference between outbound SOAP and Apex approaches. I have used this many times and didn’t find any issue at all. Can you please send me the error? Alternatively, you can forward the error to my email address, which I just sent to your email.

                      Also, please make sure that your Apex code follows what I had posted in that article.

  2. […] the first part of this article series, we briefly touched the topic of X.509 certificates. Let’s dig little […]

  3. sathya January 7, 2013 at 9:43 pm Reply

    Hi Hari, Thanks for wonderful details. It really helps. My requirement is to call the webservice in CastIron that I developed from salesforce with out any certificate. Is this possible? If so, how do I do that. I understand that I need to go with trigger as SOAP format of outbound is not supported. Thanks in advance. – Sathya

  4. Sathya January 16, 2013 at 12:14 am Reply

    Hari,

    I am getting this error when I try to call CI webservice, from sfdc.

    Web service callout failed: Unexpected element. Parser was expecting element ‘http://schemas.xmlsoap.org/soap/envelope/:Envelope’ but found ‘:html’
    Error is in expression ‘{!simulateWebService}’ in component in page productsearch

    any idea would help.

    Thank you
    Sathya

    • Hari Krishnan January 16, 2013 at 4:53 am Reply

      Sathya,
      When you make web service callout from SFDC, as you know, the request and response are SOAP messages and SFDC is expecting a SOAP response, but I guess your CI server is returning some error, may be 404 or 501/503, etc. Since the error information is standard HTML, SFDC is complaining with the error message that you described above. Check your CI logs to see if you see any error. You need to check both system log and job logs. If you don’t find any error, then there might be tunneling issue.

  5. rkbatthula January 16, 2013 at 4:08 pm Reply

    Hi Hari,

    Thanks for the valuable information.

    I have a callout issue “System.CalloutException: IO Exception: DER input, Integer tag error” and I found some related information in your blog. It will be a great help if you can please guide me to resolve the issue.

    I got a certificate from the webservice team which is an executable file and in .p12 format. I have installed that on my desktop and have exported to a text format and used in stub.clientCert_x. This is a new development; I have executed anonymous code block but got the above exception. I understand it is something related to the format/conversion of the certificate so will you please provide me the steps to convert to text to make a successful callout?

    Please let me know if you need any additional information on this issue.

    Thanks for your time and help,
    Ravi

    • Hari Krishnan January 17, 2013 at 2:42 am Reply

      Hi Ravi,
      If you just want to use one-way SSL authentication, then you don’t need to embed the certificate in your code. I assume you are trying to implement two-way SSL authentication. That said, it’s little difficult to write down the step by step instruction in the comments. I have written about this in detail in the 4th part of this article which you can find it here: https://krishhari.wordpress.com/2012/02/16/making-authenticated-web-service-callouts-from-salesforce-to-ibm-cast-iron-using-sslcertificatespart-iv/.

      • rkbatthula January 18, 2013 at 1:44 pm Reply

        Hi Hari,

        Thanks for your response. Your assumption is correct. I am trying to implement two way SSL authentication to link my salesforce application with my organization’s own payment gateway. I have received that certificate from the other team (payment gateway) and they wanted me to use that in callouts (salesforce legacy process). My organization has got its own CA and the question I have, is it mandatory that the issuer should be in salesforce trusted liste to make a successful handshake?
        http://wiki.developerforce.com/page/Outbound_Messaging_SSL_CA_Certificates

        I am not sure but may be this could be the reason why I get “System.CalloutException: IO Exception: DER input, Integer tag error”

        Thought from an architect definitely helps me a lot.

        Thanks again,
        Ravi

        • Hari Krishnan January 24, 2013 at 4:11 am Reply

          That’s right. The certificate that you are going to install in your Cast Iron server has to be signed by public CA that is listed in the link that you mentioned above. You can use self-signed certificate only at the client side; what this means that, when you consume the web service hosted by Cast Iron from your apex code, you can embed the self-signed certificate as part of your request.

  6. amar February 12, 2013 at 1:07 pm Reply

    Hari, I love this article.. it was a in depth article on this subject.
    am i right saying that two way SSL usecase here will only take care of transport level security but still there is some work to be done to encrpt the SOAP message incase of sensitive data being sent from saleforce to on-premise webservice?

    can you please elobarate on encrption techniques supported for this usecase on top of transport level security using 2 way SSL?

    • Hari Krishnan February 13, 2013 at 7:28 am Reply

      Hello Amar,
      That’s pretty much right. With two-way SSL, the transport layer is not only encrypted, but the data transfer happens only after successful handshake. It’s very difficult to have man-in-the-middle attacks since the certificates based authentication is designed to prevent that kind of hacking. Honestly, in my opinion, two-way SSL/Certificate based authentication should be enough if the source and target are limited to just two endpoints; However, if there are multiple hops, then two-way SSL/Certificate based authentication may not be enough, because if the in-between server got compromised, then the request payload is at risk and subject to hacking. In that case, encrypting SOAP message is a must to secure the request payload. All most all stacks such as .NET and java provide mechanisms to encrypt the SOAP messages. If my memory is right, then WCF has built-in bindings to specify SOAP encryption. You can also check the following links to get an idea of how this works:
      How to: Use Certificate Authentication and Message Security in WCF Calling from Windows Forms
      Securing Messages Using Message Security

      • amar February 14, 2013 at 1:20 am Reply

        thanks Hari.
        I appreciate you taking time to respond to our queries

  7. Ankit Sharma January 17, 2014 at 7:32 am Reply

    Hello Mr.Harikrishnan,

    Your post helped me a lot in understanding two way SSL authentication. However I have a following doubt. It would be great if you can help.

    In our case we are making a call out from salesforce to an external server using two way SSL. Server has a certificate which is signed by digicert intermediate certificate (DigiCert SHA2 High Assurance Server CA) which in turn signed by digicert root certificate(DigiCert High Assurance EV Root CA) and salesforce is presenting a self-signed certificate which is installed in servers trust store.

    Still we are not able to make callout because salesforce raises an exception which says “unknown_ca”.

    After researching, I found a list of SSL CA which salesforce supports, the list has 3 digicert ROOT certificates and NO INTERMEDIATE certificates.

    http://wiki.developerforce.com/page/Outbound_Messaging_SSL_CA_Certificates

    So my question is, while salesforce validates the the server certificate does the entire chain of certificates needs to be installed in there trust store? or only the root certificate is enough to validate?

    • Hari Krishnan January 22, 2014 at 4:09 am Reply

      Hello Ankit,
      You need to install all the intermediary certificates in your external web server. Regarding the error, try validating the certificate using openssl and see if you need to install any intermediary certificates in your external server. This article may give you some clue to your problem.

      Best Regards,
      Hari K.

  8. […] Making authenticated web service callouts using ssl […]

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: