Enabling the WS-Security Bizagi API

Overview

Bizagi features a secure API using the OData-standard compliant. 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, the only way to invoke these methods is using the 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:

•Web applications where Bizagi processes run (applicable to all environments), use a locally-installed certificate.

This means one certificate is needed for each environment.

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.

Before you start

You must request through a support ticket to activate the WS-Security feature.

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.

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.

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

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.

Open Bizagi Management Console.

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

Set environment options.

Go to Environment > Options and browse into the Web Service section.

Fill out the form:

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

•Enable WS-Security: Make sure this is checked.

•User Name: 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 Save all 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 make sure that the SOAP API is working, review that you can retrieve the WSDL.  To do so, use any of the methods' URL using the .SVC extension and the WSDL command. You can use this URL in any browser using this format

http://[Work Portal URL]/WebServices/[internal_component].svc?wsdl

For example:

https://MyProject-MyCompany.bizagi.com/webservices/entitymanagersoa.svc?wsdl

You must be able to see the WSDL:

You can rely on SOAP UI client tool for testing and verification purposes as well.

Using SOAPUI

When invoking the SOAP API using SOAPUI, make sure that you have the following:

1.Use the SVC extension in the URL

2.In the request properties set the username and password defined in Bizagi's Management Console.

3.Set the WSS-Password type to PasswordText.

4.Select the WS-A tab

5.Select the Add default wsa: To checkbox

Using a .NET code

You must use Service References and set the Client Credentials within the code. Here is an example:

static void Main(string[] args)

        {

            ServicePointManager.ServerCertificateValidationCallback += (sender, cert, chain, sslPolicyErrors) => true; // Validate if the certificate is valid

            SecureEntityManagerSOAClient client = new SecureEntityManagerSOAClient(); // Service Reference Instance

            client.ClientCredentials.UserName.UserName = "username";

            client.ClientCredentials.UserName.Password = "password";

            using (new OperationContextScope((System.ServiceModel.IClientChannel)client.InnerChannel))

            {

                var result = client.getEntitiesAsString("");

                Console.WriteLine(result);

            }

        }