B2C Commerce Hyperforce における Staging 環境へのコードアップロード手順のご案内

Hyperforce における Staging インスタンスへのセキュアなコードアップロードのための2要素認証(2FA)システムが変更されました。本記事では、この変更点の詳細と、お客様自身での自己署名 CA 証明書バンドルの生成、eCDN へのアップロード、およびクライアント証明書の署名とローテーションの手順について説明します。

Hyperforce における変更点

Hyperforce への移行に伴い、Staging インスタンスへのセキュアなコードアップロードのための 2要素認証(2FA)システムが変更されました。主な変更点は以下の通りです。

1. コードアップロードには、標準の Business Manager のホスト名（例：staging-realm-customer.demandware.net）を使用します。

   1. コードアップロード用の個別のホスト名はなくなり cert.staging.realm.customer.demandware.net のホスト名は無効化されます。

   2. 通常の Business Manager の操作にはクライアント証明書は不要です。2FAクライアント証明書は、コードアップロードにのみ必要となります。

2. Salesforce B2C Commerce から CA 証明書バンドルは提供されなくなります。代わりにお客様自身で CA 証明書バンドルを生成し、eCDN に登録していただきます。この CA 証明書バンドルの初期アップロードおよびローテーションは、セルフサービスで行います。

   1. Salesforce では CA 証明書バンドル自体にアクセスできなくなるため、お客様のセキュリティが向上します。

   2. お客様が生成した CA 証明書バンドルによって署名されたクライアント証明書は、eCDN レイヤーでチェックおよび検証されます。

   3. この CA 証明書バンドルの有効期限は最大 365 日です。

以下の手順は、自己署名CA証明書バンドルを生成し、eCDN にアップロード/登録する方法の概要を示しています。

[推奨事項]

Hyperforceへの移行準備として、この手順に従うことをお勧めします。Hyperforce 移行が完了するまでは、 古い cert.staging.realm.customer.demandware.net ホスト名を持つ既存のクライアント証明書を引き続き使用してください。

移行後は、標準の Business Manager ホスト名を持つ新しいクライアント証明書を使用します。

自己署名 CA 証明書バンドルの生成

証明書と秘密鍵の作成

<realm> と <customer> をお客様のレルムに置き換えて、以下の openssl コマンドを実行します。

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

$ 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 []:

証明書と秘密鍵のアップロード

次に、CA 証明書と秘密鍵を eCDN にアップロードする必要があります。これは Business Manager UI または CDN-API を介して実行できます。完了すると、eCDN はこの CA 証明書によって署名されたクライアント証明書を受け入れるように構成されます。

Business Manager UI を介した証明書と秘密鍵のアップロード 

1. Staging 環境の Business Manager で「管理 >  サイトの開発  > 開発セットアップ >コードアップロード証明書」に移動する。

2. 画面右側の 「証明書の追加」 をクリックする。

3. 管理目的の名前にて「証明書名」を入力する。

4. 上記「自己署名 CA 証明書バンドルの生成」手順で生成した証明書(.crt)と秘密鍵(.key)をテキストエディターで開き、各ファイルのテキストを「証明書」「秘密鍵」に貼り付ける。

5. 「保存」をクリックする。

補足: 手順「自己署名CA証明書バンドルの生成」から生成した CA 証明書をアップロードしていることをご確認ください。クライアント (リーフ) 証明書をアップロードしようとすると、「Failed to create mTLS certificate.」というエラーメッセージが表示されます。

(任意)未使用または期限切れ、または不正利用の恐れがある CA 証明書の削除 

複数の CA 証明書を同時にアクティブにすることができます。未使用、期限切れ、または不正利用の恐れがある CA 証明書がある場合は、「管理 >  サイトの開発  > 開発セットアップ >コードアップロード証明書」から削除することもできます。

証明書アップロードのトラブルシューティング

「Certificate Creation Error. The certificate couldn't be created」というエラーが発生した場合は、以下のコマンドをお試しください。

openssl x509 -in <their.crt> -text -noout | grep -A2 -E "Basic Constraints|Signature Algorithm"

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

CDN-API を使用した証明書と秘密鍵のアップロード

証明書と秘密鍵のフォーマッティング

CDN-API を介してアップロードする前に、crt ファイルと key ファイルを CDN-API がサポートする形式に変更する必要があります。上記の crt ファイルと key ファイルの内容は、改行文字を \n に置き換える必要があります。以下は、この場合、使用できるリファレンスコマンドです。

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

Sublime Text のように正規表現をサポートするテキストエディターを使用して、検索と置換を行うこともできます。Sublime Text を使用する場合の手順は以下の通りです。

1. crt ファイルを開く。

2. メニューバーで、[Find] →  [Replace...] を選択する。

3. 正規表現の設定 (.* ボタン) が有効になっていることを確認する。

4. 以下の内容を入力する。

• • Find: \n

  • Replace: \\n

5. [Replace All] を選択する。

6. ファイルを保存する。

7. key ファイルについても上記の手順を繰り返す。

出力結果は、次の手順にて使用されます。

証明書と秘密鍵をアップロードするための API コールの実行 

証明書と秘密鍵のフォーマッティングを完了後、CDN-API を使用して証明書を eCDN にアップロードします。これには、curl コマンドを使用するか、Postman のようなアプリケーションを使用できます。API コールを実行するには、はじめに Authorization ヘッダーで渡されるアクセストークンを取得する必要があります。

詳細については、「SCAPI Admin API の認可」ドキュメントを参照してください。CDN API コールの実行に必要な OAuth スコープは 「sfcc.cdn-zones.rw」です。

CDN API を利用するためのアクセストークンを取得するリファレンス curl コマンド: 

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"

証明書をアップロードする CDN-API コールのリファレンス curl コマンド: 

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

補足: 上記 「certificate」および「privateKey」の値は、手順「証明書と秘密鍵のフォーマッティング」で取得したフォーマット済みの値をご利用ください。

既存の証明書を確認するために使用されるコードアップロード証明書を取得する CDN-API コールのリファレンス curl コマンド:

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*****'

GET コールを介して取得した mtlsCertificateId を使用して、既存のコードアップロード証明書を削除する CDN-API コールのリファレンス curl コマンド: 

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*****'

補足: ショートコード<shortcode>は、Staging 環境の Business Manager にログインし、「管理 >  サイトの開発 >  Salesforce Commerce API 設定」にてご確認いただけます。

CDN-API のトラブルシューティング 

認証エラーまたは 403 ステータスコードが表示される場合は、API クライアントに正しい Default Scopes と Allowed Scopes が設定されていること、および渡している認証情報が正しいかご確認ください。

 Default Scopes には、以下を含める必要があります。

mail
roles
tenantFilter
profile
openId

 Allowed Scopes には、以下を含める必要があります。

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

証明書を解析できないというエラー(certificate cannot be parsed)が表示される場合は、証明書が正しくフォーマッティングされていることを確認し、https://www.sslchecker.com/matcher などのツールを使用して証明書と秘密鍵が一致していることを確認してください

※ SSL match CSR/Private Key ツールには、フォーマッティング前、つまり元の証明書と秘密鍵の形式にて入力してください。

CA 証明書を使用した証明書の署名 

クライアント証明書はユーザーごとに生成する必要がありますが、同じ CA 証明書で署名することができます。各ユーザーについて、以下の手順を実施します。

1. CSR を作成する:

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

補足: USER は Business Manager のユーザー名である必要があります。チャレンジパスワードとオプションの会社名は省略します。

2. 上記の CA 証明書を使用して CSR に署名する。

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

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

補足: Mac キーチェーンにインポートするには、新しいバージョンの openssl に -legacy フラグが必要です。

4. ${USER}.p12 ファイルを UX Studio や CyberDuck などの WebDAV クライアントで使用できる。

CA 証明書のローテーション / 更新

CA 証明書バンドルの有効期限は最大 1 年です。コードのアップロードの中断を避けるために、期限切れになる前に更新する必要があります。CA 証明書、または CA 証明書が署名したクライアント証明書のセキュリティが侵害された場合も、この手順に従う必要があります。

証明書を更新するには、上記の手順に従って新しい証明書を生成してアップロードします。更新中の重複を可能にするために、複数の CA 証明書バンドルを同時にアクティブにすることができます。新しいクライアント証明書も生成し、この新しいバンドルで署名して適切に機能するようにする必要があります。

クライアント証明書が置き換えられ、機能することが検証されたら、以前の CA 証明書バンドルを削除する必要があります。これは、バンドルが最初にアップロードされたのと同じページの Business Manager を介して実行するか、CDN-API の削除コードアップロード証明書エンドポイントを使用して削除することができます。