Web services security (WS-Security)

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > SOAP web services > URL and important notes >

Web services security (WS-Security)

Overview

Bizagi offers its functionality so that it can be invoked directly from external applications through a service-oriented API.

The service-oriented API features SOAP-compliant Web services, which do not require starting configuration for their use.

For more information about Bizagi's built-in Web services, refer to Bizagi API for external applications.

 

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 ensure 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 will need:

 

1. To install Microsoft .NET Framework in its 4.5 version.

 

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

 

Once you have this framework's version installed, you will need to enable the Web services security as a feature in your Bizagi project as described below.

 

 

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.

 

On the other hand, those Bizagi projects created in version 11 will start by using the security feature enabled.

 

note_pin

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

 

1

 

 

note_pin

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

 

2

 

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

Password

Define a password for the above user name token.

X509 Find Value

The common name of the installed X.509 certificate.

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

 

 

3. Ensure your external applications or programs invoke such services by providing user name and password.

Similarly, recall that these should be able to rely on the installed certificates for encryption and signing capabilities.

 

The URL of Web services using the security feature (WS-Security) will use an .svc termination instead.

For example, instead of Legacy web service http://.../WebServices/EntityManagerSOA.asmx?wsdl, you would use:

http://.../WebServices/EntityManagerSOA.svc?wsdl

 

WS_SVC_wsdl

 

Refer to the following example to view how an encrypted <Security> section should be sent inside of the SOAP Header in such type of invocations:

<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">[encrypted value]</o:KeyIdentifier>

                 </o:SecurityTokenReference>

       </KeyInfo>

       <e:CipherData>

                 <e:CipherValue>[encrypted value]</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>[encrypted value]</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>[encrypted value]</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>[encrypted value]</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>[encrypted value]</e:CipherValue>

       </e:CipherData>

   </e:EncryptedData>

</o:Security>

 

 

Learning about X.509 certificates and testing options

In case you are not familiar with use of X.509 certificates and when testing this feature in a development environment, you may refer to official documentation of Microsoft's .NET framework at

https://msdn.microsoft.com/en-us/library/ff699202.aspx.

Additional external links may present tutorials and guides oriented for first-time certificate users, such as http://www.reliablesoftware.com/DasBlog/PermaLink,guid,6507b2c6-473e-4ddc-9e66-8a161e5df6e9.aspx.

 

Further information on WS-* standards can be found at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss (as published and maintained by OASIS WSS.