B2C Commerce Hyperforce 2FA Secure Upload Customer Instructions

Changes to 2FA for Secure Code Upload on Hyperforce

The system for 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 (eg., 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 SFCC, 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 cert bundle is completed as self-service
   1. SFCC 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 cert 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 BM hostname.

Generate and upload a self-signed CA cert bundle

Create 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 -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) []:cert.staging.realm.customer.demandware.net
Email Address []:

Upload certificate and private key

The CA certificate and private will next need to be uploaded to eCDN. This can be done via the BM UI, or using the CDN-API

Once this is complete, eCDN will be configured to accept client certificates signed by this CA cert.

Certificate upload using BM UI

In Business Manager for the Staging instance, navigate to Administration → Site Development → Development Setup → Code Upload Certificate (tab)

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

 
(Optional) Delete unused/expired CA certs

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

Certificate upload using 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. This output will be used in the following step:

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 advanced Regular Expression support, such as Sublime, to do this by using find and replace. With Sublime:

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

 Uploading the CA certificate

With these files now in the expected format, upload the cert 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 access token to be passed in the Authorization header
  • Follow the docs here https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html
  • 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 (Note: certificate and privateKey values are based of formatted values obtained in previous step)

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-----"
}'

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 (if expired, unused, or compromised) 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}' \
-X DELETE
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer abcd*****'

(Note: certificate and privateKey values are based of formatted values obtained in previous step) You can find your Shortcode 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

mail
roles
tenantFilter
profile
openId

• • The allowed scopes should contain

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

• If you get 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 cert

Client Certificates should be generated per user, but can be signed with the same CA cert

For each user complete the following steps:

1. Create a CSR (USER should be the BM username; challenge password and optional company name should be omitted):
   1. $ USER=<bm_username>
      $ openssl req -new -sha256 -newkey rsa:2048 -nodes -out ${USER}.req -keyout ${USER}.key
2. Sign the CSR using the CA cert above:
   1. openssl x509 -CA ${CERT_HOST}.crt -CAkey ${CERT_HOST}.key -req -in ${USER}.req -out ${USER}.pem -days 90
3. Finally, convert the signed cert to a p12 file (note -legacy flag needed for newer versions of openssl to import to Mac keychain), the export password needs to be configured and shared with the user of the client cert:
   1. openssl pkcs12 -export -legacy -in ${USER}.pem -inkey ${USER}.key -certfile ${CERT_HOST}.crt -name ${USER} -out ${USER}.p12
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 cert, 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 BM 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