Overview
Bizagi offers this functionality to be beckoned directly from external applications through a service-oriented API, which has a SOAP web service functionality (it is not mandatory to perform any configuration to be used). For more information please relate to this article.
When you (i.e., an application or your system) need to consume a service from the SOA layer of Bizagi, it is necessary to generate a certificate to activate WS-Security. This certificate is generated by Bizagi (self-signed).
Standards and security in WS-*
Bizagi API supports WS-Security configuration, while considering aspects such as:
•Authenticating the caller (authentication and certain authorization aspects implied).
•Including signatures (non-repudiation and data integrity).
•Encrypting the message (message protection for confidentiality).
Through WS-Security, such aspects are managed by the web service itself, in addition to any HTTPS measures you implement for hardened security measures, this means that neither of the web services options are different nor exclusive, only the way in which they are consumed. Furthermore, this ensures that Bizagi web services are invoked strictly by authorized external applications (correct user/password), and make use of certificates to encrypt SOAP messages.
The following standards are supported by Bizagi web services:
•WS-Security
•WS-SecurityPolicy
•WS-Policy
•WS-Addressing
•XML Signature
•XML Encryption
•SOAP 1.2
•WSDL 1.1
|
Legacy web services are disabled. If you want to use the Bizagi SOAP API, You must request a ticket to activate the WS-Security option, and the Bizagi operations team configures this. |
Enable the WS-Security SOAP API and configure its parameters.
1. Submit a support ticket to activate the SOA layer with WS-Security.
When requesting the ticket to enable the security layer with WS-Security you will receive the following information:
•Thumbprint of the certificate used to enable WS-Security
•Username
•Password
2. Configure your environment with the information sent by Bizagi.
To enable SOAP API with WS-Security features for one of your environments, use Bizagi Studio or Bizagi Management Console according to the environment.
They both offer a similar user interface to configure this. Use Bizagi Studio only for the Development environment and the Bizagi Administration Console for the other environments.
Then you have to make the following configuration:
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 user name token.
•X509 Find Value: Input the thumbprint provided by Bizagi through the support ticket (without special hidden characters or blank spaces).
•X509 Store Location: Select CurrentUser.
•X509 Store Name: Select My.
•X509 Validation Mode: Select 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.
Verify secure web services
Make sure your external applications or programs invoke the previously configured services once the username and password is provided by Bizagi.
Similarly, verify that both must be able to use the installed certificates to encrypt and sign.
After configuring these settings, consider that every client connecting to them has to use adequate certifications.
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
https://[project_name]-[company_name].bizagi.com/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);
}
}
Check the following example to see how an encrypted section must be sent to the SOAP header in this sort of invocations:
<s:Header>
<a:Action s:mustUnderstand="1" u:Id="_4">http://tempuri.org/ISecureWorkflowEngineSOA/createCasesAsString</a:Action>
<a:MessageID u:Id="_5">urn:uuid:4155b42d-bbb5-43d5-ab08-235395d80f6f</a:MessageID>
<a:ReplyTo u:Id="_6">
<a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
</a:ReplyTo>
<a:To s:mustUnderstand="1" u:Id="_7">http://dev-raulp/BizagiR1080x/WebServices/WorkflowEngineSOA.svc</a:To>
<o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<u:Timestamp u:Id="uuid-8628c1ed-914e-4d9c-a64e-4a3d44d6d371-2">
<u:Created>2015-10-16T14:54:49.385Z</u:Created>
<u:Expires>2015-10-16T14:59:49.385Z</u:Expires>
</u:Timestamp>
<e:EncryptedKey Id="uuid-8628c1ed-914e-4d9c-a64e-4a3d44d6d371-1" xmlns:e="http://www.w3.org/2001/04/xmlenc#">
<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p">
<DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" xmlns="http://www.w3.org/2000/09/xmldsig#"/>
</e:EncryptionMethod>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<o:SecurityTokenReference>
<o:KeyIdentifier ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">FbBwI2LOkfu9W3O3qMSzAD1j/hk=</o:KeyIdentifier>
</o:SecurityTokenReference>
</KeyInfo>
<e:CipherData>
<e:CipherValue>uf78DpDshQlaJAazQfI4vodv3wtXgzB5JwnrJ6u6tSPc3RMUG5b5S58f0JOlboRxdZkubBBH1aRFGhOp6LJLtoCwAIfzGDF+TAFR4gxCavkGmPtILaJX9xxgrJ48QPZVsbhOeXztDiqsuqJsazlJ2zazIK3fXCtR18Dd9l4i2vBEUaotK77Eadi0VrmunAPRxk3aQMLfYZwSXXe1ehokt1NO6YrISiRbDPnW4/UReUIoYi7zl0bApT4v3AYxLMA14LHA0htysFytXANU+U4oCEm24eYI43KM0G7lte+yhWfCYdK4T9y3fbFXrl7Ft/ZKBWjzxt6tSWu9C9yWbhEaLw==</e:CipherValue>
</e:CipherData>
</e:EncryptedKey>
<c:DerivedKeyToken u:Id="_0" xmlns:c="http://schemas.xmlsoap.org/ws/2005/02/sc">
<o:SecurityTokenReference k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#EncryptedKey" xmlns:k="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
<o:Reference ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#EncryptedKey" URI="#uuid-8628c1ed-914e-4d9c-a64e-4a3d44d6d371-1"/>
</o:SecurityTokenReference>
<c:Offset>0</c:Offset>
<c:Length>24</c:Length>
<c:Nonce>KV4XTx/ZPqCSJaXBhxG9jg==</c:Nonce>
</c:DerivedKeyToken>
<c:DerivedKeyToken u:Id="_1" xmlns:c="http://schemas.xmlsoap.org/ws/2005/02/sc">
<o:SecurityTokenReference k:TokenType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#EncryptedKey" xmlns:k="http://docs.oasis-open.org/wss/oasis-wss-wssecurity-secext-1.1.xsd">
<o:Reference ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#EncryptedKey" URI="#uuid-8628c1ed-914e-4d9c-a64e-4a3d44d6d371-1"/>
</o:SecurityTokenReference>
<c:Nonce>8CnurZZxAn9CMfjsU6lQag==</c:Nonce>
</c:DerivedKeyToken>
<e:ReferenceList xmlns:e="http://www.w3.org/2001/04/xmlenc#">
<e:DataReference URI="#_3"/>
<e:DataReference URI="#_8"/>
<e:DataReference URI="#_9"/>
</e:ReferenceList>
<e:EncryptedData Id="_9" Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:e="http://www.w3.org/2001/04/xmlenc#">
<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<o:SecurityTokenReference>
<o:Reference ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk" URI="#_1"/>
</o:SecurityTokenReference>
</KeyInfo>
<e:CipherData>
<e:CipherValue>K6CZl+UHcWxSRTxDjs/DSfkG4zb+ZofcQKO29S34EUlHXbK4CXan1pjOFIHYTsDc5OX9LuHIWbl+upaCEvvtnu5d7/UARaLiouzLPPzm9UJ6bAy84oThdlkoqZGM5MGlxUH/7u9Vn8LHnUYW0E9hRWPW5WkITnHvg20/pvMCyAwiaJwrE9pp8jkYFA/lkpVTnD+4z9JVI+E+roEheiEQtL63c+UjljyFEqwrxhE8pOf2EfAqyXn8O8QTQeY38+Au0wO3i92M8k8a/ZXFAdbzDxCKeXey1fXuHGfYI5bzfwjEFjVSiTFiEBnBPqxvK7PXmpVnmOxL6rDbAXGA27KAT9a4by3uYG8prgg3AtM4R7e6LnQ555DVzrsgalJB24yj4E7CI2AR2w3+jv22zZHPneRsALwT+2FsqqySS3LqTyiay2jaHXyen/jfvcTdggG5OG+qSRzdsTwJjwCCn2S1MRtxtZVG7eYtfavH3HuJVXAK6um697nWCnASdee3NBwL1X2f5urEROL4uINdvaSxp/ikivGMdZEyXtcTclFM1otE7nitJhRLWbSbks3fuJ9lCS+JEbIwISbSILdpnNXrd4kyZE87Xdrg6+1z1GQFif0=</e:CipherValue>
</e:CipherData>
</e:EncryptedData>
<e:EncryptedData Id="_8" Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:e="http://www.w3.org/2001/04/xmlenc#">
<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<o:SecurityTokenReference>
<o:Reference ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk" URI="#_1"/>
</o:SecurityTokenReference>
</KeyInfo>
<e:CipherData>
<e:CipherValue>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</e:CipherValue>
</e:CipherData>
</e:EncryptedData>
</o:Security>
</s:Header>
<s:Body u:Id="_2">
<e:EncryptedData Id="_3" Type="http://www.w3.org/2001/04/xmlenc#Content" xmlns:e="http://www.w3.org/2001/04/xmlenc#">
<e:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<o:SecurityTokenReference xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<o:Reference ValueType="http://schemas.xmlsoap.org/ws/2005/02/sc/dk" URI="#_1"/>
</o:SecurityTokenReference>
</KeyInfo>
<e:CipherData>
<e:CipherValue>9jwKnLCRSB6APvfUTb5cg3ht7Gbqi985XMwqD7aWIqj43FljgKiUKSR5Fi1sJNIawCNk1AqG3Rosw8amQFC3AvcTJR2v1n+6MxRUodB/2vCNFXMy1ZiMtagPZrjnM6WP9/edoI7vdHkkNbOwPwdImA==</e:CipherValue>
</e:CipherData>
</e:EncryptedData>
</s:Body>
</s:Envelope>
Further information regarding X509 certificates and other testing methods
To learn more about X509 certificates or for an in-depth outline of expected procedures, you may refer to external links such as https://msdn.microsoft.com/en-us/library/ms819944.aspx.
When testing in a development environment you may refer to the official Microsoft .Net Framework in https://msdn.microsoft.com/en-us/library/ff699202.aspx
Additional external links contain tutorials and guides oriented to users certifying for the first time, like http://www.reliablesoftware.com/DasBlog/PermaLink,guid,6507b2c6-473e-4ddc-9e66-8a161e5df6e9.aspx.
Further information of WS-* standards can be found in https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss (published and maintained by OASIS WSS).
Last Updated 2/12/2024 4:05:55 PM