Creating a WS-Security Profile

Create a WS Security Profile to securely exchange messages between your application and a web service. By configuring a SOAP message in your WS-Security Profile, you can authenticate a web server by validating message senders and the integrity of messages in your application.

  1. Create the rule that stores the WS-Security Profile.

    1. In the Designer Studio header, click Create > Security > WS-Security Profile.
    2. In the Short description field, enter text that describes the data instance.
    3. In the Web Service security profile name field, enter a name for the data instance.
    4. Click Create and open.

  2. Define the outbound SOAP message that is sent to the service.

    Note: You can add as many configuration types for the outbound SOAP message as you need.

    1. On the Out Flow tab, click the Add new configuration icon.

    2. In the Configuration type list, select one of the following outbound SOAP message types:

      • Encryption - Enables the encryption configuration on the outbound SOAP message.

        1. In the Encryption parts field, enter a semicolon separated list of element names to encrypt. For example, to encrypt and/or digitally sign the WS-Security UsernameToken element, the value would look like this: {Element}{http://schemas.xmlsoap.org/ws/2002/07/secext}UsernameToken

        2. In the Encryption key identifier list, select the encryption key to use in the SOAP message.

        3. In the Encryption user field, enter a certificate alias that is specified in the Keystore field on the Keystore tab in this rule form.

        4. To use symmetric key encryption, where the user and the service have a shared binary key, in the Embedded key field, enter the Base64 value of a binary shared key.
        5. In the Embedded key name field, enter the name of the shared embedded key.

        6. In the Encryption sym algorithm list, select an algorithm to encrypt the symmetric key.

        7. In the Key transport algorithm list, select an algorithm to encrypt and decrypt the encryption key.

      • Signature - Enables the signature configuration type on an outbound SOAP message.

        1. In the Signature algorithm list, select the digital signature algorithm to use for encryption.

        2. In the Signature key identifier list, select the key identifier type to use to identify the signature token. As a best practice, select Issuer Name and Serial. When you select this option, only the user name and serial number of the certificate are sent in the message; the certificate is not sent in the security header.

        3. Click Change signature password to change or add a password that is associated with the signature.

        4. In the Signature user field, enter the name of the alias listed in the Keystore field on the Keystore tab in this rule form.

        5. In the Signature parts field, enter a semicolon-separated list of element names to sign. For example, to encrypt and/or digitally sign the WS-Security UsernameToken element, the value would look like this: {Element}{http://schemas.xmlsoap.org/ws/2002/07/secext}UsernameToken

      • Timestamp - Enables the time stamp configuration type on an outbound SOAP message.

        • In the Time to live field, enter the amount of time in seconds, for which the SOAP message is valid.

      • Username - Enables the user name configuration type on an outbound SOAP message.

        1. In the User name field, enter a user name for authentication.

        2. Click Change password to change or add a password that is associated with the specified user name.

        3. In the Password type list, select the type of password to use for the SOAP message.

          • Text - Sends the password as a plain text in the SOAP message.

          • Digest - Sends the password as a Base64-encoded SHA1 has of value of the original value.

        4. To change the SOAP message to a randomly generated Based64 string, select the Add nonce value check box.
        5. To indicate the creation time of the message by including a timestamp in the SOAP message, select the Add created timestamp check box.

  3. Define the inbound SOAP messages.

    Note: The order of the configuration type is important. For example, if your outbound message is first signed and then encrypted, the inbound message must first decrypt the message and then check the signature.

    1. On the In Flow tab, click the Add new configuration icon.

    2. In the Configuration type list, select one of the following inbound SOAP message type:

      • Decryption - Enables the decryption configuration on the inbound SOAP message.

        1. In the Encryption key identifier list, select the encryption key to use in the SOAP message.

        2. Click Change decryption password and then enter the new password to change the private key password.

        3. To use symmetric key encryption, where the user and the service have a shared binary key, in the Embedded key field, enter the Base64 value of a binary shared key.
        4. In the Embedded key name field, enter the name of the shared embedded key.

        5. In the Encryption sym algorithm list, select the algorithm to encrypt the symmetric key.

        6. In the Key transport algorithm list, select the algorithm used for encrypting and decrypting the encryption key.

      • Signature - Enables the signature configuration type on an inbound SOAP message.

        1. In the Signature algorithm list, select the digital signature algorithm to use for encryption.

        2. In the Digest algorithm list, select a hash code that verifies that the signature came from the claimed source.

        3. In the Signature key identifier list, select the key identifier type to use to identify the signature token.

      • Timestamp - Enables the time stamp configuration type on an inbound SOAP message.

      • Username - Enables the user name configuration type on an inbound SOAP message.

        1. In the User name field, enter a user name for authentication.

        2. Click Change password to change or add a password associated with the specified user name.

        3. In the Password type list, select the type of the password to use with the connection.

          • Text - The password is sent as plain text in the SOAP message.

          • Digest - The password is sent as a Base64-encoded SHA1 has of value of the original value.

        4. To change the SOAP message to a randomly generated Based64 string, select the Add nonce value check box.
        5. To indicate the creation time of the message by including a time stamp in the SOAP message, select the Add created timestamp check box.

      • SAML - Enables the SAML configuration type on an inbound SOAP message.

        1. In the Saml version list, select the SAML version to use in the SOAP message.

        2. In the Clock skew field, enter the time difference (in seconds) between two different servers that are out of sync.

  4. Identify the keystore that stores the cryptographic keys and certificates for your WS Security Profile.

    1. Click the Keystore tab.
    2. In the Keystore field, enter the keystore record that contains the Pega Platform private/public key pair for SSL security.
    3. In the Truststore field, enter the keystore record that contains the SSL certificates that are trusted by the Pega Platform.

  5. Click Save.