$(document).ready(function(){highlight();});

Enabling the WS-Security Bizagi API

<< Click to Display Table of Contents >>

Navigation:  Bizagi API > WS-Security >

Enabling the WS-Security Bizagi API

Overview

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

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

For more information about the OData API, refer to Bizagi API.

 

If using the OData API is not possible, consider using use the Bizagi SOAP API.

When setting up the Bizagi SOAP API, we recommend that you enable its WS-Security feature so the SOAP web services encrypt messages based on the use of X.509 certificates (in addition to the channel being already encrypted by TLS/SSL).

 

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

 

Preliminary concepts

Encrypting a message based on the use of certificates requires the following:

Servers where Bizagi processes will be running (applicable to all environments), use a locally-installed certificate.

This means one certificate is needed for each environment.

Servers on your systems which host applications consuming the Bizagi SOAP API need to have the public key of the certificate installed.

This means installing a different public key for each environment.

If more than one server will host the applications invoking the SOAP API for an environment, then you 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 raising any security concerns.

Bizagi already uses certificates issued by a public Certificate Authority for TLS/SSL support, and 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: https://www.oasis-open.org/committees/download.php/13392/wss-v1.1-spec-pr-UsernameTokenProfile-01.htm.

 

note_pin

We recommend using different certificates per environment as a best practice that segregates definitions and access per environments.

 

Before you start

The main prerequisite for using a certificate-based message encryption for Automation Service in its SOAP API is for you, the customer, to submit a support ticket requesting its use.

When the setup is ready you get a notification that the certificates have been installed, and receive the public key (.cer file) and a thumbprint for further configuration.

When you receive the public key, place it in a path which is accessible by the servers from which you invoke the WS-Security SOAP API.

 

What you need to do

Here are the high-level steps needed to configure the Bizagi SOAP API using WS-Security, once you have the public key and thumbprint provided by the Bizagi Support team.

1. Install the certificate (public key).

2. Enable the WS-Security SOAP API and configure its parameters.

 

note_pin

You follow the same procedure for any applicable Bizagi environment in the cloud.

We strongly recommended that you thoroughly set this up and conduct tests in the development first, and then in testing ans staging (if applicable), before deploying it in your Production environment.

 

Procedure

Follow these steps:

 

1. Install the certificate.

To install a certificate's public key, consider:

If you are using a .NET-based client application to invoke the WS-Security SOAP API, you need to install the certificate into the Local machine. Your admins usually do this step through the Microsoft Management Console (directly available in Windows OS).

If you are using a Java-based client application to invoke the WS-Security SOAP API, you need to install the certificate into the keystore file (using a .jks extension) Java uses.

 

The following procedure describes how to install a certificate when working with a .NET-based client application.

If are using a Java-based client application, such as the Bizagi WS-Security client tool (provided for initial testing and verification purposes), follow the instructions for certificates installation 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

 

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, make sure you click Certificates then Add>:

 

MMC_addview

 

Click OK and make sure 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, select All Tasks, and click Import...

 

MMC_import

 

This launches a certificate import procedure assisted by a wizard.

 

1.3. Select the .cer file.

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

 

MMC_import1cer

 

Click Next.

 

1.4. Define a password for the private key.

Provide a password of your choice. Keep this password in a safe place for later use.

 

MMC_import2

 

You can leave both the Mark this key as exportable, and Include all extended properties check boxes checked.

Click Next.

 

1.5. Define the certificate store.

Check Place all certificates in the following store and select the Personal certificate store.

 

MMC_import3

 

Click Next and then Finish, when done.

After a successful import you see a confirmation message:

 

MMC_success

 

You can double-check that the certificate is now located at the Personal certificate store, while displaying the name/issued to that you defined when generating the certificate.

 

MMC_final2

 

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

In this step, repeat the procedure in steps 1.2. through 1.5, but this time import the certificate into the Trusted Root CAs.

Right-click Trusted Root Certification Authorities, select All Tasks and click Import...

 

BICOM_trustedimport

 

This launches the same certificate import procedure assisted by a wizard, you have already used.

 

1.7. Select the P12 file.

Click Browse to locate and select the same .cer certificate you imported:

 

MMC_import1cer

 

Click Next.

 

1.8. Define a password for the private key.

provide a password of your choice. Keep the password in a safe place for later use.

 

MMC_import2

 

You can leave both the Mark this key as exportable, and Include all extended properties check boxes checked.

Click Next.

 

1.9. Define the certificate store.

Check Place all certificates in the following store and select the Trusted Root Certification Authorities certificate store.

 

BICOM_trustedimport4

 

Click Next and then Finish, when done.

After a successful import, you see a confirmation screen:

 

MMC_success

 

You can double-check that the certificate is now located at the Trusted Root Certification Authorities certificate store, displaying the name/issued to you defined when you generate it.

You can open that certificate to verify its configuration (right-click it and select Open):

 

MMC_trustedreview

 

1.10. Verify adequate certificate validity.

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

 

MMC_details

 

2. Enable the WS-Security SOAP API and configure its parameters.

To enable the SOAP API with WS-Security features for one of your environments, use either Bizagi Studio or the Bizagi Management Console according to the environment.

Both offer a similar UI to configure this. Use Bizagi Studio for the Development environment only, and the Bizagi Management Console for the other environments.

 

2.1. Open Bizagi Studio / Bizagi Management Console.

Open your project with the corresponding Bizagi application.

When working with Automation Service, access the Bizagi Management Console via RDP.

Access Bizagi Studio via RDP if it is not set up on your premises.

 

UsingStudio01

 

2.2. Set environment options.

Click Environment and browse into the WS-Security section.

 

Studio_WSSec

 

Fill out the form:

Enable legacy web services (asmx): Leave this un-checked.

Enable WS-Security: Make sure this is checked.

Username: Define a user name to use for signing.

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

Password: Define a password for the username token.

X509 Find Value: Input the thumbprint provided by Bizagi through the support ticket (without special hidden characters or 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, the WS-Security Bizagi SOAP API is set up, and you can use your own coding to invoke its services to test them out in the Development environment first.

You can rely on the Bizagi WS-Security client tool for testing and verification purposes as well, as described in the Bizagi WS-Security client tool document.

 

You can inform us through a Bizagi support ticket that the WS-Security feature has been set up, if you want to use the Bizagi WS-Security client tool.