Enabling the WS-Security Bizagi API

<< Click to Display Table of Contents >>

Navigation:  WS-Security >

Enabling the WS-Security Bizagi API

Overview

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 installing the public key of such certificate.

This also means installing one different public key 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 public key 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.

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.

 

note_pin

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

 

Before you start

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 (.cer file) and a thumbprint for further configuration.

When receiving the public key (.cer file), ensure you place this file in a path which is accessible by those servers where you will be invoking the WS-Security SOAP API.

 

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. Installing the certificate (public key).

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

 

note_pin

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.

 

Procedure

Follow these steps:

 

1. Installing the certificate.

To install a certificate's public key, consider:

If you will be using a .NET-based client application to invoke the WS-Security SOAP API, then you will need to install the certificate into the Local machine. This step is usually done for admins through the Microsoft Management Console (directly available in Windows OS).

On the other hand and if you will be using a Java-based client application to invoke the WS-Security SOAP API, then you will need to install the certificate into the keystore file (using a .jks extension) as employed by Java.

 

The following procedure describes how to install a certificate for the first scenario; that is, when working with a .NET-based client application.

In case that you will be using a Java-based client application, such as the Bizagi WS-Security client tool (provided for initial testing and verification purposes), then you may follow the instructions regarding certificates installation as detailed in the Bizagi WS-Security client tool document.

 

1.1. Open the Microsoft Management Console.

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

 

MMC_open

 

Local certificates should be listed as shown below:

 

MMC_certs

 

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...:

 

MMC_snapin1

 

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

 

MMC_addview

 

Click Ok and ensure you select the Local computer certificates.

 

MMC_addlocalpc

 

Click Finish when done.

 

1.2. Launch the import certificate wizard for the Personal store.

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

 

MMC_import

 

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

 

1.3. Select the .cer file.

Click Browse to locate the .cer certificate file provided by Bizagi, and select it:

 

MMC_import1cer

 

Click Next.

 

1.4. Define a password for the private key.

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

 

MMC_import2

 

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

Click Next.

 

1.5. Define the certificate store.

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

 

MMC_import3

 

Click Next and then Finish, when done.

A successful operation should prompt you once finished:

 

MMC_success

 

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

 

MMC_final2

 

1.6. Launch the import certificate wizard for the Trusted Root store.

The following steps repeat the procedure as in steps 1.2. through 1.5, though this time the same certificate is also imported into the Trusted Root CAs.

To do so, right click on Trusted Root Certification Authorities and select All Tasks to click on Import...

 

BICOM_trustedimport

 

This action launches the same certificate import procedure assisted by a wizard, as seen previously.

 

1.7. Select the P12 file.

Click Browse to locate the same .cer certificate imported previously, and select it:

 

MMC_import1cer

 

Click Next.

 

1.8. Define a password for the private key.

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

 

MMC_import2

 

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

Click Next.

 

1.9. Define the certificate store.

Mark the Place all certificates in the following store option and ensure that the Trusted Root Certification Authorities certificate store is selected.

 

BICOM_trustedimport4

 

Click Next and then Finish, when done.

A successful operation should prompt you once finished:

 

MMC_success

 

You may double-check that the certificate is now located at the Trusted Root Certification Authorities certificate store, while displaying the name/issued to as defined when generating such certificate in a previous step.

Also at this point, open that certificate to verify its configuration (you may right-click it and select Open):

 

MMC_trustedreview

 

1.10. Verify adequate certificate validity.

At the General tab when viewing the certificate, ensure that it specifies "This certificate is intended for the following purpose(s): * All issuance policies; * All application policies".

 

MMC_details

 

2. 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).

 

2.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.

 

UsingStudio01

 

2.2. Set environment options.

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

 

Studio_WSSec

 

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 (without special hidden characters or without any blank spaces).

X509 Store Location: Choose Local machine.

X509 Store Name: Choose My (for the personal store located at the Local machine).

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 the Bizagi WS-Security client tool document.

 

You may choose to inform through a Bizagi support ticket that the WS-Security feature has been setup and in case you want to use the Bizagi WS-Security client tool.