Enabling the WS-Security Bizagi API

<< Click to Display Table of Contents >>

Navigation:  » No topics above this level«

Enabling the WS-Security Bizagi API


Bizagi PaaS features a secure and OData-standard compliant API which enables any application to reuse Experience design features in Bizagi.

Through Experience design and other possibilities in this API, you may work with data of My Stuff and trigger actions, execute searches, or even start new cases and complete activities or events, among others.

For more information about the OData API, refer to http://help.bizagi.com/bizagi-paas/en/index.html?api_odata.htm.


In scenarios where using the OData API is not possible, then you as a customer, may choose to use the Bizagi SOAP API.

When setting up the Bizagi SOAP API, it is strongly recommended to enable its WS-Security feature so that such SOAP web services encrypt the message based on the use of X.509 certificates (in addition to the channel being already encrypted by means of TLS/SSL).


This document describes how to enable WS-Security for the Bizagi SOAP API, applicable to environments of Bizagi PaaS.


Preliminary concepts

When encrypting a message based on the used of certificates, note that the following is implied:

Servers where Bizagi processes will be running (applicable to all development, testing, production environments; and staging if applicable), will be using a locally-installed certificate.

This means one certificate per each of the different environments.

Similarly, the servers on your end (i.e, at the customer's systems), which host applications consuming the Bizagi SOAP API, will be using a different locally-installed certificate.

This may also mean one certificate per each of the different environments.

If per environment, more than one server will host the applications invoking the SOAP API, then you will to install the same certificate for each of the servers.

Given that the above certificates are employed to encrypt the message, both Bizagi and the customer applications, may use self-signed certificates without implying any security concerns.

Recall that Bizagi already uses certificates issued by a public Certificate Authority for TLS/SSL support, and that such self-signed certificates are not employed for this purpose.

Self-signed certificates are those which are not issued by a public Certificate Authority, and which you may locally generate by means of SDK tools such as Java's keytool.

Message encryption is enforced by use of the username token profile, as detailed at the official spec in https://www.oasis-open.org/committees/download.php/13392/wss-v1.1-spec-pr-UsernameTokenProfile-01.htm.



The use of different certificates per environment is encouraged simply as a best practice that segregates definitions and access per environments.



Before you start, note that the main prerequisite to start using a certificate-based message encryption for Bizagi PaaS in its SOAP API, is for you, as a customer, to submit a support ticket requesting its use.

Through the support ticket, you will be notified when the setup is ready (certificates have been installed), and you will be provided with the public key and thumbprint for further configuration.


For next steps (generating a self-signed certificate and installing it unto your servers), you will need to download and install a SDK tool providing this possibility such as Java's keytool, or the OpenSSL tool provided by GitHub, as instructed for those steps.


What you need to do

The following outline describes the high-level steps needed to configure the Bizagi SOAP API using WS-Security, parting from already having the public key and thumbprint provided by the Bizagi Support team.

1. Generating your certificate.

2. Installing your certificate.

3. Enabling the WS-Security SOAP API and configuring its parameters.



The same procedure is needed for any applicable Bizagi environment in the cloud (development, testing, production, and staging if applicable).

As usual, it is strongly recommended to thoroughly set this up and conduct tests on development first, and then on testing.

Conduct configuration on staging if applicable and finally move on into a production set up.



Follow these steps:


1. Generating your certificate.

To generate certificates, first make sure you install Oracle's Java JDK 8.

Notice you may install the Java JDK in any machine; given that it is employed to generate the certificate which is portable (to install it later on into the servers).

This means that the tool nor the steps to generate the certificate are strictly needed at the final servers.  


1.1. Download and install Java JDK 8.

The installer is available at http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html and its installation is assisted.





After a successful installation, you should be able to locate the keygen tool inside of the bin folder of the Java JDK 8 installation path (though it meant to be run via a command prompt as instructed below):




1.2. Generate the server certificate.

Open a command prompt and browse into the bin of the Java JDK 8 installation path (by default at C:\Program Files\Java\.. or as a customized path as shown in the image above).

Then run the following command:


keytool -genkey -keyalg RSA -sigalg SHA1withRSA -validity [valid_days] -alias [key_name] -keypass [key_password] 

-keystore [store_name].jks -storepass [store_password] -dname "cn=[projectname]-[company].bizagi.com"





[key_name]: The name of the certificate.

[key_password]: The password for that given the certificate.

[store_name]: The name of the store keeping the certificates that are generated through this tool. Use the .jks file extension for the moment (it will be later on converted to P12 format).

[store_password]: The password for the store keeping the certificates.

[project]: The name of the project, simply for presentation purposes.

[company]: The name of the company representing the customer and its environments, simply for presentation purposes.

[valid_days]: The number of days after which the certificate will expire. For instance setting 365 applies for a year. See the notes below for recommendations on this setting.



The number of valid days as set above ([valid_days]) should be set at least to 365.

What is very important to consider is that:

1.You will need to plan and coordinate accordingly, generating a new certificate so that expiration does not affect your operations (as part of your maintenance tasks).

2.It is your choice if you wish to use a very high [valid_days] setting (such as 3650 representing 10 years), if you wish to avoid at maximum any administrative overhead related to the process of generating new certificates periodically.


For complete information about the command line options, refer to the official documentation of keytool at https://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html.


A successful -genkey command will generate the .jks store file at the current path (alternatively you may define the [store_name] by using a full path):




1.3. Export the certificate.

Run the following command:


keytool -export -rfc -alias [key_name] -keystore [store_name].jks -storepass [store_password]

-file [certificate].cer 





[key_name]: The name of the certificate as set previously (it needs to match the definition of the generated certificate).

[store_name]: The name of the store keeping the certificate as set previously (it needs to match the *.jks file as created before).

[store_password]: The password for the store keeping the certificates as set previously (it needs to use the correct password).

[certificate]: The name of the exported certificate file, using a .cer file extension.


Notice that a successful export procedure will generate the .cer file with the public key at the current path (or in a explicitly different path if otherwise specified):




Alternatively, notice that if you do not specify -file, then a successful procedure will print out the .cer information so that you can just copy and paste it into a file.




1.4. Convert to P12.

Run the following command:


keytool -v -importkeystore -srckeystore [store_name].jks -srcalias [key_name] 

-destkeystore [store_p12].p12 -destkeypass [store_p12_password] -deststoretype PKCS12 





[key_name]: The name of the certificate as set previously (it needs to match the definition of the generated certificate).

[store_name]: The name of the store keeping the certificate as set previously (it needs to match the *.jks file as created before).

[store_p12]: The name of the P12-format store keeping the certificate for this conversion.

[store_p12_password]: The password for the P12-format store.




Upon running the command, you will be prompted to confirm:

Enter destination keystore password: Use the same newly defined password for the P12-format store (the same value as for [store_p12_password]).

Re-enter new password: Use the same as above.

Enter source keystore password: Use the password as defined for the .jks store (the same value as for [store_password] in a previous command).

Enter key password for <[alias_name]>: Use the password as defined for the generated certificate (the same value as for [key_password] in a previous command).


Notice that a successful conversion procedure will generate the .p12 file at the current path (or in a explicitly different path if otherwise specified):




At this point you have your certificate file for the use related to one of your Bizagi environments.

It is ready to import into any number of servers that will be using this same environment.

This means that you need to make sure you copy this .p12 file into a path which is accessible by those servers where you will install the certificate.




2. Installing your certificates.

To install certificates, perform the following steps at the target server.


2.1. Open the Microsoft Management Console.

Locate the MMC.exe file to open up the Microsoft Management Console:




Local certificates should be listed as shown below:




Notice that if local computer certificates are not listed right away, you may need to include this view explicitly.

To do so, click File and then Add/Remove Snap-in...:




To add that view, ensure you click Certificates then Add>:




Click Ok and ensure you select the Local computer certificates.




Click Finish when done.


2.2. Launch the import certificate wizard.

Right click on Personal and select All Tasks to click on Import...




This action launches a certificate import procedure assisted by a wizard.


2.3. Select the P12 file.

Click Browse to locate the .p12 key store and select it:




Click Next.


2.4. Define a password for the private key.

Input a password of your choice. Recall that you should safekeep this password.




You may leave both the Mark this key as exportable, and Include all extended properties checkboxes as marked.

Click Next.


2.5. Define the certificate store.

Mark the Place all certificates in the following store option and ensure that the Personal certificate store is selected.




Click Next and then Finish, when done.

A successful operation should prompt you once finished:




You may double-check that the certificate is now located at the Personal certificate store, while displaying the name/domain as defined when generating such certificate in a previous step.




Recall that these above steps in section #2 (steps 2.1 through 2.5), should be repeated in additional servers where you need to invoke Bizagi SOAP API.


3. Enabling the WS-Security SOAP API and configuring its parameters.

To enable the SOAP API with WS-Security features, use either Bizagi Studio or the Bizagi Management Console according to the environment in question.

Both offer a similar UI to configure this, though recall that Bizagi Studio is employed for the development environment only (while the Bizagi Management Console is used for the other environments).


3.1. Open Bizagi Studio / Bizagi Management Console.

Open you project with the corresponding Bizagi application.

Recall that when working with Bizagi PaaS, the Bizagi Management Console is accessed via RDP.

Similarly Bizagi Studio is accessed via RDP if not set up on your premises.




3.2. Set environment options.

When using either the Bizagi Studio or the Bizagi Management Console, click Environment and browse into the WS-Security section.




In there, fill out:

Enable legacy web services (asmx): Make sure it is left un-checked.

Enable WS-Security: Make sure it is checked.

Username: Define a user name used for signing.

This user is employed for encryption purposes as a username token (as specified by the WS-Security profile spec) to be used later on when invoking the SOAP API.

Password: Define a password for such username token.

X509 Find Value: Input the thumbprint as provided by Bizagi through the support ticket.

X509 Store Location: Choose Local machine.

X509 Store Name: Choose My (for the personal store).

X509 Find Type: Choose FindByThumbprint.

X509 Validation Mode: Choose None.


Click Ok when done.

At this point you the WS-Security Bizagi SOAP API is set, and you may use your own coding to invoke these services (i.e, test them out in the development environment first).

Alternatively, you may rely on the Bizagi WS-Security client tool for testing and verification purposes as well, as instructed at Bizagi WS-Security client tool.