Overview
Bizagi offers a security standard that can be applied over the SOAP API. For more information about Bizagi's built-in Web services, refer to Alternative SOAP for external applications. To invoke any of these services you need to configure the security, so they are only invoked using the WS-Security standard.
WS-* standards and security
Bizagi Web services support WS-Security capabilities, and comply to the most widely used WS-* standards.
For production environments, it is recommended and especially useful to make sure that you enable WS-Security for such Bizagi Web services.
This will allow you to enforce that Bizagi Web services are strictly invoked only by an authorized application (providing adequate user name and password), and to be able to rely on the use of certificates (X.509 compliant) for SOAP messages encryption.
Capabilities of the following standards are featured by Bizagi Web services:
•WS-Security
•WS-SecurityPolicy
•WS-Policy
•WS-Addressing
•XML Signature
•XML Encryption
•SOAP 1.2
•WSDL 1.1
Prerequisites
In order for your Bizagi Server to feature Web services which support WS-* standards and security, you need to have official X.509 certificates (as issued by an appropriate CA) for encryption purposes.
Such certificates should be valid and already installed. Note that your platform administrator will require adequate expertise on this subject (certificates, their use and installation).
|
You can use self-signed certificates only in your development environment. |
Enable the Web services security as a feature in your Bizagi project as described below.
Generate a self-signed certificate (for development environment only)
For the development environment you can use self-signed certificates for testing purposes. For the production environment it is mandatory to use a certificate issued by an appropriate CA.
To generate a self-signed certificate you can rely on OpenSSL.Download the appropriate installer of OpenSSL from https://slproweb.com/products/Win32OpenSSL.html,
For Windows OS, a wizard can help you install the SDK. Follow the default steps to copy OpenSSL DLLs to The OpenSSL binaries (bin) directory:
After a successful installation in Windows, you should be able to see the openssl.exe executable file, along with its openssl.cfg configuration file, in the bin folder of the location you selected during installation:
We recommend that you add OpenSSL to your system environment variables so that you can run its executable without needing to worry about paths.
To do this, edit the Path variable:
Add the OpenSSL's bin folder into the registered locations:
Click OK to save your changes before closing any windows (opened command prompts, environment variable windows, etc).
The steps in this article use OpenSSL from a command prompt.
To learning about other options and for complete information about OpenSSL, refer to its official documentation at https://www.openssl.org/docs/man1.0.2/apps/openssl-req.html.
Once installed you can open a CMD (Command Console), change the directory to a folder where you want to generate the certificate, and run the following command:
openssl req -x509 -newkey rsa:4096 -keyout WsCertificatekey.pem -out WSCertificate.cer -days 365 -nodes
Some information related to the certificate is asked like country, state, common name, and others. After registering all the information press Enter and review that both the .cer and .pem files are in the folder.
Install the Certificate in the Bizagi Server
You need to install the certificate in the Bizagi server where the project is running (where the Work Portal is running). This procedure has to be done only once and it is not necessary to replicate in developers' workstations.
Your admins usually do this step through the Microsoft Management Console (directly available in Windows OS).
Open the Microsoft Management Console.
Locate the MMC.exe file to open up the Microsoft Management Console.
Click File and then Add/Remove Snap-in.
To add that view, make sure you click Certificates then Add>:
Click OK and make sure you select the Local computer certificates.
Click Finish when done.
Launch the import certificate wizard for the Personal store.
Right click on Personal, select All Tasks, and click Import...
This launches a certificate import procedure assisted by a wizard.
Select the .cer file.
Click Browse to locate and select the .cer certificate file generated previously:
Click Next.
Define a password for the private key.
Provide a password of your choice. Keep this password in a safe place for later use. You can leave both the Mark this key as exportable, and Include all extended properties check boxes checked.
Click Next.
Define the certificate store.
Check Place all certificates in the following store and select the Personal certificate store. Click Next and then Finish, when done.
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.
Launch the import certificate wizard for the Trusted Root store.
Right-click Trusted Root Certification Authorities, select All Tasks and click Import.
This launches the same certificate import procedure assisted by a wizard, you have already used.
Select the Cer file.
Click Browse to locate and select the same .cer certificate you imported in the previous step:
Click Next.
Define a password for the private key.
provide a password of your choice. Keep the password in a safe place for later use. You can leave both the Mark this key as exportable, and Include all extended properties check boxes checked.
Click Next.
Define the certificate store.
Check Place all certificates in the following store and select the Trusted Root Certification Authorities certificate store. Click Next and then Finish, when done.
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):
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".
Enabling security for Web services
By default, Bizagi legacy web services do not include features complying to WS-* standards and security.
Bizagi projects which are upgraded from versions 10 to 11 will keep using Legacy web services, which are the ones that do not present the security features, but we recommend to activate the WS-Security option.
On the other hand, those Bizagi projects created in version 11.x will start by using the security feature enabled.
|
Legacy web services rely on asmx services, as featured by older versions of the .NET framework (i.e, v2.0), while Web services using WS-Security rely on the Windows communication foundation framework (WCF). |
It is strongly recommended to use Web services with the security feature (WS-Security). When doing so, consider the following:
1. Enable WS-Security and disable Legacy web services.
In case your project was upgraded from a previous release, and you were using the Legacy web services, you will need to first make sure you adequate any external applications to invoke the new Web services.
When enabling WS-Security, make sure you configure all parameters according to your installed X.509 certificates.
2. Configure additional security aspects for such web services at the application server.
Furthermore, this recommendation applies regardless of the Bizagi Web services you employ, and it means configuring IP white lists, additional protection for the resources in your application server, as described at Security setup.
Procedure
Carry out the following steps to rely on WS-Security web services in Bizagi:
1. Open the Environment Options from the main ribbon and select the Popular tab.
Tick the Enable WS-security checkbox (and leave unmarked the Enable legacy web services checkbox).
|
In case you do need backwards compatibility or the use of Legacy web services (not the preferred option), at anytime you may switch back to using those. |
2. Fill out the parameters for the WS-Security feature.
Note that in order to enable encryption and signing capabilities, you will need to specify the usual information regarding installed x509 certificates (such as the store name and location).
Enter configuration details as detailed below (you must necessarily use all of the security aspects of this feature which include authentication, signing and encryption).
PARAMETER |
DESCRIPTION |
|---|---|
User name |
The user name token used for signing. For authentication purposes of the web services, you must define a user name token (as specified by the WS-Security standard). This can be any username you want. |
Password |
Define a password for the above user name token. This can be any password you want. |
X509 Find Value |
Depending on the parameter Find Type, you must use the value. For example, if you use the Thumbprint in the Find Type, you must use the value without spaces (e.g. CCBE812A32201488A0D784EDFFFFA7189232B66D). |
X509 Store Location |
The location of the store where the X.509 certificate is installed. You may use the MMC snap-in to verify such information (https://msdn.microsoft.com/en-us/library/ms788967(v=vs.110).aspx). |
X509 Store Name |
The name of the store where the X.509 certificate is installed. You may use the MMC snap-in to verify such information (https://msdn.microsoft.com/en-us/library/ms788967(v=vs.110).aspx). |
X509 Find Type |
The value which filters how to use the Find Value parameter. For the common name, use FindBySubjectName. |
X509 Validation Mode |
Choose from the valid options: •ChainTrust: This one validates the certificate using the certification authority. In .NET scenarios, it may be more reliable to use this option. •PeerTrust: This one is validated by the server by checking its trusted store (recommended). PeerTrust implies that the incoming certificate has to be in the Trusted People certificate folder. •PeerOrChainTrust: Any of the previous one. •None: Trust any certificate (not recommended). |
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);
}
}