Bizagi WS-Security client tool (jdk)

<< Click to Display Table of Contents >>

Navigation:  » No topics above this level«

Bizagi WS-Security client tool (jdk)

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.

 

Tool_inputs

 

System requirements

In order to use the Bizagi WS-Security client tool, consider that you will need to have installed 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

 

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 (.jks), given that the tool (.jar) is a Java-based application.

 

To prepare the machine, carry out the following:

 

1. Generate a client certificate and keystore

To generate a client certificate, first open a command prompt and browse into the bin folder of the installation path of the JDK.

 

Once there, run the following command:

keytool -genkey -keyalg RSA -sigalg SHA1withRSA -validity [validity] 

-alias [key_name] -keypass [key_password] -keystore [store_name].jks 

-storepass [store_password] -dname "cn=[display_name]" 

 

Tool_Generate

 

Consider:

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

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

[valid_days]: The number of days after which the certificate will expire. For instance you may choose to set expiration to 3650 (applies for a 10 years, so that you do not incur in administration overhead of such certificates).

 

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

 

Tool_JKS

 

2. Import the .cer file into the created keystore

Notice that as an output of the previous step, you should be able to reference the created keystore.

In addition to this, at this point you will also reference the public key (.cer file) as available in a local path.

 

While in the same command prompt, run the following command:

keytool -import -trustcacerts -keystore [store_name].jks -storepass 

[store_password] -alias [key_name] -file [certificate].cer -noprompt

 

[IMG]

 

Consider:

[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 certificate file (public key), using a .cer file extension.

You will need to specify the full path to that .cer file in case that it is not located at the bin folder.

 

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 path of your choice.

 

Tool_Extracted

 

The content consists of:

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

2.A sample client.properties file to enable you to load parameters and run the executable via the command prompt.

 

In there, edit the client.properties file so that it references adequate values as set in the previous section about "Preparing the machine to use the tool".

 

Tool_Propertiesgen

 

Consider:

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

 

Save the changes when done and close the file.

At this point, the tool is installed and set up.

 

Using the tool

Using the tool is simply done by executing the .jar file.

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 - Copy

 

You may ignore the default log message prompting about a "Not able to load project file" java.io.FileNotFoundException.

This is so because by default, the tool will attempt to locate existing settings, though you may always configure properties from scratch, as described next.

 

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

Run the ws-client.jar, by opening a command prompt.

To do so, first prepare the following information:

 

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