Private Operator for Azure integration guide

UID2 Operator は、UID2 エコシステム内の API サーバーです。詳細は、UID2 Operator を参照してください。

このガイドでは、Microsoft Azure の機密コンピューティングオプションである Confidential Containers のインスタンスで、Private Operator として UID2 Operator Service をセットアップするための情報を提供します。Confidential Containers インスタンスは、データ整合性、データ機密性、およびコード整合性などの本質的な機能を提供する、ハードウェアでバックアップされた信頼できる実行環境（Trusted Execution Environment: TEE）で実行されます。

UID2 Operator Confidential Containers インスタンスの Docker コンテナが起動すると、UID2 Core Service が Operator Service と Operator Service が実行されているエンクレーブ環境の真正性を検証できるように、アテステーション プロセスが完了します。

認証が成功すると、UID2 Core Service は、UID2 Operator を安全な UID2 Operator Confidential Containers インスタンスでブートストラップするためのソルトやキーなどのシード情報を提供します。

注意

UID2 Private Operator for Azure は、次の地域ではサポートされていません: ヨーロッパ、中国。

Operator version

最新の ZIP ファイルは、次の表の Azure Download 列にリンクされています。

Version Name	Version Number	Release Notes	Azure Download	Date	Deprecation Date
H1 2026	v5.70.159	v5.70.159	azure-cc-deployment-files-5.70.159-r7.zip	September 9, 2026	June 30, 2027

注記

サポートされているバージョンと非推奨日については、Private Operator versions を参照してください。

Private Operator upgrade policy

セキュリティと運用の整合性を維持するため、古いオペレーターのバージョンは 12 ヶ月後に無効化され、影響を受けるデプロイメントがシャットダウンまたは起動に失敗する可能性があります。最新のセキュリティと機能強化を使用するために、アップグレードを推奨します。中断を避けるために、積極的なアップグレードを推奨します。

注記

重要なセキュリティまたは運用上の問題、または契約条件が適用される場合、Private Operator に対してより厳しいアップグレードタイムラインを適用する権利を留保します。

Prerequisites

Azure に UID2 Private Operator をデプロイする前に、次の前提条件を満たす必要があります:

• Set up UID2 Operator account
• Install Azure CLI
• Get the required Azure permissions

Set up UID2 Operator account

UID2 Private Operator をデプロイする前に、UID2 Service の Private Operator として登録する必要があります。UID2 Private Operator として登録するには、UID2 連絡先に組織を UID2 Operator として登録するよう依頼します。誰に依頼すればよいかわからない場合は、Contact info を参照してください。

登録プロセスが完了すると、UID2 Service から UID2 Private Operator としての専用の Operator Key が送信されます。このキーは、UID2 Service との通信に使用されるもので、UID2 Service において Private Operator としてあなたを識別します。構成時に、このキーを OPERATOR_KEY の値として使用します。この値は、あなたの固有の識別子であり、パスワードでもあります。安全に保管し、共有しないでください。

注記

デプロイ環境ごとに別々の Operator Key を受け取ります。

Install Azure CLI

Azure CLI をインストールします。詳細は、Azure ドキュメントの Azure CLI のインストール方法 を参照してください。

Get the required Azure permissions

リソースグループを作成するには、サブスクリプション所有者の権限が必要です。

これが完了したら、リソースグループレベルでのコントリビューター権限のみが必要です。

詳細は、Azure ドキュメントの Azure roles を参照してください。

前提条件のすべての手順が完了したら、UID2 Private Operator をデプロイする準備が整います。Deployment を参照してください。

Preparing DII for processing

UID2 に変換する入力データが許容可能な形式であることは非常に重要です。そうでない場合、期待される結果は得られません。たとえば、Phone number normalization で説明されているように、電話番号には国コードを含めるように正規化する必要があります。

詳細は、Preparing emails and phone numbers for processing を参照してください。

フルトークン生成パイプラインをエンドツーエンドで検証し、正規化・ハッシュ化・エンコードされた値から生成されたトークンが正確であることを確認するためには、［UID2 Token Validator］（../ref-info/ref-token-validator.md）を使用してください。

Deployment environments

以下の環境が利用可能です。ベストプラクティスとして、本番環境にデプロイする前に、インテグレーション環境で実装をテストして検証することを推奨します。

注記

各環境に対して別々の {OPERATOR_KEY} 値が受け取れます。使用する環境に応じて正しいキーを使用してください。デプロイメントの成果物と処理の流れは、どちらの環境でも同じです。

Environment	Details
Integration (integ)	テスト専用。デバッグモードはインテグレーション環境で使用できます。
Production (prod)	本番のトラフィックの管理。

Deployment

新しい UID2 Private Operator for Azure をデプロイするには、次の手順を完了する必要があります:

• Download ZIP file and extract files
• Create resource group
• Complete key vault and managed identity setup
• Set up the VPC network
• Complete the UID2 Private Operator setup
• Set up the Gateway Load Balancer

Download ZIP file and extract files

最初に、デプロイメントに必要なファイルを取得します:

1. 次の表の Azure Download 列にあるリンクをクリックして、最新バージョンの ZIP ファイルをダウンロードします。

2. ZIP ファイルを解凍して、デプロイメントに必要な次のファイルを取得します:

   • vault.json and vault.parameters.json
   • vnet.json and vnet.parameters.json
   • operator.json and operator.parameters.json
   • gateway.json and gateway.parameters.json

Create resource group

Azure で UID2 Operator を実行するためのリソースグループを作成するには、次のコマンドを実行します:

az group create --name {RESOURCE_GROUP_NAME} --location {LOCATION}

備考

すべてのリソースは、後で指定する {RESOURCE_GROUP_NAME} 値の名前の下にプロビジョニングされます。

ロケーションには、いくつかの制限があります:

• UID2 Private Operator for Azure は、次の地域ではサポートされていません: Europe、China。

• Azure 仮想ネットワーク展開の可用性は、Azure ドキュメントの Linux container groups を確認し、Confidential Containers の地域サポートの可用性を確認してください。

• 場所のエイリアスを取得するには、次のコマンドを実行します。

az account list-locations -o table

Complete key vault and managed identity setup

次のステップは、key vault を設定し、Operator Key を保存することです。

Key Vault を作成したら、managed identity を作成し、Key Vault へのアクセス権を付与します。

後で、Azure Container Instances (ACIs) がこの ID で起動します。

次の手順に従います:

1. vault.parameters.json ファイルを次の必要な値で更新します:

   Parameter	Description
   vaultName	Operator Key シークレットをホストするための Key Vault の名前。選択する名前はグローバルに一意である必要があります。
   operatorKeyValue	アカウント設定の一環として UID チームから受け取った OPERATOR_KEY シークレット値 (Set up UID2 Operator account を参照)。この値はあなたに固有であり、パスワードとして機能します。安全で秘密に保つ必要があります。

2. (オプション) デフォルトを受け入れたくない場合は、vault.parameters.json ファイルを次の値で更新します。これらのパラメータはデフォルト値を受け入れたくない場合にのみ更新する必要があります。

   Parameter	Description
   operatorIdentifier	コンテナを起動するマネージド ID の名前。 デフォルト: uid-operator。
   operatorKeyName	Operator Key シークレット名。 デフォルト: operator-key。

3. 次のコマンドを実行してデプロイメントをトリガーします:

   az deployment group create --name vault --resource-group {RESOURCE_GROUP_NAME} --parameters vault.parameters.json  --template-file vault.json

Set up the VPC network

次のステップは、VPC ネットワークを設定することです。

Microsoft Azure で UID2 Private Operator をホストする Virtual Private Cloud (VPC) を示す次の図を参照してください。

次の手順に従います:

1. (オプション) デフォルトを受け入れたくない場合は、vnet.parameters.json ファイルを次の値で更新します。これらのパラメータはデフォルト値を受け入れたくない場合にのみ更新する必要があります。

   Parameter	Description
   vnetName	Virtual Network 名。 デフォルト: unified-id-network
   computeSubnetName	UID2 Operator を実行するサブネットの名前。 デフォルト: unified-id-subnet-operators
   gatewaySubnetName	UID2 Gateway を実行するサブネットの名前。 デフォルト: unified-id-subnet-gateway
   VnetAddressPrefix	Vnet アドレスプレフィックス。 デフォルト: 10.0.0.0/20
   computeSubnetPrefix	UID2 Operator を実行するサブネットに委任されたアドレスプレフィックス。 デフォルト: 10.0.0.0/24
   gatewaySubnetPrefix	UID2 Gateway を実行するサブネットのアドレスプレフィックス。 デフォルト: 10.0.1.0/28

2. 次のコマンドを実行してデプロイメントをトリガーします:

   az deployment group create --name vnet --resource-group {RESOURCE_GROUP_NAME} --parameters vnet.parameters.json  --template-file vnet.json

Complete the UID2 Private Operator setup

次のステップは、VPC サブネットで複数の Azure Container Instances (ACIs) を起動することです。

次の手順に従います:

1. operator.parameters.json ファイルを次の必要な値で更新します:

   Parameter	Description
   vaultName	Operator Key シークレットをホストするための Key Vault の名前。Complete key vault and managed identity setup で作成した名前と一致している必要があります。
   deploymentEnvironment	デプロイ先の環境を示します: integ または prod。詳細は Deployment environments を参照してください。

2. (オプション) デフォルトを受け入れたくない場合は、operator.parameters.json ファイルを次の値で更新します。これらのパラメータはデフォルト値を受け入れたくない場合にのみ更新する必要があります。

   Parameter	Description
   operatorKeyName	Operator Key シークレット名。値は Complete key vault and managed identity setup で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は operator-key です。
   operatorIdentifier	コンテナを起動するマネージド ID の名前。値は Complete key vault and managed identity setup で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は uid-operator です。
   vnetName	Virtual Network 名。値は Set up the VPC network で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は unified-id-network です。
   computeSubnetName	UID2 Operator を実行するサブネットの名前。値は Set up the VPC network で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は unified-id-subnet-operators です。
   count	起動するインスタンス数のカウント。デフォルトは 2 です。

3. 次のコマンドを実行してデプロイメントをトリガーします:

   az deployment group create --name operator --resource-group {RESOURCE_GROUP_NAME} --parameters operator.parameters.json  --template-file operator.json

4. 作成した ACI インスタンスの IP アドレスを取得するには、次のコマンドを実行します:

   az deployment group show -g {RESOURCE_GROUP_NAME} -n operator --query properties.outputs

   出力は次のようになります:

   { "ipAddress": { "type": "Array", "value": [ "10.0.0.5", "10.0.0.4" ] } }

Set up the Gateway Load Balancer

次のステップは、Gateway Load Balancer を設定し、作成した ACI のプライベート IP アドレスを使用して backend pool として使用することです。

次の手順に従います:

1. gateway.parameters.json ファイルを次の必要な値で更新します:

   Parameter	Description
   containerGroupIPs	作成した ACI インスタンスの IP アドレス。Complete the UID2 Private Operator setup Step 4 の出力値として出力される値を使用します。

   たとえば、更新されたファイルは次のようになります:

   "containerGroupIPs":{
     "value":[
       "10.0.0.5",
       "10.0.0.4"
     ]
   }

2. (オプション) デフォルトを受け入れたくない場合は、gateway.parameters.json ファイルを次の値で更新します。これらのパラメータはデフォルト値を受け入れたくない場合にのみ更新する必要があります。

   Parameter	Description
   vnetName	Virtual Network 名。値は Set up the VPC network で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は unified-id-network です。
   gatewaySubnetName	UID2 Gateway を実行するサブネットの名前。値は Set up the VPC network で指定した値と一致する必要があります。デフォルト値を受け入れた場合、値は unified-id-subnet-gateway です。

3. 次のコマンドを実行してデプロイメントをトリガーします:

   az deployment group create --name gateway --resource-group {RESOURCE_GROUP_NAME} --parameters gateway.parameters.json  --template-file gateway.json

4. Gateway Load Balancer のパブリック IP アドレスを取得するには、次のコマンドを実行します:

   az deployment group show -g {RESOURCE_GROUP_NAME} -n gateway --query properties.outputs

   出力は次のようになります:

   { "gatewayIP": { "type": "String", "value": "20.163.172.56" } }

ヒント

コンテナを更新しても、Azure バックエンドプールは新しいコンテナの IP アドレスで自動的に更新されません。ソリューションは、Azure ドキュメントの Automate infrastructure reconfiguration by using Azure を参照してください。

注意

この例では、HTTP を使用して Gateway Load Balancer をデプロイします。SSL を設定することを強く推奨します。手順は、Azure ドキュメントの Tutorial: Configure an Application Gateway with TLS termination using the Azure portal を参照してください。

Running the health check

実装のヘルスチェックをテストするために、ヘルスチェックエンドポイントを呼び出します。

インテグレーション環境と本番環境でヘルスチェックを実行する方法は同じですが、エンドポイントが異なります。

次の手順に従います:

1. Gateway Load Balancer のパブリック IP アドレスを取得します。これは、Set up the Gateway Load Balancer Step 4 の出力値です。

2. オペレーターステータスをテストするために、ブラウザでヘルスチェックエンドポイントに移動します: http://{LB_IP}/ops/healthcheck。

   HTTP 200 と OK というレスポンス本文が表示された場合、正常な状態です。

Private Operator attestation failure

Private Operator が Core Service による検証に失敗した場合、次のいずれかのアクションが発生します:

• HTTP 401 レスポンス。Private Operator はすぐに終了します。
  • 原因: Operator Key が取り消されたか、間違っています。
• その他の 200 以外のレスポンスコード。Private Operator は 12 時間機能し続けます。この期間内に問題が解決されない場合、自動的に終了します。

Private Operator がエラーが発生した場合、アラートを処理し、オペレーターを再起動するためのインフラストラクチャを用意する必要があります。

Scraping metrics

Azure の Private Operator は、ポート 9080 で /metrics エンドポイントを介して Prometheus 形式のメトリクス を公開します。これらのメトリクスを収集して集計するには、Prometheus 互換のスクレイパーを使用できます。

スクレイパーは、Private Operator が実行されている VNet にアクセスできる必要があります。ロードバランサーに /metrics エンドポイントへのアクセスを許可することは推奨しません。

Network security group policy

注記

ドメインに関連付けられた証明書がエンクレーブに渡されるのを防ぐため、許可されるのはインバウンド HTTP のみです。インバウンド HTTPS は許可されません。これにより、すでに組織内のプライベートネットワークである環境において、追加のセキュリティ層を導入することによる余分な負荷も回避できます。

以下の表は、サポートされているプロトコルに関する情報を提供します。

Port Number	Direction	Protocol	Description
80	Inbound	HTTP	ヘルスチェックエンドポイント /ops/healthcheck を含むすべての UID2 API を提供します。 すべてが正常に稼働している場合、エンドポイントは HTTP 200 とレスポンス本文 OK を返します。詳細は Running the Health Check を参照してください。
9080	Inbound	HTTP	Prometheus メトリックを提供します (/metrics)。詳細は Scraping Metrics を参照してください。
443	Outbound	HTTPS	UID2 Core Service と Azure Blob Storage への呼び出し、オプトアウトデータとキーストアのファイルをダウンロードします。

注記

アウトバンドのネットワークが制限されている場合は、Private Operator network egress に記載されている宛先へのアウトバウンドアクセスを許可する必要があります。

Upgrading

UID2 Azure Confidential Containers の新しいバージョンがリリースされると、Private Operator は新しいリリースリンクを含む更新通知のメールを受信します。アップグレードのためのウィンドウがあり、その後、古いバージョンは非アクティブ化され、サポートされなくなります。

アップグレードするには、次の手順を完了します:

1. Download ZIP file and extract files の手順に従って、新しいバージョンのデプロイメントファイルをダウンロードし、解凍します。

2. Complete the UID2 Private Operator setup の手順に従って、新しいバージョンのファイルを使用して ACI をデプロイします。

3. Set up the Gateway Load Balancer の手順に従って、新しい ACI を Gateway Load Balancer に追加します。

4. 新しい ACI のヘルスチェックを確認し、ステータスが healthy であることを確認します:

   az network application-gateway show-backend-health --resource-group {RESOURCE_GROUP_NAME} --name uid-operator-gateway

5. Gateway Load Balancer から古い ACI を削除します。Set up the Gateway Load Balancer の手順に従って、古い ACI をバックエンドプールから削除します。

6. 以下のコマンドを実行して、古い ACI をシャットダウンします:

   for i in {0..COUNT}; az container delete --name uid-operator-OLD-VERSION-$i --resource-group {RESOURCE_GROUP} --yes

Keeping the operator key secure

Operator Key を安全に保つためのガイドラインを以下に示します:

• Operator Key を受け取ったら、安全な場所に保管してください。
• キーが使用されているすべての場所を把握しておき、キーをローテーションする必要がある場合に迅速に対応できるようにしてください。
• キーが漏洩した場合に備えて、既存の値を新しい値に置き換えるプロセスを確立してください。
• 定期的なサイクル（例えば、毎年）でキーをローテーションし、キーが漏洩するリスクを軽減してください。

UID2 Operator error codes

以下のセクションでは、Private Operator の起動時またはランタイム中に発生する可能性のあるエラーコードを一覧表示しています。

注記

Private Operator 起動時のエラーコードは、リリース v5.49.7 以降のバージョンに適用されます。

Startup errors

起動時に発生する可能性のあるエラーを次に示します:

Error Code	Issue	Steps to Resolve
E02	OperatorKeyNotFoundError	Operator Key を格納するシークレットボールトとシークレット名が正しく構成されていることを確認してください。VAULT_NAME と OPERATOR_KEY_SECRET_NAME として設定されていることを確認してください。
E03	ConfigurationMissingError	構成に必要な属性が不足しています。詳細は、ログを参照し、Azure オペレーターを実行する前に不足している属性を更新してください。
E04	ConfigurationValueError	構成値が無効です。構成値が必要な形式と環境に一致していることを確認してください。Note: debug_mode = true は integ 環境でのみ許可されます。詳細はログを確認してください。
E05	OperatorKeyValidationError	Operator Key が環境に適しており、提供されたものと一致していることを確認してください。
E06	UID2ServicesUnreachableError	UID2 Core Service および Opt-Out Service の IP アドレスをアウトバウンドファイアウォールで許可します。IP アドレスと DNS の詳細は、ログを参照してください。
E08	OperatorKeyPermissionError	コンテナを起動するマネージド ID (operatorIdentifier パラメータで指定) は、 Operator Key が格納されている Key Vault へのアクセス権を持っている必要があります。operatorIdentifier の値は、すべての構成 JSON ファイルで同じである必要があります。

Runtime errors

ランタイム中に発生する可能性のあるエラーを次に示します:

Error Code	Issue	How to Identify in Logs	Steps to Resolve
E12	Data Download Failure	E12: Data Download Failure を含むログメッセージ、または RotatingStoreVerticle からの Failed to load エラーを確認してください。これらのメッセージには、HTTP ステータスコード（例：HTTP response code 403）や例外の種類（例：exception: IOException）が含まれます。	エラーメッセージ内の HTTP ステータスコードまたは例外を確認し、それに応じて対処してください: 404 エラー: Operator Key が環境に対して有効であることを確認してください。 403 エラー: Operator Key および認証情報が正しいことを確認してください。 タイムアウトエラー: ネットワーク接続を確認し、ファイアウォール／セキュリティグループの設定で HTTPS（ポート 443）へのアウトバウンド通信が許可されていることを確認し、UID2 Service のエンドポイントにアクセス可能であることを確認してください。 500/503 エラー: このコードは一時的な UID2 Service の問題を示します。再試行し、エラーが継続する場合は UID2 サポートへ連絡してください。