Azure App Service: Key Vault参照がSystem AssignedからUser Assignedに切り替わらない問題

概要

Azure App Service で Managed Identity を System Assigned から User Assigned に切り替えた際、
Key Vault 参照（@Microsoft.KeyVault(...) 形式の環境変数）が解決できなくなる問題に遭遇した。

System Assigned を削除し、User Assigned を割り当て、ロール（Key Vault Secrets User）も正しく付与したにもかかわらず、
ポータル上では Key Vault 参照が InvalidSyntax エラーとなり、コンテナは起動時に環境変数を取得できずクラッシュした。

環境

• Azure App Service (Linux, B1)
• Azure Key Vault (RBAC モード)
• User-Assigned Managed Identity

発生した事象

時系列

1. App Service を作成

2. az webapp identity assign で System Assigned Managed Identity を有効化

3. Key Vault に Key Vault Secrets User ロールを付与

4. 環境変数に @Microsoft.KeyVault(SecretUri=...) で Key Vault 参照を設定

5. → ここまでは正常に動作

6. User Assigned Managed Identity (id-app-api-dev) を作成

7. App Service に User Assigned Identity を割り当て

8. User Assigned Identity に Key Vault Secrets User + AcrPull ロールを付与

9. System Assigned Identity を az webapp identity remove --identities '[system]' で削除

10. → Key Vault 参照が全て失敗

ポータルでの表示

環境変数の「App Configuration Reference Details」パネル：

Identity:      System assigned managed identity   ← ここがUser Assignedに切り替わっていない
Status:        InvalidSyntax
Error details: Reference was not able to be resolved because invalid reference syntax found.

原因

keyVaultReferenceIdentity という隠し設定

App Service には Key Vault 参照を解決する際に使用する Identity を指定する keyVaultReferenceIdentity という設定がある。

• System Assigned Identity を最初に有効化すると、この値が暗黙的に SystemAssigned に設定される
• その後 User Assigned Identity を追加しても、keyVaultReferenceIdentity は自動で切り替わらない
• System Assigned を削除すると、「存在しない System Assigned Identity」で Key Vault にアクセスしようとして失敗する

つまり、Identity の割り当て状態 と Key Vault 参照が使う Identity は独立した設定であり、
前者を変更しても後者は自動追従しない。

なぜ分かりにくいか

• az webapp identity show では type: UserAssigned と正しく表示される
• ロール割り当ても正しい
• Key Vault のシークレットも存在する
• ローカルから同じパスワードで DB 接続できる
• ポータルの環境変数画面でのみ Identity: System assigned managed identity と表示される

CLI やポータルの Identity ブレードだけ見ていると、正しく切り替わったように見えるのが厄介。

解決策

# User Assigned Identity のリソースIDを指定して keyVaultReferenceIdentity を切り替える
az webapp update \
  --resource-group <RESOURCE_GROUP> \
  --name <APP_NAME> \
  --set "keyVaultReferenceIdentity=/subscriptions/<SUB_ID>/resourcegroups/<RG>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IDENTITY_NAME>"

設定後、App Service を stop → start して Key Vault 参照が正常に解決されることを確認。

教訓

1. Iacを採用するか最初からUserAssignedを使う

System Assigned → User Assigned の切り替えは keyVaultReferenceIdentity の罠がある。
最初から User Assigned で構成すれば、この問題は発生しない。

2. 確認方法

# keyVaultReferenceIdentity の現在値を確認
az webapp show --resource-group <RG> --name <APP> --query keyVaultReferenceIdentity -o tsv

SystemAssigned と返ってきたら、User Assigned のリソース ID に変更が必要。

参考

• Azure App Service の Key Vault 参照で User Assigned Managed Identity を使う