Bizagi WS-Security client tool

<< Click to Display Table of Contents >>

Navigation:  » No topics above this level«

Bizagi WS-Security client tool

Overview

Customers using the Bizagi SOAP API with the WS-Security enabled may choose to rely on a web services client provided by Bizagi for initial testing and verification purposes.

This web services client is an executable desktop application (.jar), and it known as the Bizagi WS-Security client tool.

 

Recall that the WS-Security feature of the Bizagi SOAP API enables you to encrypt the message based on the use of X.509 certificates (in addition to the channel being already encrypted by means of TLS/SSL).

Therefore and while having WS-Security feature enabled, you may not simply invoke the SOAP API from a client which doesn't consider certificates for encryption purposes (such as the built-in web client). This means that the advantage provided by the Bizagi WS-Security client tool is that it supports certificates configuration so that it is employed for such encryption purposes.

 

Required profile

In order to use the tool, consider that you should be familiar with the data model and implemented processes with Bizagi.

Furthermore, it is expected that you know of the web services and web methods provided by the Bizagi SOAP API (how to use them, their expected inputs and outputs).

This tool requires that you work with those web methods using strings as inputs (e.g, createCasesAsString, performActivityAsString, saveEntityAsString, etc).

 

To review the basics about the Bizagi SOAP API, regardless of using them on Bizagi PaaS or for an on-premises project, browse the complete chapter starting at: http://help.bizagi.com/bpm-suite/en/index.html?soa_layer.htm.

 

Before you start

Before moving on, ensure that the WS-Security feature has been enabled by following the steps described at the Enabling the WS-Security Bizagi API document (applicable to Bizagi PaaS environments), or by completing the configuration presented at http://help.bizagi.com/bpm-suite/en/index.html?ws_security.htm (for on-premises Bizagi projects).

 

Studio_WSSec

 

This also means that after enabling this feature, you should have at hand the following information:

 

1. The username and password chosen for WS-Security setup.

From the above configuration done in Bizagi (either via Bizagi Studio or the Bizagi Management Console), it is important that you know which username and password combination was setup.

 

2. The thumbprint of the certificate installed in Bizagi servers.

Only whenever your environment belongs to Bizagi PaaS, then this file is provided by Bizagi.

The thumbprint should look somewhat like the below image (a set of 20 paired characters):

 

BICOM_thumbprint_notepad

 

3. The public key (.cer file) of the certificate installed in Bizagi servers.

Only whenever your environment belongs to Bizagi PaaS, then this file is provided by Bizagi.

Upon receiving the .cer file, make sure you place it into a local path.

Such file will be referenced later on as the [cer_file].

 

Tool_inputs

 

note_pin

Note that .cer files are equivalent to .der files.

Furthermore, you may rename a file having one of those extensions so that it uses the other.

 

System requirements

In order to use the Bizagi WS-Security client tool, consider that you will need to have installed:

 

1. Java JDK.

It is recommended to install Java JDK version 8, as available at http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html.

 

JDK8_install

 

After a successful installation, not only you should also have a JRE fully functional, but a JAVA_HOME environment variable should be in place as well.

You should be able to view also the keygen tool installed inside of the bin folder of the Java JDK 8 installation path (though it is meant to be run via a command prompt as instructed below):

 

JDK8_keytool

 

2. OpenSSL.

Download the appropriate installer from https://slproweb.com/products/Win32OpenSSL.html, where you may locate 64-bit or 32-bit installers according to your system architecture.

 

OpenSSL_1

 

For Windows OS, running the installation is assisted, and it is recommended to follow the default steps save the setting indicating to copy OpenSSL DLLs to The OpenSSL binaries (bin) directory:

 

OpenSSL_2

 

After a successful installation, you should be able to see the openssl.exe executable file (i.e, for Windows), along with its openssl.cfg configuration file, at the bin folder of the location as defined during installation:

 

OpenSSL_3

 

Preparing the machine to use the tool (installing certificates)

In order to use the tool, given that it relies on the use of certificates, it is a requisite that you first install the certificates in the local machine, while making sure that you do this procedure considering the keystore file as employed for a Java-based application.

The following illustration represents in a high level, how working with certificates (such as X.509) goes, while considering that in this case, the Certificate Authority is not an external one but it may be setup by reling on the use of a self-signed certificate.

 

x509_overview

 

Notice that such illustration shows more or less the steps to be carried out when preparing the machine; which entail:

Generating a private + public key pair. The private key store provides safekeeping storage for the private key.

Signing a certificate with the root certificate of the Certificate Authority; by providing the public key (through a certificate signing request .csr).

Installing the certificate into the client.

 

For the commands shown below which are lengthy, ensure that you remove any line breaks put simply for presentation purposes in this document.

 

To prepare the machine, carry out the following:

 

1. Generate a signed client certificate and keystore

The following steps are done by relying on OpenSSL.

 

1.1. Open a command prompt and browse into the bin folder of the installation path of the OpenSSL tool.

 

1.2. Ensure you set the OPENSSL_CONF property to target the default properties file.

Do this by running:

set OPENSSL_CONF=openssl.cfg

 

OpenSSL_4

 

1.3. Run the command to generate a certificate:

openssl req -passout pass:[client_password] -new > [csr_name].csr -subj "[details]"

 

OpenSSL_5

 

Consider:

[client_password]: Define the password for the generated certificate.

[csr_name]: Define the name for the certificate signing request file. You may include a full path if you wish to not save it at the current folder.

[details]: Define the details as presented by the generated certificate. The suggested format is:

//C=[country]\ST=[state]\L=[city] DC\O=[organization]\OU=[organization_unit]

\CN=[display_name]\emailAddress=[email] 

Where:

o[country]: Stands for a 2-letter code of the country.

o[state]: Stands for a 2-letter code of the state.

o[city]: Stands for a locality, most often a city's complete name.

o[organization]: Represents the name of the organization.

o[organization_unit]: Represents the appointed unit within the organization.

o[display_name]: Represents the legible name for the certificate.

o[email]: Represents the email for contact purposes.

 

A successful command will create both the .csr file as defined above, but also a privkey.pem private key file:

 

OpenSSL_6

 

For complete information about OpenSSL command options, refer to its official documentation at https://www.openssl.org/docs/man1.0.2/apps/openssl-req.html.

 

1.4. Run the command to generate a key file:

openssl rsa -passin pass:[client_password] -in privkey.pem -out [key_file].key

 

OpenSSL_7

 

Consider:

[client_password]: Use the password as defined previously for the generated certificate.

[key_file]: Define the name for the .key file that will be produced as output. You may include a full path if you wish to not save it at the current folder.

 

A successful command will create the .key file as output:

 

OpenSSL_9

 

 

1.5. Run the command to sign the certificate:

openssl x509 -in [csr_name].csr -out [crt_name].crt -req 

-signkey [key_file].key -CAcreateserial -days [valid_days]

 

OpenSSL_8

 

Consider:

[csr_name]: Use the name for the certificate signing request file as defined/created previously. You may need to include a full path if applicable.

[crt_name]: Define the name for the certificate as an output. You may include a full path if you wish to not save it at the current folder.

[key_file]: Use the name for the .key file as defined/created previously. You may need to include a full path if applicable.

[valid_days]: The number of days after which the certificate will expire. For instance setting 3650 applies for 10 years. Using a high value such as 3650 is best in order to avoid at maximum any administrative overhead related to the process of generating new certificates periodically (which should not be an advantage when running initial tests).

 

A successful command will create the .crt file as output:

 

OpenSSL_11

 

1.6. Run the command to export a .pfx file:

openssl pkcs12 -export -cacerts -in [crt_name].crt -out [pfx_file].pfx 

-inkey [key_file].key 

 

OpenSSL_10

Consider:

[crt_name]: Use the name for the certificate as defined/created previously. You may need to include a full path if applicable.

[pfx_file]: Define the name for the .pfx as an output. You may include a full path if you wish to not save it at the current folder.

[key_file]: Use the name for the .key file as defined/created previously. You may need to include a full path if applicable.

 

Once you run the command, you will need to define (and confirm) a password used for the export.

Such password will be referred to as [export_password]. Make sure you remember or jot down such password and safekeep it.

 

A successful command will create the .pfx file as output:

 

OpenSSL_12

 

2. Import the .cer file into the client certificate

Notice that as an output of the previous step, you should be able to reference a created .pfx file and retain the [export_password] defined previously.

Similarly, for the next step you will need to reference the .cer file (as available in a local path) as used for the public key configuration in Bizagi.

 

2.1. Run the command to import the .cer file:

keytool -import -file [cer_file].cer -keystore [pfx_file].pfx -storetype pkcs12 

 

Keytool_1

 

Consider:

[cer_file]: The name of the certificate file as obtained as a requisite. You may need to include a full path if applicable.

[pfx_file]: Use the name for the .pfx file as defined/created previously. You may need to include a full path if applicable.

 

Once you run the command, you will need to input (and confirm) the password ([export_password]) as defined during the above export procedure.

Then you will need to confirm that you want to add the certificate (into a keystore, according to Java's terminology).

Confirm this by inputting y and hitting Enter.

 

At this step, the configuration is complete. You should be able to see that the existing .pfx file should have a most recent modification date.

The final step is about querying settings and keys of the provided certificate, so that you can configure its use accordingly in the tool.

 

2.2. Run the command to gather settings of the certificate:

keytool -list -v -keystore [pfx_file].pfx -storetype pkcs12

 

Consider:

[pfx_file]: Use the name for the .pfx file as defined/created previously. You may need to include a full path if applicable.

 

Once you run the command, you will need to input (and confirm) the password ([export_password]) as defined during the above export procedure.

 

Keytool_3

 

What is important to gather from the information listed above:

The name for the TrustCertEntity ("mykey" in the image above --Alias name).

The name for the PrivateKeyEntry.

 

Downloading and installing the tool

Downloading the tool is done from this link http://resources.bizagi.com/docs/Bizagi%20WS-Security%20client%20tool.zip.

 

Once downloaded, extract the .zip file into a local path.

It is recommended that you extract the .jar file into the Java JDK bin (otherwise you may get a "java.lang.IllegalStateException: No compiler detected, make sure you are running on top of a JDK instead of a JRE" exception).

 

Tool_Extracted

 

The content consists of:

1.The ws-client-[version].jar executable file (initial [version] being 0.0.3).

2.The run.bat executable file to install the tool in Windows operating system.

3.The run.sh executable file to install the tool in *nix Operating Systems.

 

Execute the run file for your operating system to launch the tool, the file wsbizagi.project will be created, it stores the settings you are currently using (you may disregard this file).

 

Using the tool

Using the tool is simply done by executing the .jar file or the run.bat or run.sh files.

You may run it as is, and configure the settings through the UI, or alternatively filling out the settings by running it via a command prompt.

 

Testing while configuring settings via the UI

Recall that you may run it by double-clicking the ws-client-[version].jar, as long as you have a set Java (i.e, using a JAVA_HOME environment variable) in your machine:

 

Tool_UI

 

If you find a log message prompting about a "Not able to load project file" java.io.FileNotFoundException please close the tool and execute the run file that corresponds to your operating system

 

To use the tool, configure the following:

 

Setting

Description

Example

WSDL

The URL targeting the wsdl of a given WS-Security web service.

Use the following format:

For Bizagi PaaS:

HTTPS://[environment]-[project]-[company].bizagi.com/webservices/[web_service].svc?wsdl.

 

Consider:

o[environment]: The name of the environment (dev, test, stg), or no label at all for a production environment.

o[project]: The name of the Bizagi project.

o[company]: The name of the company representing the customer and its environments.

o[web_service]: Use either WorkflowEngineSOA or EntityManagerSOA.

 

For on-premises projects:

HTTPS://[server]/[project]/webservices/[web_service].svc?wsdl.

 

Consider:

o[server]: The name of the customer's server hosting the Bizagi project.

o[project]: The name of the Bizagi project.

o[web_service]: Use either WorkflowEngineSOA, EntityManagerSOA. or QuerySOA.

An example applicable to Bizagi PaaS is:

HTTPS://test-myapps-agilitycorp.bizagi.com/webservices/WorkflowEngineSOA.svc?wsdl.

Method

The web method's name to use of either the WorkflowEngineSOA, EntityManagerSOA. or QuerySOA web services.

An example when specifically using WorkflowEngineSOA as the web service, is:

createCasesAsString

Username

Type the username as configured in Bizagi when setting up the WS-Security feature.

Not applicable.

Password

Type the password for the above username, as configured in Bizagi when setting up the WS-Security feature.

Not applicable.

Client key

Alias of the certificate as created when "Preparing the machine to use the tool" (the [key_name] parameter).

Not applicable.

Key password

Password for the certificate above, as created when "Preparing the machine to use the tool" (the [key_password] parameter).

Not applicable.

Server key

Password for the certificate above, as created when "Preparing the machine to use the tool" (the [key_password] parameter).

Not applicable.

Properties file

The local path pointing to the client.properties file.

An example when using the tool in a Windows-OS, is:

E:\Shared\cert\client.properties

XML

A string holding information in an XML format, compliant to what expected by the specific web method as defined above (according to the Method property).

An example when specifically working with createCasesAsString, is:

<BizAgiWSParam><domain>domain</domain><userName>admon</userName><Cases><Case><Process>VacationRequest</Process><Entities><VacationRequest><VacationStartingDate>2012-03-18T12:00:00-05:00</VacationStartingDate><VacationEndingDate>2012-03-26T12:00:00-05:00</VacationEndingDate></VacationRequest></Entities></Case></Cases></BizAgiWSParam>

Ignore self-signed certificate exception

A checkbox allowing you to tick it to ignore any issues arising from the use of self-signed certificates.

It is recommended to tick this checkbox.

Not applicable.

 

Once that properties are set, simply click the Execute button to send the XML as request and obtain a response which will be displayed in the Result textbox.

Further log detail is provided at the Log textbox:

 

Tool_run

 

You may use the Clear button so that you can Execute a new test again without previous verbose or information.

 

Testing while configuring settings via the command prompt

Before you start, the wsbizagi.project file must exist. Then run the ws-client.jar, by opening a command prompt.

 

Use the following command to launch the tool:

java -jar wsclient-[version].jar -i -w "[WSDL]" -m [method] -u [username] 

-p [password] -skey [service_key] -ckey [client_key] -ckp [key_password] 

-f [properties_file] -x [XML] 

 

Consider the same definitions for variables as detailed for settings in the UI, as detailed below:

 

Variable

Description

Example

[WSDL]

The URL targeting the wsdl of a given WS-Security web service.

Use the following format:

For Bizagi PaaS:

HTTPS://[environment]-[project]-[company].bizagi.com/webservices/[web_service].svc?wsdl.

 

Consider:

o[environment]: The name of the environment (dev, test, stg), or no label at all for a production environment.

o[project]: The name of the Bizagi project.

o[company]: The name of the company representing the customer and its environments.

o[web_service]: Use either WorkflowEngineSOA or EntityManagerSOA.

 

For on-premises projects:

HTTPS://[server]/[project]/webservices/[web_service].svc?wsdl.

 

Consider:

o[server]: The name of the customer's server hosting the Bizagi project.

o[project]: The name of the Bizagi project.

o[web_service]: Use either WorkflowEngineSOA, EntityManagerSOA. or QuerySOA.

An example applicable to Bizagi PaaS is:

HTTPS://test-myapps-agilitycorp.bizagi.com/webservices/WorkflowEngineSOA.svc?wsdl.

[method]

The web method's name to use of either the WorkflowEngineSOA, EntityManagerSOA. or QuerySOA web services.

An example when specifically using WorkflowEngineSOA as the web service, is:

createCasesAsString

[username]

Type the username as configured in Bizagi when setting up the WS-Security feature.

Not applicable.

[password]

Type the password for the above username, as configured in Bizagi when setting up the WS-Security feature.

Not applicable.

[client_key]

Alias of the certificate as created when "Preparing the machine to use the tool" (the [key_name] parameter).

Not applicable.

[key_password]

Password for the certificate above, as created when "Preparing the machine to use the tool" (the [key_password] parameter).

Not applicable.

[server_key]

Password for the certificate above, as created when "Preparing the machine to use the tool" (the [key_password] parameter).

Not applicable.

[properties_file]

The local path pointing to the client.properties file.

An example when using the tool in a Windows-OS, is:

E:\Shared\cert\client.properties

[XML]

A string holding information in an XML format, compliant to what expected by the specific web method as defined above (according to the Method property).

An example when specifically working with createCasesAsString, is:

<BizAgiWSParam><domain>domain</domain><userName>admon</userName><Cases><Case><Process>VacationRequest</Process><Entities><VacationRequest><VacationStartingDate>2012-03-18T12:00:00-05:00</VacationStartingDate><VacationEndingDate>2012-03-26T12:00:00-05:00</VacationEndingDate></VacationRequest></Entities></Case></Cases></BizAgiWSParam>

[version]

The specific version number as seen next to the .jar's file name (following the dash, represented by 3 numbers in a #.#.# format).

0.0.3 (the tool's initial version).

 

When launched, the tool will automatically run the test and display a log with the result:

 

Tool_command