Creating and Using Certificates for Code Deployment

Salesforce B2C Commerce doesn't support client certificates with RSA algorithm and a key length less than 1024-bits. Salesforce recommends that customers use client certificates with at least a 2048-bit length.

Perform the following general tasks to create and use certificates.

  1. Install OpenSSL on your machine.
    1. Download a Windows or Linux OpenSSL client from the following location: http://www.slproweb.com/products/Win32OpenSSL.html
    2. For Windows users, accept the default installation instructions. OpenSSL will be installed to C:\OpenSSL by default.
      These instructions assume the default installation location.
  2. Create a new key and request using OpenSSL.
    1. Extract the Certificate.zip file in C:\OpenSSL\bin.
    2. Open the command prompt and enter C:\OpenSSL\bin\.
    3. In either case, enter the following command to generate a request: openssl req -new -newkey rsa:2048 -nodes -out $user.req -keyout $user.key
      $user: indicates the user that this key is for. We recommend that it be the same as the Business Manager user they are authenticating against. For example, if the B2C Commerce instance username is jsmith, the certificate should be named jsmith.
      Don't use generic names such as Release Team.
      The output should be as follows:
      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. The last two fields are optional. We recommend that you leave them blank. The challenge password isn't used.
    5. Fill out the request with your company name information and a valid email address. This should be the valid email address of the person using the certificate.
      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 []:
      
      B2C Commerce supports OpenSSL (http://www.openssl.org) certificates.
  3. Sign the certificate request ($user.req) with your certificate.
    1. Copy the results of the client key and client request to the same directory as the certificate and key (C:\OpenSSL\bin).
    2. Enter the following OpenSSL command into the command prompt: openssl x509 -CA $name.crt -CAkey $name.key -CAserial $name.srl -req -in $user.req -out $user.pem -days $days
      $days: The number of valid days for this client certificate following creation.

      $name: The name provided by Salesforce

      $user: The user of the client certificate you are signing

      The $name portion of the $name.srl file might be slightly different from other $name files. Make sure you enter the file name correctly.

      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

    3. The certificate will be valid until it expires or you ask B2C Commerce to revoke all certificates. Therefore you must plan carefully when assigning certificates to users.
      The output of this command should look as follows:
      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:
    4. Enter the pass phrase (contained in $name.txt) to sign the certificate.
  4. Export the certificate and client information to pkcs12 format.
    1. Enter the following command into the command prompt: openssl pkcs12 -export -in $user.pem -inkey $user.key -certfile $name.crt -name "$user" -out $user.p12
      $name: The name provided by Salesforce.

      $user: 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

    2. Specify an export password for this file. This password must be provided to the end user who will be loading the certificate into Studio or another keystore.
    3. The pkcs12 certificate can be used to connect to a Staging instance via Studio. The certificate can also be used with other WebDAV clients, such as the Windows built in WebDAV client. If the user wants to upload code via the Windows WebDAV, see Step 5, Otherwise, Step 5 isn't required.
  5. Import the pkcs12 file if creating a WebDAV connection.
    1. On the local machine, double-click the certificate to open it. The following window opens.

    2. Click Install Certificate. The Certificate Import Wizard opens.

    3. Click Next.

    4. Select the Automatically select the certificate store based on the type of certificate checkbox and click Next.

      A message appears indicating that you have successfully completed the certificate import.
    5. Click Finish. You will now be able to open a WebDAV connection using this certificate. You can also open Studio and import the certificate directly (see Step 6).
    6. Use the Add Network Wizard to create a WebDAV network location with Windows, using the following hostname: cert.staging.web.customer.demandware.net
      Reference the Microsoft hotfix (KB942392) to make the above work with the Windows Vista client (http://support.microsoft.com/KB/942392).
  6. Create a server connection via Studio.
    1. Open UX Studio and click File > New > Digital Server Connection. The following window opens.

    2. Make sure you enter the new instance URL. It should be in the format of cert.staging.realm.customer.demandware.net.
    3. Click the Use Certificate Authentication check box.
    4. Browse to the keystore (pkcs12) file you want to import and click Select.
    5. Enter the password supplied to you by your administrator.
    6. Click Finish to connect. The customer can now connect via Studio and WebDAV.
  7. If there is a proxy server between the UX Studio and your instance, you might need to also install the client certificate on the proxy server. This depends on how your proxy server is configured. Salesforce recommends that you test your connection and 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. Information on extracting the certificate from the pkcs12 file before uploading it to the proxy server is included below.
    You can ignore this step if your instance doesn't use a proxy server.

    To extract the client certificate from the PKCS12 file, enter the following command:

    openssl pkcs12 -in $user.p12 -clcerts -out $user.cer

    where $user is the user of the client certificate.

    For example:

    openssl pkcs12 -in jsmith.p12 -clcerts -out jsmith.cer

    When you enter this command, openssl prompts you for the password on the PKCS12 file. You might also be able to use the $user.pem file but might need to rename it based on your Proxy Server.