Tag Archives: Integration

Securing IBM WebSphere Cast Iron Appliance while integrating with Salesforce-Part IV

Introduction

This article series discusses about securing IBM Websphere Cast Iron Appliance when integrating with Salesforce. In the previous articles, we discussed about the security challenges and some of the methods to address those challenges including protecting the enterprise network using Firewall, SSL/Certificate based authentication. In this article, we will see how requests from cross-organization to cross-environment (from Salesforce to on-premise) can be prevented. This method also protects your organization’s web services from being accessed from other enterprises who are co-located along with your organization’s orgs. Implementing this method along with the solutions described in the previous articles is a powerful method that will secure your enterprises web services from almost any type of unauthorized access.

Background

In a typical enterprise, multiple environments are created to promote development to production. The usual model is to have one single environment for DEV, one for QA, one for Staging and another for Production. The number of environments may vary depending on the organization’s needs, but the bottom line is that there will be multiple organizations (Sandboxes) on the Salesforce side and matching environments at on-premise with mapping from Salesforce orgs to these local environments. At on-premise, each of these environments are either physically or logically separated using various technologies such as NAT and firewall rules are implemented to prevent cross environment access such that DEV servers can talk only to other DEV servers, QA servers can talk to other QA servers, etc. The bottom line is that applications from one environment cannot call into the applications/databases/services in another environment. But this type of implementation is not possible with Salesforce, because Salesforce doesn’t have the concept that we just explained above. Further we explained in part-2 about how the requests originates from Salesforce. To recap, Salesforce has a set of IP addresses for each region (such as North America, Asia Pacific, etc…) and the web service callouts made by the Salesforce client applications carry one of this IP address as their source address. Salesforce doesn’t have the concept of different network segments for the web service callouts, hence by default, there is no way for the enterprises to distinguish the requests to identify if it come from sandbox or production org or even from their own orgs. But not all is lost. The solution proposed here will address this problem, by not only, preventing the cross-organization to cross-environment access, but also prevents access from other enterprises orgs.

Solution

The solution to this problem involves some custom coding along with a Salesforce provided feature called ‘Organization Id’. Every Salesforce organization has a unique identifier called ‘Organization Id’. The ‘Organization Id’ can be found under Your Name | Setup | Administration Setup | Company Profile | Company Information.

A2-P4-01-OrganizationId[4]

Figure 1: Getting the Organization Id

The ‘Organization Id’ is unique for each Salesforce org. It is not only unique with your enterprise’s Salesforce orgs, but also unique universally across all orgs of all it’s clients. That means that if your web service client in Salesforce embed this ‘Organization Id’ in the request, then a web service can catch that and can prevent the call from executing if the ‘Organization Id’ is not in their access control list. This is what exactly we are going to do that. Here is a simple flowchart that describes this technique.

OrgValidation-FlowChart[4]

Figure 2: Flow chart that depicts the solution

As shown in the flowchart above, the client (Salesforce) will send the ‘Organization Id’ along with the input payload when it makes a web service callout to the Cast Iron. Apex provides the User API through which the ‘Organization Id’ can be retrieved which suits well for apex code. We get the ‘Organization Id’ from this object and embed it in the HTTP headers. For outbound SOAP messages, the outbound workflow action itself provides the ‘Organization Id’. Cast Iron will retrieve the ‘Organization Id’ from the request and validates against it’s configuration. If the ‘Organization Id’ matches, it continue to process, otherwise, the web service exits immediately, returning an error code. The following sections will provide step by step details along with the necessary code that implements this pattern.

Developing the OrgValidationService Cast Iron Orchestration

Since we want to validate all the incoming requests, it is best to develop the validation as a separate web service, so that all other web services can call this one web service to validate the ‘Organization Id’. We will call this as ‘OrgValidationService’. This web service will be consumed by all other Cast Iron web services that want to validate the organization ids. The following image is extracted from the Cast Iron studio that depicts the flow.

A2-P4-CI-01-OrgValidationService[4]

Figure 3: OrgValidationService

Previously, we saw that the client has to send the ‘Organization Id’ along with the input payload. This can be done with couple of ways. I preferred to embed the ‘Organization Id’ as part of the HTTP headers, because, this is less intrusive. Had we chose to embed this as part of the input request parameters, instead of putting into HTTP headers, then the XML schema for all of these web services need to be updated to include the ‘Organization Id’ parameter. Here is the logic:

  • The web service receives the input parameter and assigns it to input variable named ‘objOrgInfoRequest’. While assigning we filter it for the value ‘Organization Id’. Please note that apart from the HTTP headers, you will also notice another parameter named ‘OrganizationId’, which will be used if web service callout is made by outbound SOAP message. The following screenshot shows how the ‘Organization Id’ is passed through the HTTP headers.

A2-P4-CI-02-OrgInfo-HTTPHeaders-Mapping[4]

Figure 4: Filtering the input headers to get the ‘Organization Id’

  • The valid ‘Organization Id’ for that particular environment is configured in a variable named ‘OrgIdLookup’. This is retrieved and assigned to a variable.
  • The web service checks the ‘Organization Id’ that came as part of the input parameter and checks against this configured value.
  • If it matches, then it assigns the status to ‘true’, otherwise, it assigns the status ‘false’.

The code for this orchestration can be downloaded from here.

Developing the Test Web Service Cast Iron Orchestration

The Test Web Service Cast Iron orchestration will serve as an example of how the regular Cast Iron orchestrations (that will be developed to support your organization’s business requirements) should utilize the OrgValidationService to validate the ‘Organization Id’. The following image is extracted from the Cast Iron studio.

A2-P4-CI-03-TestRequestService[3]

Figure 5: TestRequestService Web Service to be consumed by Apex code.

This orchestration is exposed as a web service which will be consumed by your apex code. It copies the HTTP headers to a local variable and calls the OrgValidationService passing this variable. If the return value from the OrgValidationService is true, then the orchestration proceeds to execute, otherwise, it terminates immediately. The code for this orchestration can be downloaded from here.

Consuming the OrgValidationService in Salesforce

There are couple of ways the Salesforce can be programmed/configured to consume a web service that is hosted elsewhere. The right solution depends on the needs, but they are as follows:

  • Apex code
  • Outbound SOAP message
  • AppExchange App

Consuming the Test Web Service from Salesforce (through Apex code)

With apex code option, the consuming the Test Web Service from Salesforce is done completely by coding in Apex. Developers choose this option when they want to

  • pull data from multiple objects and pass them as input parameters
  • process the data and derive the input parameters for the web service

Here are the steps to consume the test web service from Salesforce using the apex code.

  • Generate the WSDL from the Cast Iron web service and save it to a folder
  • Login into your dev/sandbox org and go to the section ‘Apex Classes’ under Your Name | Setup | App Setup | Develop.
  • Click ‘Generate from WSDL’ and choose the file that you saved from the Cast Iron studio.
  • If you want to rename the default names provided by the import wizard, go ahead and change the file names. I renamed the files as follows:

A2-P4-CI-05-GenerateFromWsdl[4]

Figure 6: Naming the system generated classes in Salesforce

  • Click ‘Generate Apex Code’ button and click ‘Done’.

Now we need to create a wrapper class that utilizes the stub generated by the import wizard. To do this, click ‘New’ under Your Name | Setup | Develop | Apex Classes. Copy the code given below. This code consumes the test web service by utilizing the stub that we just generated.

public class TestRequestServiceClient {
    @future (callout=true)
    public static void Test() {
        Boolean isSuccess = true;
        try {
            TestRequestServiceWsdl.Provide_ServicePort binding = buildService();
            List<TestRequestServiceRequest.TestRequest_element > elementList = new List<TestRequestServiceRequest.TestRequest_element >();
            TestRequestServiceRequest.TestRequest_element element = new TestRequestServiceRequest.TestRequest_element ();
            binding.Provide_Service('1', 'Test');
            isSuccess = true;
        } catch (Exception e) {
            isSuccess = false;
        }
        //return;
    }
    private static TestRequestServiceWsdl.Provide_ServicePort buildService() {
        TestRequestServiceWsdl.Provide_ServicePort updateStatusInstance = new TestRequestServiceWsdl.Provide_ServicePort ();
        updateStatusInstance.endpoint_x         = 'https://yourcastironwebserver:443/TestRequestService';
        updateStatusInstance.inputHttpHeaders_x = new Map<String, String>();
        updateStatusInstance.inputHttpHeaders_x.put('OrganizationId', UserInfo.getOrganizationId());
        updateStatusInstance.inputHttpHeaders_x.put('OrganizationName', UserInfo.getOrganizationName());
        System.debug('\nOrganization Id :' + UserInfo.getOrganizationId());
        updateStatusInstance.timeout_x          = 60000;
        return updateStatusInstance;
    }
}

Click Save.

Consuming the OrgValidationService in Salesforce (outbound SOAP message)

With outbound SOAP message option, the outbound SOAP action sends the ‘Organization Id’ as part of the request payload. This is the reason that we designed our OrgValidationService to accept both HTTP headers and a separate parameter named ‘Organization Id’ to support both scenarios (Apex code and outbound SOAP messages).

Here is the test web service built to be consumed by an outbound SOAP message. The outbound SOAP message definition provides you the WSDL and the following screenshot shows the test web service implmented using this WSDL. The code for this web service can be found here.

A2-P4-CI-04-TestRequestServiceO[3]

Figure 7: ‘TestRequestServiceO’ web service to be consumed by Outbound SOAP message

Now we have completed all the development tasks. Before start testing, you need to perform the following tasks:

  • Deploy all the three Cast Iron orchestrations in your Cast Iron server (preferably in your development environment)
  • In OrgValidationService, configure the ‘OrganizationId’ configuration property to the organization id of the Salesforce org that you are going to test. You can get the organization id from the ‘Company Information’ link under Your Name | Setup | Company Profile‘ as shown in the Figure 1 above. Note that the organization id that is displayed here is 15 digit and you need to use the 18 digit version, as otherwise, your OrgValidationService will fail. [You can get the 18 digit through many ways. One way is to let it run against your cast iron web service and look at the cast iron log and you will find the 18 digit id (set the log level to ‘All’ in your cast iron server).
  • In Salesforce, update the ‘endpoint_x’ variable in the TestRequestServiceWsdl to point to your cast iron server and save it. (I renamed the system generated file to ‘TestRequestServiceWsdl’. If you choose a different name or if you didn’t rename, then the file name will be different in your case.

With this, we are all set to test it. Invoke the developer console from Your Name | Developer Console and execute the following: TestRequestServiceClient.Test(); Now if you open the debug logs, you will see that the call succeeded. If you check your Cast Iron logs, you would see log message titled either ‘Request came from authorized organization’ or ‘Request came from unauthorized organization’ depending on what value you have configured for the ‘Organization Id’ configuration property in the OrgValidationService orchestration.

Summary

This article is the fourth in the five part article series. The first part described the security challenges. The second part explained how the enterprise can use firewall to filter unwanted traffic other than the trusted networks. The third part continued to explain about transport level encryption. The fifth part will now explain about authorizing the trusted users. This scenario is particularly important if you are going to use Cast Iron server to integrate with other systems including other cloud services such as Docusign, Amazon elastic cloud, Windows Azure, etc.

Advertisements

Securing IBM WebSphere Cast Iron Appliance while integrating with Salesforce-Part I

Introduction

The IBM WebSphere Cast Iron is a cloud integration platform that enables enterprises to integrate applications without any traditional coding. While the IBM Websphere Cast Iron can be used for almost any type of integration, it is most widely used to integrate the Cloud applications (SaaS, PaaS) with the on-premise applications. Integrating cloud applications with the traditional on-premise applications introduces some new challenges, particularly, in terms of security. An organization needs to carefully design their network security in order to avoid any pitfalls as otherwise it has to face several issues from compliance to customer dissatisfaction to data theft to lawsuits …you name it and you have it. We will see some of the key security questions that needs to be answered when we design our network/application security.

This article series will cover several solutions to secure your Cast Iron server. This is by no means a complete list, but covers most widely used scenarios.

Background

The enterprises typically have a separate network zone called DMZ through which all the communication from internal systems & applications that interact with the public network goes through. It is a common and best practice to deploy the Cast Iron server in this DMZ which acts like a middle-tier that integrates the cloud applications with on-premise applications. The following snapshot provides a rough idea on how this looks in a typical enterprise.

CI-01

This architecture offers several advantages such as

  • a central place to manage all your incoming / outgoing requests
  • need to open only the required ports, specifically, HTTP/S ports

Since this is going to be a gateway to your enterprise applications, securing the Cast Iron server is very important as explained in the ‘Introduction’ section. Several key questions arise while designing the security for integrating Salesforce cloud with our on-premise solutions using IBM Websphere Cast Iron server.

  • What systems can access our Cast Iron server?
  • Who can be allowed to access our Cast Iron server?
  • Will the data be encrypted? If so, do we need to have the clients prove its identity?
  • How do we make sure cross org/environment calls are blocked?
  • What type of authentication do we need to use?

As you can guess, there is no single solution that can satisfy all the security requirements and we need to implement multiple solutions in order to secure the organization’s integration assets. This article is going to address these questions and will propose multiple solutions answering all these questions. Now, some of the questions may not be an issue at all for some organizations and in those cases, it is okay to not implement them. For e.g. two-way SSL authentication may not be necessary, provided, firewall access restrictions, one-way SSL authentication along with Organization based authentication are implemented.

This article series will provide in-depth insight along with practical solutions to address the security concerns. The article series will be divided as follows:

Let’s dive into the details. The Part-2 of this article series will discuss about the Firewall Access Restriction.

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

Introduction

This article is the fifth and final in the five part article series on making authenticated web service callouts from Salesforce to IBM WebSphere Cast Iron. In this article, we will cover some of the issues that we come across in implementing SSL/Certificate based security and the solution to fix them. This is not an exhaustive list, but these are the most common problems one may face while implementing this type of security.

Certificate issues

PKIX path building failed

Exception message

sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Solution

This exception can happen due to various reasons. The following list of actions might solve this issue.

  • If you are using two-way certificate authentication, then check whether you have included the certificate on your client side when you make the web service callout.
  • Make sure the certificate is not expired and valid.
  • Make sure to include the certificate if you enable two-way certificate authentication.

IO Exception: DER input, Integer tag error

Exception message

IO Exception: DER input, Integer tag error

Solution:

This exception can happen due to various reasons.

  • As explained previously, Salesforce will accept PKCS#12 certificates; if your certificate is DER/PEM, then you will receive this error. Once you use the PKCS#12 certificate this error should go away.
  • When you embed the third party certificate in the code and if the certificate content is tampered or if you incorrectly paste the certificate content, then you will receive this error

SSLPeerUnverifiedException: peer not authenticated

Exception message:

 javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated.

Solution:

There are many situations where this error can happen. This can be summarized as:

  • If your certificate has a chain of trust (which means that the certificate has intermediate certificates), then the order of the certificates in the chain has to be correct. The order is defined as follows:
    • The server certificate
    • The intermediate certificate that have signed your server certificate (only if the server certificate is not signed by root certificate)
    • The intermediate certificate that signed the above intermediate certificate
    • Include all the intermediate certificates as defined in the previous certificate except the root CA (this is usually already available in your server’s trust store)
  • One or more of the certificate in the chain has expired or not valid.
  • One or more of the intermediate certificate in the chain is missing.
  • One or more of the certificate in the chain is either a self-signed certificate or not trusted by Salesforce. The list of the CA that Salesforce supports can be found here.

IO Exception: Unable to tunnel through proxy.

Exception message:

IO Exception: Unable to tunnel through proxy. Proxy returns \"HTTP/1.0 503 Service unavailable

Solution:

This error happens if your firewall doesn’t allow access to your server where the web service is hosted. Making the firewall changes should fix this issue.

In general, when you see an issue, follow this check list to troubleshoot the issue:

  • Make sure you have the firewall settings in your enterprise is configured to allow the inbound web service call.
  • Check whether the certificate is expired or not.
  • Check if your chain of trust has valid certificates.
  • Make sure you embed the PKCS#12 certificate on the Salesforce side when you make a web service callout.

Most vendors provide tools to check your server/certificate. DigiCert’s tool can ping your server and retrieve the certificate and can provide you the report. Similarly, Verisign has its own tool to validate the certificates.

Conclusion:

This article series had in-depth analysis of how to make authenticated web service callouts from Salesforce to IBM WebSphere Cast Iron both one-way SSL/Certificate and two-way SSL/Certificates. Though this article uses Salesforce and IBM WebSphere Cast Iron as examples, the concept applies elsewhere whether you are making the authenticated web service callouts from Java client to .NET WCF Web Services or from Windows .NET Azure Web Services to SAP, albeit the implementation details will differ.

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

Introduction

This article is the fourth in the five part article series on making authenticated web service callouts from Salesforce to IBM WebSphere Cast Iron using SSL/certificates. Web Service callouts is a powerful feature and the IBM WebSphere Cast Iron provides great integration capabilities. We discussed the basics of the authenticated callouts and the problem scenario in the first part and implemented a solution without the SSL/certificates in the second part. We also discussed about securing the web service with one-way SSL/certificate authentication in the third part. In this part, we will continue to add two-way SSL/certificates that demonstrates the concept of both the parties proving their identities.

Understanding the two-way SSL

As explained in the third part, the one-way SSL/certificates based authentication allows one of the parties (read ‘server’) to prove its identity to the client(s) based on the PKI mechanism such that the client and the server can exchange communication on a secure medium. This is the most commonly found scenario which is widely implemented by most web sites such as amazon.com, ebay.com, etc. Sometimes, this arrangement is not enough and the server needs to know whom it is talking to. This is particularly relevant when you integrate cloud based services with on-premise or other cloud based systems.

Let’s consider a real scenario. You want to integrate the information from your salesforce platform to your on-premise system – assume you have infrastructure as described in the architecture diagram in Part-2. You can secure your IBM WebSphere Cast Iron server with certificates signed by public CA. You may even put firewall rules to restrict access that allows inbound calls only from salesforce.com servers. (adding *.salesforce.com to firewall will not work. Salesforce has a set of IP ranges and the request may arrive from any of these IP addresses. There is no distinction on the requests to indicate the salesforce organization from where the request originated [the salesforce does send the organization name if it is outbound SOAP message based web service callout]. These IP address ranges has to be added to your firewall to restrict the access to salesforce.com servers). But still there is a gaping hole. If someone knows your endpoint who also is a salesforce user (from a different company; for that matter, it can be an individual from salesforce DE user), then he can very well invoke your web services, provided, you do not have other forms of authentication, built into your orchestration. You can always build such other forms of authentication into your orchestrations, but it may not be versatile.

There’s a better solution available which is the two-way SSL/certificates based authentication. In this method, the client, as well, provides its identity to the server to prove it’s identity. This is much better, because, in most cases, this is just a configuration task, especially on the IBM WebSphere Cast Iron side. On the client side, it depends on the platform you use – Salesforce does provide both configuration only and code based approaches. This is definitely better than user name/password based authentication, because, if the user name/password is compromised somehow, then the attacker can easily gain access to your systems. Sure, if the attacker gain access to your client’s public key, then it is still a high risk with two-way SSL/certificates approach as well; but for all practical scenarios, this is highly difficult, if not impossible. But the same is not true with user name/password based approach, for e.g. if the attacker uses brute force method and your password is not strong enough to resist it. There’s much more to this and it is out of scope for this article to discuss elaborately and I’ll write more about the security in a future article series.

To summarize, in two-way SSL/certificates based authentication, both the server and the client(s) prove their identities respectively using SSL certificates. As explained in the Part-3, Salesforce will accept only certificates signed by public CA, when it acts as a client and makes a callout to the server. On the contrary, you can use either self-signed certificates, provided you import this certificate into the Key Store of your IBM WebSphere Cast Iron runtime appliance, or you can use certificates signed by public CA (you don’t need to do any thing special on IBM WebSphere Cast Iron side for this). We are going to see this in action in the remainder of this article.

Tutorial-3: Setting up two-way SSL/certificate authentication

The basic concept here is to add the SSL/certificate authentication to the client side. The concept of two-way SSL/certificate authentication is generic to all platforms and technologies, though the implementation could slightly differ. From Salesforce perspective, there are two ways to accomplish this. They are as follows:

  • Certificate generated from non-Salesforce

  • Certificate generated from Salesforce

In both the scenarios, we can either use self-signed certificates or certificates signed by public CA. This article will explain both these approaches for the above two scenarios.

Certificate generated from non-Salesforce

This is also called the ‘Legacy’ method by Salesforce. In this scenario, we generate the CSR from non-Salesforce system, such as Windows Active Directory Services or Open SSL. This involves some coding work on the Salesforce side which will be explained later.

Self-Signed Certificates

With the self-signed certificates, we can have our own CA installed in our infrastructure and can generate the CSR and sign it. Self-signed certificates may not work in all occasions; for e.g. if the other end can accept only certificate signed by public CA. Usually, this may happen with SaaS vendors or with any third-party services. For our tutorial, we will use the Open SSL to get the self-signed certificates.

Step # 1: Setting up Open SSL and generating root certificate

Download the Open SSL from www.openssl.org for linux. This tutorial uses the windows distribution of Open SSL.  Open a command prompt, and execute the following commands:

set OPENSSL_CONF=E:\openssl-win32\bin\openssl.cfg
path=%path%;E:\openssl-win32\bin
set RANDFILE=E:\openssl-win32\myca\.rnd

In my workstation, I have installed it under E:\OpenSSL-Win32\. Please replace the drive where you have installed in your workstation.

Now that we have setup the Open SSL, let’s generate the root certificate that will be used to sign the certificate that we will generate in the next step. Before proceeding, let’s cover some basics. A digital certificate is verified using a chain of trust. It is formed as a tree structure and the first node of this tree structure is issued by the Root Certificate Authority and may contain intermediate certificates in the tree structure. The private key of the root certificate is used to sign the other certificates. Each certificate in the certificate chain inherits the trust worthiness of it’s parent certificate which goes all the way up to the root certificate. This is why we need a root certificate before creating the actual certificate, since the private key of the root certificate will be used to sign our certificate. IBM WebSphere Cast Iron normally (like most servers) doesn’t allow a certificate to be imported if the chain of trust is not present, though it does provide an option to bypass it, but this is not a recommended practice.

To generate the root certificate, execute the following command:

openssl req -new -x509 -extensions v3_ca -keyout keys\cakey.pem -out certs\cacert.pem -days 730 -newkey rsa:2048

This command generates a new root certificate with new key which is 2048 bits long.

A1-P4-OS-01-GenerateRootCA

Figure 4a. Generate root certificate

Step # 2: Creating the CSR for client

The Certificate Signing Request (CSR) contains the information about your organization and the public key which the CA validates it before signing it. In this case, we have our own CA which will be used to sign this certificate.

Here is the command to generate the CSR.

openssl req -new -nodes -out certs\contoso.csr -key keys\cakey.pem

A1-P4-OS-02-GenerateCSR

Figure 4b. Create CSR using Open SSL (for self-signed certificate)

This will generate the CSR file under certs\contoso.csr. An important thing to note is that the common name should either exactly match your domain name or should match your domain name with wild card. Wild card is used if you want to use the same certificate for the sub domains. For e.g. the same certificate can be used for the URLs secure.contoso.com, docs.contoso.com, contoso.com, if you use ‘*.contoso.com’ in the common name.  If you use IP address, then note that your clients can access the web service only by IP address, the exception being, if your subjectAlternateName has your DNS name in it (same as common name).

Step # 3: Sign the certificate

Now that we have the CSR generated, it needs to be signed which can be done by the following command.

openssl ca -policy policy_anything -cert certs/cacert.pem -in certs/contoso.csr -keyfile keys/cakey.pem -days 730 -out certs/contoso.cer

A1-P4-OS-03-SignCertificateWithRootCA

Figure 4c. Sign the certificate using Open SSL

The above command instructs to sign the CSR using the root certificate that we generated in step # 1 using the private key and set the certificate to expire in 2 years.

IBM WebSphere Cast Iron can accept only PKCS#12 formatted certificates and hence we need to convert our PEM formatted certificate to PKCS#12 format. This can be accomplished by the following command:

openssl pkcs12 -export -out certs/contoso.p12 -in certs/contoso.cer -inkey keys/cakey.pem

A1-P4-OS-04-ConvertPEM2PKCS12

Figure 4d. Convert the PEM encoded certificate to PKCS#12 format

Step # 4: Import the root certificate and self-signed certificate into IBM WebSphere Cast Iron runtime appliance

Most servers including IBM WebSphere Cast Iron ships with root certificates for most of the vendors such as Verisign, Thawte, etc. But since we are using the self signed certificates which is signed by our own CA that we setup in the step # 1, we first need to import the root certificate into the Trust Store.

To do this, click ‘Import’ under the ‘Trust Store’ section of Security->Certificates. This will open up a dialog box. You can either select the file or paste the content from the certificate file. Click ‘Browse’ and select the file and click ‘Open’. Click ‘Import’ and the certificate should be imported into your Trust Store now.

To import the self signed certificate, click ‘Import’ under the ‘Key Store’ section of Security->Certificates. This will open up a dialog box. You can either select the file or paste the content from the certificate file. Click ‘Browse’ and select the file and click ‘Open’. Enter the password that you used to generate the self signed certificate. Click ‘Import’ and the certificate should be imported into your Key Store now.

Step # 5: Update the code to embed the certificate in the web service callout

The web service callout code needs to be updated to include the certificate in the call for the two-way authentication. The certificate that we have now is in PKCS12 format which is a binary format and we need the text version (PEM) of it to embed it into the code. To get this, execute the following command:

openssl base64 -in certs/contoso.p12 -out certs/contoso.pem

Open the contoso.pem file in a text editor and copy the content. Now, update the UserStatusClient file on the Salesforce side by clicking ‘Edit’ against ‘UserStatusClient’ under Setup->Develop->Apex Classes.

string key = ''; // paste the content that you copied from the contoso.pem file.
updateStatusInstance.clientCert_x = key;
updateStatusInstance.clientCertPasswd_x = 'xxxxxx'; // enter the password that you put when you generated the certificate.

Test it by updating the test user’s status and you should see that it has made a web service callout with two-way authentication.

Public CA Signed Certificates

The biggest advantage of getting the certificate signed by public CA is that you there is no need to import the certificate in the target server, as in the case of self-signed certificates, as the web/application server(s) trust the certificates signed by public CA’s. This will really helpful where the user doesn’t have control or a way to import the self-signed certificates into the target server’s Trust/Key Store.

In this scenario, we will see how to get the certificate signed by public CA using CSR generated from Open SSL.

Step # 1: Creating the CSR for client

To create the CSR, you can follow the same steps as described in the step # 2 of the previous section.

Step # 2: Get the certificate signed from public CA

Submit the CSR to your preferred public CA (should be supported by Salesforce) and get it signed.

Step # 3: Update the code to embed the certificate in the web service callout

Follow the same steps as described in the step # 5 of the previous section to update the wrapper class in Salesforce to include the certificate when making the web service callout.

Test it by updating the user’s status and you should see that it has made a web service callout with two-way authentication. And as described above, you don’t need to import the certificate into IBM WebSphere Cast Iron runtime appliance as the server can accept the certificate passed by the salesforce since it is signed by public CA.

Certificate generated from Salesforce

Salesforce provides the option to generate the Certificate from its platform and this is the suggested method by Salesforce. The biggest advantage is that the private key is not shared outside of the Salesforce and the caveat is that you will not be able to use this certificate from any other system, other than the Salesforce, since you cannot get the private key when you download the certificate from Salesforce. This section will also cover both the scenarios; self-signed certificates and certificate signed by public CA, but this time the Certificate is generated from the Salesforce.

Self-Signed Certificates

Step # 1: Creating self-signed certificate the CSR for client

To generate the certificate from Salesforce, login into your Salesforce organization and click ‘Create Self-Signed Certificate’ under Setup->Security Controls (under Administration Setup)->Certificate and Key Management. Enter the information as below.

A1-P4-SF-01-GeneratedSelfSignedCSR

Figure 4e. Create self-signed certificate from Salesforce.

Click ‘Save’ and it should show you the screen as below.

A1-P4-SF-01-GenerateSelfSignedCSR

Figure 4f. Self-signed certificate generated in Salesforce.

Step # 2: Update the code to reference the certificate in the web service callout

Since the certificate is now residing within Salesforce, we don’t need to embed the certificate in the web service callout; instead, we can just reference the certificate name in the code and Salesforce runtime automatically embeds the certificate in the callout. Update the UserStatusClient file on the Salesforce side by clicking ‘Edit’ against ‘UserStatusClient’ under Setup->Develop->Apex Classes

updateStatusInstance.clientCertName_x = 'Contoso_SF';
updateStatusInstance.clientCertPasswd_x = 'test';

Public CA Signed Certificates

Step # 1: Creating the CSR for client

To get the certificate signed by public CA that is generated from Salesforce, click ‘Create CA-Signed Certificate’ under Setup->Security Controls-> (under Administration Setup)->Certificate and Key Management. Enter the information as below.

A1-P4-SF-01-GenerateCSR-PublicCA

Figure 4g. Create CSR from Salesforce.

Click ‘Save’.

Step # 2: Get the certificate signed from public CA and Upload to Salesforce

Download the CSR by clicking ‘Download Certificate Signing Request’ button and submit this CSR to your preferred public CA and get it signed. Once you receive the signed certificate, upload it by clicking ‘Upload Signed Certificate’ button.

Step # 3: Update the code to reference the certificate in the web service callout

This is similar as described in the previous section; i.e., since the certificate is residing within Salesforce, we don’t need to embed the certificate in the web service callout; instead, we can just reference the certificate name in the code and Salesforce runtime automatically embeds the certificate in the callout. Update the UserStatusClient file on the Salesforce side by clicking ‘Edit’ against ‘UserStatusClient’ under Setup->Develop->Apex Classes

updateStatusInstance.clientCertName_x = 'Contoso_SF_PCA';
updateStatusInstance.clientCertPasswd_x = 'test';

Summary

In this article, we saw how to make two-way authenticated calls using SSL/certificates including some of the fundamentals about the certificates and how they work. In Part-5, which is also the final piece of this article series, we will see some common issues and how to fix them.

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.

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.
%d bloggers like this: