Secure Web Service Integrations in B2C Commerce

Learning Objectives

After completing this unit, you'll be able to:

• Explain how the OSI seven-layer architecture relates to a secure B2C Commerce integration.
  
• List the secure protocols for accessing third-party apps with a B2C Commerce storefront application.
  
• Explain how to configure the two communication layers between a storefront and an external web service.
  
• List the steps a controller takes to connect a third-party app to B2C Commerce.
  
• Explain how to import and store certificates.
  

Connecting a B2C Commerce storefront to third-party systems requires both well-structured code and layered security. This unit covers the Open Systems Interconnection (OSI) model, secure protocols, transport and application layer configuration, controller wiring, and certificate management.

How the OSI Model Relates to B2C Commerce Integrations

Connecting a B2C Commerce storefront to third-party systems requires both well-structured code and layered security. This unit covers the Open Systems Interconnection (OSI) model, secure protocols, transport and application layer configuration, controller wiring, and certificate management.

The OSI model divides network communication into seven layers. Developed by the International Organization for Standardization (ISO), this conceptual framework categorizes telecommunication and computing functions into distinct levels. This shared terminology enables network experts to design compatible systems and resolve connectivity problems more effectively. Three are relevant for B2C Commerce web service integrations.

Understanding these layers helps you diagnose failures:

• A refused connection is a transport-layer problem.
  
• A malformed payload is a presentation-layer problem
  
• A 404 or SOAP fault is an application-layer problem.
  

Secure Protocols for Third-Party Access

The service type in Business Manager determines the protocol and underlying client class. For any integration that transmits credentials, customer data, or order information, use an encrypted protocol.

For SOAP integrations that require message-level protection beyond channel encryption, B2C Commerce supports WS-Security for signing and encrypting individual SOAP message bodies.

Avoid plain HTTP or unencrypted FTP for any integration that transmits sensitive data.

Configuring the Two Communication Layers

B2C Commerce web service security operates at two distinct layers. You configure both in Business Manager and in your cartridge code.

Transport Layer Security

The transport layer establishes an encrypted channel. When the storefront calls an external HTTPS endpoint, B2C Commerce presents the client certificate stored in the instance keystore. Configure it in three steps.

1. Import your TLS certificate into Business Manager under Administration | Operations | Private Keys and Certificates.
   
2. Assign the target host name (for example, api.paymentprovider.com) to the private key. B2C Commerce uses the host name to select the correct certificate for each outbound connection.
   
3. In the service credential, enter the full HTTPS URL of the endpoint.
   

After it’s configured, B2C Commerce handles the TLS handshake automatically for all calls to that host.

Application Layer Security

Application layer security protects message content, not just the channel. For SOAP integrations, WS-Security signs or encrypts individual SOAP message bodies, protecting content from interception and tampering even if the transport channel is compromised.

1. Place the keystore file (.jks or .pkcs12) in the webreferences2 folder of your cartridge, with the same base name as the WSDL file.
   
2. In the createRequest callback, build a requestCfg HashMap. Set WSUtil.WS_ACTION the interceptor actions—WS_SIGNATURE, WS_ENCRYPT, WS_USERNAME_TOKEN, WS_TIMESTAMP—and include the keystore type, password, and alias.
   
3. Build a matching responseCfg HashMap for the response.
   
4. Apply both with WSUtil.setWSSecurityConfig(port, requestCfg, responseCfg).
   

To sign or verify using certificates stored in the instance keystore rather than the cartridge, use dw.crypto.Signature methods that accept a KeyRef parameter.

Steps a Controller Takes to Connect a Third-Party App

An SFRA controller that calls a third-party service follows these steps.

1. Register the service. Call LocalServiceRegistry.createService() with the service configuration name from Business Manager and a callback object containing createRequest, parseResponse, and mockCall handlers.
   
2. Build the request. The createRequest callback sets the HTTP method, request headers, and body — or, for SOAP, constructs the typed request object and any WS-Security HashMaps.
   
3. Invoke the service. Call Service.call(). The framework checks the circuit breaker and rate limiter before calling the services. If either trips, the framework skips the call and the Result reflects the failure.
   
4. Inspect the result. Check result.ok. On failure, read result.error for service-specific codes (such as HTTP 404), result.errorMessage for exception details, and result.status to distinguish a circuit breaker trip (Failure Count Exceeded) from a timeout (SocketTimeoutException: Read timed out).
   
5. Return output or handle the error. On success, pass result.object to an ISML template or JSON response. On failure, return a meaningful error—not a raw exception—to the shopper.
   

Example: Controller Connecting to a Payment Provider

This SFRA controller applies the five steps to an HTTPS payment authorization. It registers mycartridge.https.payment.authorize (that name must match a service configuration in Business Manager) and implements createRequest, parseResponse, and mockCall.

• createRequest sets the method to POST, adds JSON and Authorization headers, and returns the request body. The password comes from the service credential in Business Manager (svc.configuration.credential.password), not from cartridge code.
  
• parseResponse converts client.text into the object that Service.call() returns.
  
• mockCall returns a simulated authorization when the service mode is Mocked, so you can test without calling the live payment endpoint.
  
• The Authorize route calls Service.call() with the order ID and amount.
  
• On success, it returns result.object.transactionId as JSON. On failure, it returns HTTP 500 and result.errorMessage, not a raw exception to the shopper.
  

var LocalServiceRegistry = require('dw/svc/LocalServiceRegistry');
var paymentService = LocalServiceRegistry.createService('mycartridge.https.payment.authorize', {
    createRequest: function (svc, args) {
        svc.setRequestMethod('POST');
        svc.addHeader('Content-Type', 'application/json');
        svc.addHeader('Authorization', 'Bearer ' + svc.configuration.credential.password);
        return JSON.stringify(args);
    },
    parseResponse: function (svc, client) {
        return JSON.parse(client.text);
    },
    mockCall: function (svc, client) {
        return { statusCode: 200, statusMessage: 'Success', text: '{"transactionId":"mock-001","approved":true}' };
    }
});
server.post('Authorize', function (req, res, next) {
    var result = paymentService.call({ orderId: req.form.orderId, amount: req.form.amount });
    if (result.ok) {
        res.json({ success: true, transactionId: result.object.transactionId });
    } else {
        res.setStatusCode(500);
        res.json({ success: false, error: result.errorMessage });
    }
    next();
});

Importing and Storing Certificates

Business Manager stores certificates in the instance keystore. You’ll want to configure them manually on each instance since they don’t replicate between instances.

Import a Certificate

1. Go to Administration | Operations | Private Keys and Certificates.
   
2. Select Import and select the certificate or key file. Accepted formats:
   
   • Trusted certificates: .crt, .pem, .cer, .der
     
   • Private keys: .p12, .pfx
     
3. Enter an alias. The alias is permanent. To change it, delete the entry and reimport. Aliases can't contain spaces or special characters.
   
4. For private keys, enter a source password and assign one or more host names (for example, api.paymentprovider.com). B2C Commerce uses the host name to select the correct certificate for each outbound HTTPS call.
   
5. Save your work.
   

Storage Rules

The instance keystore holds private keys and trusted certificates for that instance only. Entries don't replicate, so you import them on each instance. After import, every site and organization on the instance can use them.

These limits and placement rules apply.

• Each instance holds up to 50 keystore entries (private keys and trusted certificates combined).
  
• Each private key can be associated with up to five host names.
  
• The instance shares certificates across all sites and organizations.
  
• Store WS-Security keystores for signing and encrypting SOAP messages in the cartridge webreferences2 folder, not in the instance keystore.
  

Using Certificates in Script

After it is imported, B2C Commerce applies TLS certificates automatically for HTTPS calls to the associated host via dw.net.HTTPClient or the service framework. For signing and verification using X.509 certificates stored in the instance keystore, reference them in a script with dw.crypto.KeyRef(alias) for private keys and dw.crypto.CertificateRef(alias) for trusted certificates.

Wrap It Up

In this unit, you explored how to secure B2C Commerce integrations by applying TLS at the transport layer and WS-Security for SOAP messages. You learned how to configure certificates in Business Manager and implement the controller logic necessary to register, invoke, and monitor third-party service connections. By following these steps, you can ensure that external data transfers remain protected and that your storefront handles service results effectively.

In this badge you learned how to plan, implement, manage, and secure third-party web service integrations for B2C Commerce. With these strategies and best practices, you can now build robust, fault-tolerant integrations that protect storefront performance and maintain continuous uptime.

Resources

• Salesforce Help: Web Service Security