B2C Commerce Hyperforce Code Upload Instructions for Staging

Changes to 2FA for Secure Code Upload on Hyperforce

The system for two-factor authentication (2FA) for secure code uploads to Staging instances has changed for Hyperforce. The main changes are as follows:

1. Code uploads will use the standard Business Manager hostname (e.g., staging-realm-customer.demandware.net).
   1. There will no longer be a separate hostname for code uploads. The cert.staging.realm.customer.demandware.net hostname will be deactivated.
   2. Regular Business Manager operations will not need a client certificate. The 2FA client certificate will only be necessary for code uploads.
2. A CA certificate bundle will no longer be provided by B2C Commerce. Instead, the customer will generate their own CA certificate bundle which will be registered with the eCDN. Both initial upload and rotation of this CA certificate bundle is completed as self-service.
   1. B2C Commerce will no longer have access to the CA certificate bundle itself, increasing customer security.
   2. Client certificates signed by the customer generated CA certificate bundle will be checked and validated at the eCDN layer.
   3. This CA certificate bundle will have a maximum expiry of 365 days.

The following instructions outline how to generate a self-signed CA certificate bundle and upload/register it with the eCDN. It is recommended to follow the steps as preparation for the migration to Hyperforce. Up until the migration, continue to use any existing client certificates with the old cert.staging hostname. After the migration, use new client certificates with the standard Business Manager hostname.

Generate Self-Signed CA Certificate and Private Key

Run the following openssl command, replacing <realm> and <customer>:

CERT_HOST=staging-<realm>-<customer>.demandware.net
$ openssl req -new -newkey rsa:2048 -sha256 -days 365 -x509 -nodes -addext "basicConstraints=critical,CA:TRUE" -addext "keyUsage=critical,keyCertSign,cRLSign" -keyout ${CERT_HOST}.key -out ${CERT_HOST}.crt

Fill out the prompts as appropriate. For Common Name, use the same value used for CERT_HOST. See example below:

$ openssl req -new -newkey rsa:2048 -sha256 -days 365 -x509 -nodes -keyout ${CERT_HOST}.key -out ${CERT_HOST}.crt
...
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MA
Locality Name (eg, city) []:Burlington
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Salesforce
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:staging-<realm>-<customer>.demandware.net
Email Address []:

The CA certificate and private key will next need to be uploaded to eCDN. This can be done via the Business Manager UI, or using the CDN-API. Once this is complete, eCDN will be configured to accept client certificates signed by this CA certificate.

Upload Certificate and Private Key (Business Manager)

In Business Manager for the Staging instance, navigate to Administration → Site Development → Development Setup → Code Upload Certificate. On this page, select Add Certificate, enter a Certificate Name (for ease of organization), and copy/paste the Certificate and Private Key data generated above, then Save.

Note: Please ensure you are uploading the CA certificate generated from the first section commands. In the event you attempt to upload the client (leaf) certificate, you will encounter the following error message, "Failed to create mTLS certificate."

(Optional) Delete Unused/Expired CA Certificates

Multiple CA certificates may be active at a time. If there are any unused, expired, or compromised CA certificates, they can also be removed via this screen.

Upload Certificate and Private Key Business Manager Troubleshooting

Upload Certificate and Private Key (CDN-API)

Format Certificate and Private Key

Before uploading via CDN-API, the crt and key files need to be formatted to what CDN-API expects them to be in. The contents of the crt and key files above will need literal newlines replaced with \n. Below is a reference command that can be used for this:

$ cat ${CERT_HOST}.crt | perl -pe 's/\n/\\n/g'
$ cat ${CERT_HOST}.key | perl -pe 's/\n/\\n/g'

You can also use a text editor with regular expression support, such as Sublime Text, to do this by using find and replace. With Sublime Text:

1. Open the crt file
2. In the menu bar, select Find → Replace...
3. Ensure that the Regular Expression setting is enabled (the .* button)
4. Fill in the following:
   1. Find: \n
   2. Replace: \\n
5. Select Replace All
6. Save the file
7. Repeat for the key file

This output will be used in the following step.

Make API Calls to Upload Certificate and Private Key

With these files now in the expected format, upload the certificate to eCDN using CDN-API. You can either use the curl command or use an application like Postman for this. To make the API call, you will first need to obtain an access token to be passed in the Authorization header. Refer to the Authorization for SCAPI Admin APIs document for details. The OAuth scope needed to make CDN API call is sfcc.cdn-zones.rw

Reference curl command to obtain access token to call CDN API

curl "https://account.demandware.com/dwsso/oauth2/access_token" \
  --request 'POST' \
  --user "<api_client_id>:<client_secret>" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:<realm>_stg sfcc.cdn-zones.rw"

Reference curl command for CDN-API call to upload the certificate

curl --location 'https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abcd*****' \
  --data '{
    "name": "client ca for code upload",
    "certificate": "-----BEGIN CERTIFICATE-----\ncacertificatestring\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nprivatekeystring\n-----END PRIVATE KEY-----"
  }'

Note: certificate and privateKey values are based on the formatted values obtained in the previous step.

Reference curl command for CDN-API call to get code upload certificates used to check existing certificates

curl --location 'https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abcd*****'

Reference curl command for CDN-API call to delete existing code upload certificates using the mtlsCertificateId obtained via the GET call

curl --location 'https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates/{mtlsCertificateId}' \
  --request 'DELETE' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer abcd*****'

Note: You can find your short code by logging into your Staging instance and navigating to Administration > Site Development > Salesforce Commerce API Settings.

CDN-API Troubleshooting

If you get unauthorized errors or 403 status code, ensure that you have configured your API client with correct default and allowed scopes as well as ensure the credentials you are passing are correct.

The default scopes should contain the following:

mail
roles
tenantFilter
profile
openId

The allowed scopes should contain the following:

sfcc.cdn-zones
sfcc.cdn-zones.rw

If you get the certificate cannot be parsed error, make sure your certificate was reformatted correctly as well as check that the certificate and privateKey match using a tool like https://www.sslchecker.com/matcher (Note: Do not put in the reformatted certificate and privateKey into this tool as it expects the certificate and privateKey in the original format.)

Signing Certificates with the CA Certificate

Client certificates should be generated per user, but can be signed with the same CA certificate. For each user, complete the following steps:

1. Create a CSR:

USER=<bm_username>
openssl req -new -sha256 -newkey rsa:2048 -nodes -out ${USER}.req -keyout ${USER}.key

Note: USER should be the Business Manager username. Challenge password and optional company name should be omitted.

2. Sign the CSR using the CA certificate above:

openssl x509 -CA ${CERT_HOST}.crt -CAkey ${CERT_HOST}.key -req -in ${USER}.req -out ${USER}.pem -days 90

3. Finally, convert the signed certificate to a p12 file. The export password needs to be configured and shared with the user of the client certificate.

openssl pkcs12 -export -legacy -in ${USER}.pem -inkey ${USER}.key -certfile ${CERT_HOST}.crt -name ${USER} -out ${USER}.p12

Note: -legacy flag is needed for newer versions of openssl to import to Mac keychain.

4. The ${USER}.p12 file can now be used with UX Studio and WebDAV clients like CyberDuck.

Rotating/Renewing the CA Certificate

The CA certificate bundle is allowed a maximum expiry of 1 year. Before it expires it will need to be renewed in order to avoid disruption with code uploads. This procedure should also be followed if the security of the CA certificate or any client certificate that it has signed has been compromised.

To renew the certificate, follow the instructions above to generate and upload a new certificate. Multiple CA certificate bundles can be active at the same time to allow for overlap during renewals. New client certificates will also need to be generated and signed by this new bundle to work properly.

Once the client certificates have been replaced and validated as working, the previous CA certificate bundle should be removed. This can be done via Business Manager on the same page as where the bundle was originally uploaded, or it can be removed using the CDN-API delete code upload certificate endpoint.