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.
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. 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.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. 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.
-
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?
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. sWebReferences2
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 .