Generate, Sign, and Use Client Certificates for Secure Code Uploads

Two-factor authentication to upload code securely to the staging instance requires a username and password or authentication token as one factor and a client certificate as the second factor. Generate the client certificate and sign it with a key provided by Salesforce. You can generate multiple client certificates with different expiration dates.

You must have a B2C Commerce Certificate.zip file to complete this procedure. Salesforce typically provides the Certificate.zip file as part of the realm provisioning request. You can also request a Certificate.zip file from Salesforce Customer Support.

The Certificate.zip file contains the following files:

<name>.key
<name>.crt
<name>.srl
<name>.txt

<name> is a unique identifier that reflects your instance or company name, plus a serial number. For <name>.srl only, the serial number is not included in the file name.

The <name>.txt file contains the passphrase used to access the key. You must provide this passphrase every time you sign a key request.

The files in Certificate.zip are highly sensitive. A best practice is to provide the files to only a single trusted employee within your organization, typically the administrator of your B2C Commerce instances.

If you are using Windows, install OpenSSL on your machine.
If you are using MacOS or Unix operating system, you don't have to install OpenSSL. OpenSSL is provided as part of the operating system.
1. Download a Windows OpenSSL client from the following location: http://www.slproweb.com/products/Win32OpenSSL.html
2. Accept the default installation instructions. OpenSSL is installed to C:\OpenSSL.
  These instructions assume the default installation location.
Create a certificate request.
1. Unzip the Certificate.zip file.
  If you are using Windows, unzip the contents of the file to the C:\OpenSSL\bin directory. If you are using MacOS or a Unix operating system, use any directory of your choice.
2. Navigate to the directory where you unzipped the contents of Certificate.zip.
3. To generate a request, enter the following command: openssl req -new -sha256 -newkey rsa:2048 -nodes -out <user>.req -keyout <user>.key
  Salesforce B2C Commerce doesn't support client certificates with key length less than 1024 bits. We recommend that you use client certificates with at least a 2048-bit length. <user> is the user that this key is for. We recommend that <user> be the same as the corresponding Business Manager user. For example, if the B2C Commerce instance username is jsmith, use jsmith for the certificate user. Don't use a generic name like Release Team.
  The result of this step is similar to the following:
```
Generating a 2048 bit RSA private key
....................
++++++++++++
........
++++++++++++
writing new private key to 'user.key'
-----
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]:
State or Province Name (full name) [Some-State]:
Locality Name (city) []:
Organization Name (company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (section) []:
Common Name (YOUR name) []:
Email Address []:
Enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
4. When prompted, provide your location and name information and the email address of the person using the certificate.
  We recommend that you leave the challenge password and optional company name blank. The challenge password isn't used.
  For example:
```
Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: Massachusetts
Locality Name (city) []:
Organization Name (company) [Internet Widgits Pty Ltd]: B2C Commerce
Organizational Unit Name (section) []: Customer Services
Common Name (YOUR name) []: John Smith
Email Address []: [email protected]
Enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
```
OpenSSL creates files named <user>.req and <user>.key, in the same directory where the contents of the Certificate.zip file are stored.
Sign the certificate request (<user>.req) with your certificate.
1. Enter the following command at the command prompt: openssl x509 -CA <name>.crt -CAkey <name>.key -CAserial <name>.srl -req -in <user>.req -out <user>.pem -days <days>
  - <days> is the number of days you want this client certificate to be valid.
  - <name> is the unique identifier provided by Salesforce, as reflected in the file names in the Certificate.zip file.
  - <user> is the user of the client certificate you are signing.
  For example:
  
  openssl x509 -CA cert.staging.web.customer.demandware.net_01.crt -CAkey cert.staging.web.customer.demandware.net_01.key -CAserial cert.staging.web.customer.demandware.net.srl -req -in jsmith.req -out jsmith.pem -days 10
  The result of this step is similar to the following:
```
Signature ok
subject=/C=XX/ST=XX/L=XX/O=XX/OU=XX/CN=XX/[email protected]
Getting CA Private Key
Enter pass phrase for name.key:
```
2. Enter the passphrase contained in <name>.txt in the Certificate.zip file to sign the certificate.
Export the certificate and client information to pkcs12 format.
1. Enter the following command: openssl pkcs12 -export -in <user>.pem -inkey <user>.key -certfile <name>.crt -name "<user>" -out <user>.p12
  - <name> is the unique identifier provided by Salesforce.
  - <user> is the user of the client certificate you are signing.
  For example:
  openssl pkcs12 -export -in jsmith.pem -inkey jsmith.key -certfile cert.staging.web.customer.demandware.net_01.crt -name "jsmith" -out jsmith.p12
  
  The system prompts for an export password for the file.
2. Specify an export password.
  Provide the export password to the person who uses the certificate.
  
  The system creates files named <user>.pem and <user>.p12 in the same directory where the contents of the Certificate.zip file are stored. You can use the <user>.p12 file to connect to a staging instance with UX Studio, as described in the next step. You can also use other WebDAV clients such as the Windows built-in WebDAV client, or third-party tools such as Cyberduck.
To connect to a staging instance with UX Studio, create a server connection.
1. Open UX Studio and click File > New > Digital Server Connection.
2. Enter the new instance URL as cert.staging.<realm>.<customer>.demandware.net.
3. Click the Use Certificate Authentication check box.
4. Browse to the <user>.p12 file and click Select.
5. Enter the export password for the <user>.p12 file.
6. Click Finish.
  If there is a proxy server between UX Studio and your instance, test your connection. If you can't connect to your staging instance, install the certificate on the proxy server. See your proxy server documentation for more information on uploading certificates.
7. If you have to extract the certificate from the pkcs12 file before uploading it to the proxy server, enter openssl pkcs12 -in <user>.p12 -clcerts -out <user>.cer
  - <user> is the user of the client certificate.
  For example:
```
openssl pkcs12 -in jsmith.p12 -clcerts -out jsmith.cer
```
  OpenSSL prompts you for the password on the pks12 file.