Web Service Security

There are two layers of security that you can configure for communication between your storefront and an external web service. At the transport layer, you can use certificates to identify both parties of a transaction. At the application layer, you can encrypt or sign content with another certificate (X.509), to ensure that the contents of your messages are not tampered with.

Overview of Web Service Security

The diagram below shows the communication between a Salesforce B2C Commerce pipeline and an external web service. This diagram assumes you have created a custom pipeline and script that invokes the web service, creates SOAP messages, and signs or encrypts messages to the web service.

When the web service is invoked via https, B2C Commerce automatically uses the client private key that you have stored in your instance via Business Manager, using the host name you have provided for that key. You can import SSL certificates used for two-factor authentication into your instance. TLS certificates are used for communication with web services or when using dw.net.HTTPClient. For information on how to import certificates into Business Manager, see Importing Certificates for an Instance.

When the transport layer negotiation and handshake is complete, your B2C Commerce script sends a SOAP message to the web service.

If you use the B2C Commerce implementation of web services in the dw.ws package, then If the web service requires encryption or signing of SOAP messages, B2C Commerce uses the X509 certificate stored in the instance keystore with the WSDL in the webreference2 folder in your cartridge for doc-style services or the webreference2 folder for rpc-style services. In this case, the private key is usually stored in Business Manager in a site preference or custom attribute and referenced in the script, so that the private key doesn't have to be included directly in the script.

You can also choose to use dw.net.httpClient and the crypto package to send and sign a SOAP message if you can't use the B2C Commerce implementation of web services. This isn't recommended and only necessary if you require that the web service X509 certificate be stored in the Business Manager instance.

Storing Certificates

For both transport layer and application layer security, you import private keys with certificates and trusted certificates into the Business Manager instance keystore. However, if you want to use WS-Security to automatically encrypt and decrypt SOAP messages, these certificates must be stored in a cartridge.

When you import certificates into Business Manager, you also configure additional information required when using the keys and certificates, such as an alias or a service provider host name. The alias indicates to B2C Commerce which URL requires the certificate.

Private keys and certificates are stored per instance and can be used across all sites and organizations for that instance. You can store up to 50 entries (keys or certificates) in an instance key store. Each entry in the key store must have an alias. Once given, the alias can't be changed. To change an alias, you must remove the certificate from the keystore and reimport it.

Each private key can be associated with up to five host names. You can import the following private key file types: .pfx or .p12. You can import the following types of trusted certificates: .pem,.cer,.crt,.der. You can also import X509 certificates.

Once imported, the certificates are used whenever communicating with a web service via https.
Note: In releases before B2C Commerce 14.4, X509 certificates were stored with the .wsdl file in a keystore in the webreferences or webreferences2 folder. It's still possible to do this, but it isn't recommended if you are only signing messages and not encrypting them, as storing certificates in the instance keystore is more secure and makes managing certificate expiration easier.

See also Secure Cryptographic Storage Conventions.

Script methods used for X509 certificates stored in the instance Keystore

To perform signing and verification using certificates stored in the instance keystore, you must use methods that include KeyRef parameter in the method signature.

These methods include:
  • dw.crypto.Signature.sign(String message, KeyRef privateKey, String digestAlgorithm)
  • dw.crypto.Signature.signBytes(Bytes contentToSign, KeyRef privateKey, String digestAlgorithm)
  • dw.crypto.Signature.verifySignature(String signature, String contentToVerify, CertificateRef certificate, String digestAlgorithm)
  • dw.crypto.Signature.verifyBytesSignature(Bytes signature, Bytes contentToVerify, CertificateRef certificate, String digestAlgorithm)
  • dw.crypto.KeyRef(String aliasS)
  • dw.crypto.KeyRef(String alias, String password)

You can use the helper classes KeyRef and CertificateRef as references to keys in the keystore. They have a constructor that takes a string that is an alias of a private key KeyRef or a trusted certificate CertificateRef)in the keystore.

Web Service Security FAQ

Q: What features of WS-Security does Commerce Cloud Support?

A: B2C Commerce supports all features of the WS-Security standard except addressing.

Q: What is a key store?

A: A keystore is a storage facility for cryptographic keys and certificates.

Q: What's the difference between a certificate and a trusted certificate?

A: A certificate is private; a trusted certificate is a public certificate issued from a trusted certificate authority.

Q: Why can't I see the Certificates & Private Keys module?

A: You must have the required permissions to see the module. Request permission for the Private Keys and Certificates Business Manager module from your administrator.

Q: How many TLS certificates can be imported per instance?

A: Up to 50 key entries can be stored per B2C Commerce instance and organization. Key entries include both private keys and certificates.

Q: How many host names can a private key be associated with in Business Manager?

A: Each private key can be associated with up to five host names.

Q: If there is an error when using a certificate, where is it logged?

A: See the error log files under Administration > Site Development > Development Setup > Log Files.

Q: How do I scrub logs for sensitive information?

A: When URLs written to the service framework's communication logs need to be scrubbed for sensitive information, use dw.svc.ServiceCallback.filterLogMessage to filter the request URL as well as the request and response bodies.

Q: Can I use the signatureKeyIdentifier and encryptionKeyIdentifier?

A: The WebReferences2 integration with WS-Security enables you to set values for signatureKeyIdentifier and encryptionKeyIdentifier using constants in the WSUtil class. For signatureKeyIdentifier, use the WS_SIG_KEY_ID and for encryptionKeyIdentifer, use WS_ENC_KEY_ID. s
Note: See the B2C Commerce Script API documentation for the default values that WebReferences2 uses and its permissible options.

Q: Is sensitive data included in web service logging?

A: By default, logging data is filtered to prevent logging sensitive data. It's possible to enable logging this information if it's required. For more information, see the description of the comm logging level in Web Service Logging and Troubleshooting.

Related Links

Web Services