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.
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.
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:
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.
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.
Figure 3d. CSR information
Click ‘Upload’ and this should show the following dialog box.
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:
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.
Figure 3g. Client SSL Settings section.
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.
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:
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:
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.
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.