Configure security

You can use the API Connection Manager to configure XML and Web Services (WS) security. This allows you to generate different elements to secure your connections.

For instance, you can generate an address element that specifies a particular recipient for your messages and a signature that signs this element.

To do so, follow the steps below:

  1. Open the API Connection Manager and select the connection you want to edit.

  2. Expand the Edit section and go to XML & WS Security.

  3. Select which elements you want to generate. To do so, enable the check box next to one or more elements in the Elements to Generate drop-down menu:

    • All: generate all of the elements described below.

    • Action: generate a Simple Object Access Protocol (SOAP) action element.

    • To: generate an address element.

    • Timestamp: generate a times tamp element.

    • Signature: generate a signature.

    • Username: generate a user name token element.

Configure the action element

You can generate an action element for the SOAPAction header. By default, the system uses the existing SOAPAction header of the message.

You can disable the default setting and specify a different action. If you do so, the API Connection Manager overwrites the default value from the SOAP Action header of the message.

To specify an action element, follow the steps below:

  1. Disable the check box next to Use default value for <Action/>.

  2. Enter a URL in the Action Address field, for example http://CalculatorService/ICalculator/Add.

Configure an action

Configure the address element

The address element allows you to specify a particular recipient for your messages. By default, the system uses the URL specified in the connection and the resource identifier for this URL from the message.

If you want to specify a different address, follow the steps below:

  1. Disable the check box next to Use default value for <To/>.

  2. Enter a URL in the To Address field, for example https://webservice.toscacloud.com/signature.svc.

Configure an address

You can now configure a signature that signs the address element.

Configure the timestamp element

The time stamp element allows you to specify a time period during which the message has to be received. After this time period, security expires and the message is no longer valid.

To do so, specify the Time to live in Seconds, for example 60.

Configure a time stamp

You can now configure a signature that signs the times tamp element.

Configure a signature

To configure a signature, follow the steps below:

  1. Select the required type of signature from the Type of Signature drop-down menu:

    • Signature in Security Header (SOAP Standard): an XML signature that signs a SOAP message.

    • Enveloped Signature: a signature that is part of the message and signs a particular element of the message.

  2. Specify the element of the message that the signature signs. To do so, select any elements from the Element to Sign drop-down menu:

    • Body: the signature signs the message body.

    • Timestamp: the signature signs the message's time stamp.

    • To: the signature signs the recipient’s address.

    • Custom element: the signature signs a message element that you specify. To specify the element, enter the element id in the Custom Element Id field, for example id-123.

    • All: select all options.

  3. Select a Canonicalization Algorithm from the drop-down menu.

    Canonicalization ensures that logically equivalent XML documents provide identical signatures, even if rendered differently.

    For detailed information on the available canonicalization algorithms, see W3C XML Signature Syntax and Processing Version 2.0 - Canonicalization Algorithms.

  4. Select a Digest Algorithm from the drop-down menu.

    The digest algorithm calculates a hash value for the input message. This value is used to create and verify the security signature.

    For detailed information on the available digest algorithms, see W3C XML Signature Syntax and Processing Version 2.0 - Message Digests.

  5. Select a Signature Method from the drop-down menu.

    For detailed information on the available signature algorithms, see W3C XML Signature Syntax and Processing Version 2.0 - Signature Algorithms.

  6. Signature validation requires a public key which allows others to check your signature. To facilitate this, you can include information about the public key.

    To do so, select a type from the Key Identifier Type drop-down menu:

    • Do not Include: exclude information about the public key.

    • RSA or DSA key value: include the Rivest-Shamir-Adleman (RSA) or Digital Signature Algorithm (DSA) key value.

    • Issuer and Serial Number: include issue and serial number of the public key. In this case, the certificate that provides the key data has to be available on the sending and the receiving machine.

    • X509v3 Certificate Data: include the public key certificate data in X509v3 format.

    • Binary Security Token: include the public key encoded in Base64.

  7. A security signature requires a certificate that includes a private key and provides data for the public key. You can use a PFX file or a Java Keystore for your certificate.

    To specify the certificate, select the required type from the Certificate drop-down menu:

    • Select Certificate File if your certificate is in a PFX file.

      Then click on the icon in the Certificate Path field. In the subsequent dialog, select the certificate file and click Open. Enter your Certificate Password, if required.

    • Select Certificate from Java Keystore if your certificate is stored in a Java Keystore.

      Then click on the icon in the Keystore Path field. In the subsequent dialog, select the key store file and click Open. Enter your Keystore Password, if required.

      Select a Certificate Alias from the drop-down menu and enter your Certificate Password, if required.

Configure a signature

Configure the user name token

The API Engine 3.0 can create a user name token in the message's header section. This token contains information for WS Security.

To specify the user name token, follow the steps below:

  1. Enter the user name into the Username field.

  2. Enter the password into the Password field.

  3. Select the Password type:

    • Plain text: the password is sent in plain text format in the XML message's headers section.

    • Digest: the password is sent in digest format in the XML message's headers section.

  4. Optionally, select Add Nonce for adding a Nonce element.

  5. Optionally, select Add Created for adding a Created element.

Configure a user name token element