Azure Key Vault を設定してキーをセキュアに管理する
この記事では、Dynamics 365 Commerce で Azure Key Vault を設定してキーをセキュアに管理する方法について説明します。
一部の Dynamics 365 Commerce eコマースの開発シナリオによっては、資格情報やアクセストークンなどのビジネスに関するデータを安全に保管することが必要なものがあります。 Azure Key Vault を使用すると、必要に応じて安全にアクセスできる暗号キーおよび証明書をインポート、保存、および管理できます。
この記事では、以下を実行する方法について説明します:
- 機密情報を安全に格納する Key Vault を作成します。
- Retail Server と安全に通信するよう、eコマース サイトを構成します。
- Key Vault と安全に通信するよう、Retail Server を設定します。
- eコマース コンポーネント内のシークレット値にアクセスします。
アプリケーションのシークレットを保存する Key Vault を作成する
最初の手順は、アプリケーション シークレットを保存するための新しい Key Vault を作成することです。 Azure Key Vault にアクセスするには、Azure アカウントが必要です。
新しい Key Vault を作成するには、次の手順に従います。
- Azure ポータル ホームページに移動します。
- リソースを作成する を選択します。
- Key Vault を検索してから、作成を選択します。
- この Key Vault を含むサブスクリプションおよびリソース グループを選択します。
- Key Vault の名前、地域、および価格レベルを入力します。
- 次へを選択してから、アクセス ポリシーを作成し、ユーザーにアクセス許可を割り当てます。 その他の設定はそのままにしてください。
- レビュー + 作成を選択します。
- コンフィギュレーションを確認した後、作成を選択してから、展開が完了するまで待ちます。
- Key Vault が正常に展開された後に、シークレットの下で任意のシークレットを追加できます。
eコマース Node アプリケーションと Retail Server 間のサーバー間認証を構成する
メモ
Commerce バージョン 10.0.31 以降を実行している場合は、このセクションは省略できます。
次に、eコマース Node アプリケーションを、Retail Server と安全に通信するように構成する必要があります。
次の手順では、Node アプリケーションをホストしている Azure App Service のテナント ID と、Azure App Service に関連付けられた管理 ID のクライアント ID が必要です。 これらの ID にはアクセスできないので、必要な情報を得るためにサービス統合またはサポート チームと協力してください。 これらの ID がを使用可能になったら、次の手順を続行できます。
Node アプリケーションの詳細を Retail Server の認証許可一覧に追加する
メモ
Commerce バージョン 10.0.31 以降を実行している場合は、このセクションは省略できます。
Node アプリケーションの詳細を Retail Server の認証許可一覧に追加するには、次の手順に従います。
- Commerce headquarters で、Commerce 共有パラメーターに移動します。
- ID プロバイダー タブを選択します。
- IDENTITY PROVIDERS という名前の最初のセクションで、追加を選択します。
- 発行者値に、<TENANT_ID> がテナント ID である
https://sts.windows.net/<TENANT_ID>/を入力します。 末尾に余分なスペースを追加する必要はありません。 - 名前に、"Azure AD" を入力します。 名前では大文字と小文字が区別されるため、表示されているとおりにコピーしてください。
- タイプに、「Active Directory」と入力します。
- RELYING PARTIES という 2 番目のセクションで、管理 ID のクライアント ID のエントリを入力します。
- タイプに、機密情報を選択します。
- UserType に、アプリケーションを選択します。
- Node アプリケーションの名前を入力します。
- SERVER RESOURCE IDS という 3 番目のセクションで、
https://commerce.dynamics.comのサーバー リソース ID のエントリを追加してから、保存を選択します。
これで、次の例と同様のコンフィギュレーションになったはずです。
変更をチャネル データベースに同期化するには、Commerce Headquarters で配送スケジュールに移動し、次の画像に示すように、ジョブ 1110 (グローバル コンフィギュレーション) を実行します。
これで、Node アプリケーションは、Retail Server から Key Vault シークレットに安全に通信して要求することができるようになります。
Key Vault の詳細を Retail Server に追加する
次に、Retail Server を構成して Key Vault と安全に通信します。
新しいアプリ登録を作成し、クライアント シークレットを追加する
最初に、Retail Server を表す Azure AD で新しいアプリ登録を作成する必要があり、これにより Retail Server に Key Vault を登録することができます。
新しいアプリ登録を作成するには、次の手順に従います。
Azure ポータル ホームページに移動します。
Node アプリケーションをホストしている Azure App Service を含むディレクトリに移動します。
Azure Active Directory に移動します。
左側のナビゲーション ウィンドウで、アプリ登録を選択します。
新しい登録を選択してから、名前を入力します (たとえば、"RetailServer")。
概要パネルで、アプリケーション (クライアント) ID 値を後で使用できるようにコピーして保存します。
証明書 & シークレットを選択してから、クライアント シークレットで、新しいクライアント シークレットを選択します。
クライアント シークレットを追加ダイアログ ボックスの、説明の下で説明を入力します (たとえば、"retail-server-secret")。
有効期限で、表示しないを選択してから、OK を選択します。
証明書 & シークレット ページで、新しいクライアント シークレットの値ボックスのシークレット値をコピーして、安全な場所に格納します。 このシークレット値は、Retail Server と Key Vault 間の通信を可能にするものです。
メモ
そのシークレット値をコピーする機会は 1 度だけなので、今のうちにコピーするのが重要です。
Key Vault にアクセス ポリシーを追加する
次に、Key Vault にアクセス ポリシーを追加するには、次の手順に従います。
- Key Vault に移動します。
- アクセス ポリシーを選択してから 、アクセス ポリシーの追加を選択します。
- 1 つ目のオプションとして、キー, シークレット、および証明書の管理を選択します。
- プリンシパルの選択で、前に登録したアプリを検索して選択します (たとえば、"RetailServer")。
- 承認されたアプリケーションを空白のままにします。
- 保存を選択します。
Key Vault の詳細を Retail Server に追加する
次に、Retail Server に Key Vault の詳細を追加するには、次の手順に従います。
- Commerce headquarters で、Key Vault パラメーターに移動します。
- 右上隅にある店舗セレクターから、シークレット キーと値を構成する店舗を選択します。
- 新規を選択してから、Key Vault に表示する名前を入力します。
- Key Vault URL を入力します。 これが、Key Vault の概要ページに一覧表示されている Vault URI 値です。
- Key Vault クライアントを入力します。 これが登録済アプリのアプリケーション ID です。
- Key Vault シークレット キーを入力します。 これは、アプリ登録プロセスから保存されたシークレット値です。
- Retail Server からアクセスするシークレットを追加します。 たとえば、シークレット名が "retail-server-test-secret" の場合、"retail-server-test-secret" を名前として、"vault:///retail-server-test-secret" をシークレットとして追加します。 シークレット タイプは手動に設定される必要があります。
- 検証を選択してコンフィギュレーションをテストします。 すべてが正しく構成されている場合は、「検証に成功しました」というメッセージが表示されます。
重要
シークレット キーと値の構成に使用された店舗の作業単位番号を確認します。 これは Commerce headquarters の、小売とコマース > チャネル > オンライン店舗で検索できます。 この値は、プラットフォーム設定 JSON ファイルで指定する必要があります。
eコマース Node アプリケーション内のシークレット値にアクセスします
上記のコンフィギュレーション手順が完了すると、SecretManager クラスを使用して、eコマース Node アプリケーション内のシークレット値にアクセスできます。 このクラスは、グローバル msdyn365Commerce オブジェクトで初期化され 、次の例に示すインターフェイスを実装します。 secretKey と共に、 Retail Server の baseURL を 2 番目の引数として渡す必要があります。 この基本 URL は requestContext.apiSettings.baseUrl API の下にある RequestContext API で検索できます。データ アクション内部のアクション コンテキストまたはモジュール内の props.context コンテキスト オブジェクトを通じてアクセスできます。
export interface ISecretManager {
getSecretValue(secretKey: string, baseRetailServerUrl: string): Promise<ISecretValue>;
}
export interface ISecretValue {
value: string; // secret value
id?: string; // secret ID (if applicable)
error?: Error; // Error details (set if request to fetch secret value failed)
expiresOn: number; // Unix timestamp (in seconds) when the secret value will expire
}
これをコードにインポートするには、次の例に示すように、msdyn365Commerce を ‘@msdyn365-commerce/core' ライブラリのインポート ステートメントに追加します。
import msdyn365Commerce, { IRequestContext, … } from '@msdyn365-commerce/core';
次の例では、SecretManager クラスを使用してシークレット値にアクセスする方法を示します:
const secretValue: ISecretValue | undefined = await msdyn365Commerce.secretManager?.getSecretValue('secretKey', requestContext.apiSettings.baseUrl);
secretManager クラスはサーバー側の実行時にのみシークレットをフェッチできるため、SecretManager は msdyn365Commerce で Nullable プロパティであることに注意してください。 これは、ブラウザーに対してシークレット値がリークするのを防ぐためです。 secretManager プロパティが未定義の場合は、コードがブラウザー (クライアント側) のコンテキストで実行されていることを示します。
開発者として、SecretManager クラスは、サーバー側で確実に実行されるコード (サーバー側でのみ実行されるデータ アクションなど) 上でのみ使用される必要があります。それ以外の場合はシークレット値にアクセスできないためです。 コンテキスト (サーバー側とクライアント側) の両方で実行されるコードにこのプロパティを含める場合、secretManager プロパティが未定義の場合は、代替オプションを含めることが重要です。
そのシークレット値をフェッチする要求に失敗した場合、error プロパティが設定されます。 これを使用して、シークレット値のフェッチを試みる際に生じ得る問題をデバッグすることができます。
プラットフォーム設定ファイルを更新する
platform.settings.json ファイルで secretsManagerOUN プロパティを更新して、Key Vault パラメーターが構成された店舗やチャネルの作業単位番号を指定します。 詳細については、プラットフォーム設定ファイルを参照してください。
ローカル開発
eコマース Node アプリケーションは Retail Server としか通信できず、展開された App Service 環境で安全に通信する必要があります。 つまり、ローカルに開発された場合、SecretManager クラスは Key Vault からシークレットを取得できません。 代わりに、Node アプリケーションにシークレット ディレクトリを作成し、secrets.json ファイルに追加できます。ローカルで開発する場合にのみ使用する secretKeys と secretValues を構成できます。
メモ
secrets/ディレクトリの下にあるすべてのものを .gitignore ファイルに追加して、シークレットがオンラインで漏洩するのを防ぐ必要があります。secrets/secrets.jsonファイルが作成され、ローカルの開発環境のsrcディレクトリではなく、ルート レベル ディレクトリに確実に配置される必要があります。
次の例は、secrets/secrets.json ファイルのコンテンツを示します。
{
"secretKey": "secretValue!"
}
このファイルを構成しない場合、ローカルでの開発中に SecretManager クラスが Key Vault と通信を試行する際に失敗し、エラーが発生する場合があります。