Enabling Bizagi API

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > SOAP web services > Requisites and concepts for SOAP web services >

Enabling Bizagi API

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.

 

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

 

note_pin

It is highly advisable to enable secure web services and disable legacy web services for production environments when possible.

 

Prerequisites

To use Bizagi web services in your server, you will need to:

 

1. Install Microsoft .NET Framework version 4.5.

 

2. Have an official X.509 certificate, issued by a proper Certifying Entity in order to encrypt.

These certificates must be valid and installed. The administrator of your platform should have expertise in certificates and their installation.

 

Once you have installed the correct framework installation, you will need to activate the web service security in your Bizagi project following the next instructions.

 

Procedure overview

Make sure your project has the WS-Security enabled and Bizagi legacy web services disabled. By default all projects are created with WS-Security features enabled and Bizagi legacy web services disabled. This is because these does not include features related to WS-* standards nor security.

 

note_pin

Legacy web services are supported through asmx services, likewise previous .NET framework versions (e.g. .NET Framework 2.0). Nevertheless, web services using WS-Security are supported through Windows communication foundation framework (WCF).

 

It is highly advised to use web services with security, and when doing so consider the following:

1.Enable WS-Security and disable Legacy web services.
Updated projects previously built using older versions of Bizagi Studio might have enabled WS-Security and Legacy web services disabled. Please bear in mind that the configuration will prompt for a valid X.509 certificate installed.

 

2.Configure additional security aspects for the web services in your application server.
Additional security measures are encouraged regardless what web services are used, such as white IP lists, enhancing the security of the application server resources as described in Application security recommendations.

 

Enabling secure web services

In order to enable web services, follow these steps.

Note that the steps will guide you to choosing the WS-Security alternative.

 

1. Open the Environment Options from the Ribbon and select the Popular tab.
Tick the Enable WS-security checkbox (alternative tick the Enable legacy web services when not opting for secure web services).

 

1

 

note_pin

Whenever you want to activate and deactivate whether WS-Services or Legacy web services, go back to the environment configuration and check/uncheck the corresponding option.

 

2. Provide WS-Security configuration details for each parameter:

 

2

Bear in mind that you must use all of the X.509 certificate security properties contained in the feature (Authentication, sign in and encryption). You can not pick some of them.

Furthermore, in case you need to specify another certificate, this configuration can be modified at any point.

 

PARAMETER

DESCRIPTION

Username

Username

User name token used for signing in. To enable authentication you must specify the user name token defined in the WS-protocol.

Password

Password

Password used for signing in with the previously specified user.

X509 Find Value

The Common name of the X.509 installed certificate.

X509 Store Location

Repository location where the X.509 certificate is currently installed.

You can use the MMC snap-in to verify the information (https://msdn.microsoft.com/en-us/library/ms788967(v=vs.110).aspx).

X509 Store Name

Repository name where the X.509 certificate is currently installed.

You can use the MMC snap-in to verify the information (https://msdn.microsoft.com/en-us/library/ms788967(v=vs.110).aspx).

X509 Find Type

Type of search using the Find Value field of the x509 certificate.

To look for the certificate common name use FindBySubjectName.

X509 Validation Mode

X509 Validation Mode

Validation Mode for the x509 certificate. You can specify the certificate validation mode:

ChainTrust: This one validates the certificate using the certification authority. In .NET scenarios is more reliable to use this option.

PeerTrust: This one is validated by the server by checking its trusted store.

PeerOrChainTrust: Any of the previous one.

None: Trust any certificate (Not advised).

 

An example of how the filter would be used is displayed below:

 

4_1

 

3. Make sure your external applications or programs invoke the previously configured services once the username and password is provided.

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.

 

The web service URL when using WS-Security will haven a .svc extension.

E.g. instead of the legacy web service http://.../WebServices/EntityManagerSOA.asmx?wsdl

you will use http://.../WebServices/EntityManagerSOA.svc?wsdl

 

WS_SVC_wsdl

 

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