Configure and Use Web Service Client Side Certificates

Configure and Use Web Service Client Side Certificates

  
To increase the security of your Web Services or to access secure web services you might require / want to use Client Side Certificates in your Web Services or Web References. This post explains how that can be achieved in the Agile Platform and what are the requirements of this feature.


Requiring Client Side Certificates in my Web Services

On the WebService definition side, requiring a Client Side Certificate is a simple matter of declaring (in Service Studio) that the Web Service uses SSL With Client Certificates HTTP Security, like this:

              

With this, your Web Service methods will only be executed when called in an HTTPS connection where Client Certificates are provided by the caller. If you require further validation of whether the owner of the certificate has privileges to call a certain method, you can use the  ClientCertificateGetDetails and  ClientCertificateValue actions to access information from the certificate. These actions are system actions which you will need to import using Add/Remove references.

              



Calling a Web Service which requires Client Side Certificates

On the Web Reference side, if a Web Service you're calling within Service Studio requires a Client Side Certificate you'll need to import the web reference and configure in Service Center which certificate to send when calling this web reference.

You need to add the certificate in Service Center (Administration > Certificates) by providing a filesystem path to the file.

Please note that:
  • The only kind of certificates that are valid for use in this functionality are X509 Certificates in DER encoding (therefore without a password).
  • In a farm environment this file will need to be on the same path in ALL front-ends.


              

After having a certificate configured in Service Center you'll need to go to the eSpace's Web Services tab, click on the Web Reference and configure it to send this Client Certificate:


              

              
After this don't forget to publish the eSpace in order for the changes to take effect (we recommend you to delete this eSpace data from the share folder).

If you have any questions or would like to add information about this, feel free to reply to this post.

With best regards,
Ricardo Silva, Engineering Services
Hi Ricardo,
Just want to congratulate you about this very interesting and usefull post.
It's also about an issue that I know that will be necessary in a project in which I'm working on now.
Nice work..:)

Best Regards,
Gonçalo Martins 
Hi guys
 
I would like to add some details to the "certificate" part. Ricardo indicated beforehand that we only support X509 certificates in DER format (hence without a password set). We recently detected that this information is incomplete - especialy because typically you will be given a PFX or similar certificate, with a private key protected by password - so just exporting the public key out of the PFX will not do.
 
To create the certificate which you will use (with the above instructions) please proceed as follows. These instructions need to be executed in all front-ends:
 
 
A. Load the client certificate into the machine store:
  1. Open MMC Console (Start -> Run -> mmc.exe)
  2. File -> Add/Remove Snap-in;
  3. Choose Certificates from the left column and click Add;
  4. Choose Computer Account, click Next and click Finish. Close the dialog with Ok;
  5. In the certificate list, right-click Personal and choose All Tasks -> Import
  6. Follow the wizard to import the PFX certificate - you will be prompted for the password at some point;
  7. This will import the certificates into Personal\Certificates.

B. Grant access to the certificates to IIS
  1. Right-click on the certificates you just imported and access All Tasks -> Manage Private keys ...
  2. Add users/groups NETWORK SERVICE and IIS_IUSRS (Windows 2008R2) or IIS_WPG (Windows 2003) with Full Control access. Click Apply and close the dialog.

C. Export the public key into X509 DER format
  1. Right-click the certificate and access All Tasks -> Export ...
  2. In the export wizard choose not to export the private key and  pick either encoded binary X.509 (CER) or Base-64 encoded X.509 (CER). Save the file into a folder (use the same path - folder and filename - in all front-ends).
 
After having done this, follow the instructions in the first post to create the certificate and associate it to the web-reference.

 
Kudos to Miguel João for the hard work figuring this out!

 
With best regards,
Acácio
How can i do Step B in windows 2003?
In Windows 2003 step B is indeed a little different since the UI for the Certificates management in MMC does not allow you to manage who has access to the private keys. In order to manage these permissions you'll need to use the command line tool winhttpscertconfig.

You can get the set of tools containing this particular tool from here.

Now you can run the following commands to grant the necessary privileges to the NETWORK SERVICE account and the IIS_WPG group:

winhttpcertcfg -g -c LOCAL_MACHINE\My -s "<subject>" -a "IIS_WPG"
winhttpcertcfg -g -c LOCAL_MACHINE\My -s "<subject>" -a "NETWORK SERVICE"

In the above commands you will need to replace <subject> with the name to whom the certificate was issued.



This should allow you to use Client Side Certificates on a Windows 2003 Server machine.


If you run into additional problems, feel free to contact us or reply to this thread. 
HI all,

The same can be achieved with openssl commands:
Converting PFX to PEM (requests certificate password):
openssl.exe pkcs12 -in certificate.pfx -out certificate.pem -nodes
Converting PEM to DEM:
openssl.exe x509 -outform der -in certificate.pem -out certificate.der

Complete set of conversion options available from arungp's guid on "How to Convert certificates between PEM, DER, P7B/PKCS#7, PFX/PKCS#12".
OpenSSL for windows platform available here.

Kind Regards, 
João Grazina

Hi,
i enabled SSL on my Linux server by changing standalone-outsystems.xml file and https enabled with non trust certificate as i made it as a local certificate, now i asked the administartor to create a trusted certificate to avoid the certifiace error for end user and he send me PFX file, i added the file to server.keystore and after restarting the JBOSS the HTTPS pages are not avaiable
would you please hel me with this
Using version 7.0 i followed all the steps and i still get this error "The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel."
The certificate is not self signed

Anyone knows what can be wrong? thx in advance
I have a question..Where do we give the certificate password in this case.When I tried to do like this it is giving me unauthorized error.the service i am trying to consume is using ssl certificate. 
You put in the Certificate password when you're importing it to the machine's certificate store.

Note that the .cer file on disk serves to identify the certificate to use, but the private key is stored in the machine's certificate store, using the procedure provided by Acácio.
beside 1 way authentication can we do mutual authentication ?
Hi,

how do we use the certificate to access the WSDL inside Service Studio?

Regards
António Braz
@António, what do you mean?

Service Studio itself only accesses the WSDL which shouldn't require a client side certificate. If, in your case, it does, you should obtain the WSDL from other means and import it without this requirement.
I have a WSDL that requires Client Certificate. All call to that domain requires the certificate.
It's not a public webservice and the provider requires this level of security.

There is no way to do this without importing through a file?
Here's the print screen
nope. You'll need to download the file / files and import it this way.
The WSDL has lots of <imports> and this is not a easy task
You can probably use SOAPUI for the task.
I'll try. It is possible one way or the other, but place this request in your backlog for future releases.

Regards
AB

Folks, the response from Ricardo ALMOST got me what I need. Simply put, I am trying to setup a Certificate that is required in order for me to Consumer a given vendor SOAP web service.


<see attached screenshot>

HOWEVER, I can't figure out the "File Path" in the Service Center (Administration > Certificates) screen.

Not knowing a better way, I included the certificate (filename: MyCertNow.cer) in the Resources of my app in a folder called "stuff". In otherwords, the cert file would be at https://<userName>.outsystemscloud.com/MyApp/stuff/MyCertNow.cer


HOWEVER, the File Path does not take http paths but needs a physical hard-drive path.

I even thought maybe it it looking at my workstation path? Tried it no luck.


SO, where should I "store" the certificate file - is in the app Resources good - OR - am I supposed to store it elsewhere?

ALSO - how do I determine the PHYSICAL path on the server of a give Resource??

Thanks! 


Ricardo Silva wrote:

To increase the security of your Web Services or to access secure web services you might require / want to use Client Side Certificates in your Web Services or Web References. This post explains how that can be achieved in the Agile Platform and what are the requirements of this feature.


Requiring Client Side Certificates in my Web Services

On the WebService definition side, requiring a Client Side Certificate is a simple matter of declaring (in Service Studio) that the Web Service uses SSL With Client Certificates HTTP Security, like this:

             

With this, your Web Service methods will only be executed when called in an HTTPS connection where Client Certificates are provided by the caller. If you require further validation of whether the owner of the certificate has privileges to call a certain method, you can use the  ClientCertificateGetDetails and  ClientCertificateValue actions to access information from the certificate. These actions are system actions which you will need to import using Add/Remove references.

             



Calling a Web Service which requires Client Side Certificates

On the Web Reference side, if a Web Service you're calling within Service Studio requires a Client Side Certificate you'll need to import the web reference and configure in Service Center which certificate to send when calling this web reference.

You need to add the certificate in Service Center (Administration > Certificates) by providing a filesystem path to the file.

Please note that:
  • The only kind of certificates that are valid for use in this functionality are X509 Certificates in DER encoding (therefore without a password).
  • In a farm environment this file will need to be on the same path in ALL front-ends.


             

After having a certificate configured in Service Center you'll need to go to the eSpace's Web Services tab, click on the Web Reference and configure it to send this Client Certificate:


             

             
After this don't forget to publish the eSpace in order for the changes to take effect (we recommend you to delete this eSpace data from the share folder).

If you have any questions or would like to add information about this, feel free to reply to this post.

With best regards,
Ricardo Silva, Engineering Services



Bruce Buttles wrote:OKAY - I found my own answer ... digging through the error logs I figured out the path:

C:\OutSystems\Sandboxes\POLZZ3065\Platform Server\running\MtyApp\stuff\MyCertNow.cer


So, now at least the app loads - BUT - it still isn't authenticating ... wish I could see the detailed logs and request/response details ...

Folks, the response from Ricardo ALMOST got me what I need. Simply put, I am trying to setup a Certificate that is required in order for me to Consumer a given vendor SOAP web service.


<see attached screenshot>

HOWEVER, I can't figure out the "File Path" in the Service Center (Administration > Certificates) screen.

Not knowing a better way, I included the certificate (filename: MyCertNow.cer) in the Resources of my app in a folder called "stuff". In otherwords, the cert file would be at https://<userName>.outsystemscloud.com/MyApp/stuff/MyCertNow.cer


HOWEVER, the File Path does not take http paths but needs a physical hard-drive path.

I even thought maybe it it looking at my workstation path? Tried it no luck.


SO, where should I "store" the certificate file - is in the app Resources good - OR - am I supposed to store it elsewhere?

ALSO - how do I determine the PHYSICAL path on the server of a give Resource??

Thanks! 


Ricardo Silva wrote:

To increase the security of your Web Services or to access secure web services you might require / want to use Client Side Certificates in your Web Services or Web References. This post explains how that can be achieved in the Agile Platform and what are the requirements of this feature.


Requiring Client Side Certificates in my Web Services

On the WebService definition side, requiring a Client Side Certificate is a simple matter of declaring (in Service Studio) that the Web Service uses SSL With Client Certificates HTTP Security, like this:

             

With this, your Web Service methods will only be executed when called in an HTTPS connection where Client Certificates are provided by the caller. If you require further validation of whether the owner of the certificate has privileges to call a certain method, you can use the  ClientCertificateGetDetails and  ClientCertificateValue actions to access information from the certificate. These actions are system actions which you will need to import using Add/Remove references.

             



Calling a Web Service which requires Client Side Certificates

On the Web Reference side, if a Web Service you're calling within Service Studio requires a Client Side Certificate you'll need to import the web reference and configure in Service Center which certificate to send when calling this web reference.

You need to add the certificate in Service Center (Administration > Certificates) by providing a filesystem path to the file.

Please note that:
  • The only kind of certificates that are valid for use in this functionality are X509 Certificates in DER encoding (therefore without a password).
  • In a farm environment this file will need to be on the same path in ALL front-ends.


             

After having a certificate configured in Service Center you'll need to go to the eSpace's Web Services tab, click on the Web Reference and configure it to send this Client Certificate:


             

             
After this don't forget to publish the eSpace in order for the changes to take effect (we recommend you to delete this eSpace data from the share folder).

If you have any questions or would like to add information about this, feel free to reply to this post.

With best regards,
Ricardo Silva, Engineering Services