Azure SDK documentation update: [AutoPR @azure-arm-msi]-generated-from-SDK Generation - JS-6319430 は、Azure SDK for JavaScript の管理プレーンパッケージ @azure/arm-msi を、Managed Identity API 2025-05-31-preview に合わせて生成更新した内容です。結論から言うと、すぐに本番環境の安定版を置き換える更新ではなく、ユーザー割り当てマネージド ID、Federated Identity Credential、Managed Identity の管理処理を JavaScript/TypeScript から操作している開発者・管理者が、β版として検証すべき更新です。PR は 2026年5月20日に main へマージされ、GitHub Releases では @azure/arm-msi_2.3.0-beta.1 が Pre-release として掲載されています。(GitHub)
Azure SDK documentation updateで何が変わったのか
今回の更新は、Azure SDK 全体の大規模変更というより、JavaScript/TypeScript 向けの @azure/arm-msi に関する SDK 生成更新です。対象は Azure Managed Service Identity、つまり Managed Identity を管理するための SDK です。
重要なのは、これが「アプリが Managed Identity で Key Vault や Storage に接続する認証処理そのもの」を直接変える更新ではない点です。影響を受けやすいのは、@azure/arm-msi を使って、ユーザー割り当てマネージド ID の作成・更新・削除、Federated Identity Credential の作成・取得・削除などを自動化している管理コードです。
| 項目 | 内容 | 実務上の見方 |
|---|---|---|
| 対象パッケージ | @azure/arm-msi | Managed Identity の管理プレーンSDK |
| 更新バージョン | 2.3.0-beta.1 | 本番標準ではなくβ版として検証 |
| API Version | 2025-05-31-preview | preview API のため仕様変更に注意 |
| SpecRepo | Azure/azure-rest-api-specs | REST API仕様からSDKを再生成 |
| 生成元設定 | specification/msi/resource-manager/Microsoft.ManagedIdentity/ManagedIdentity | Managed Identity リソース管理が対象 |
| ランタイム要件 | Node.js >=20.0.0 | CI/CDやローカル環境のNodeバージョン確認が必要 |
tsp-location.yaml では、生成元が Azure/azure-rest-api-specs の ManagedIdentity 仕様で、CommitSHA が 04e1bf1293607d05faacc008c84d64a9bb3f3338 と示されています。また metadata.json では Microsoft.ManagedIdentity の API バージョンが 2025-05-31-preview とされています。(GitHub)
安定版ではなくβ版として扱うべき理由
GitHub Releases では @azure/arm-msi_2.3.0-beta.1 が Pre-release として公開されています。一方、Microsoft Learn の JavaScript 用 Azure SDK ライブラリ一覧では、リソース管理 – マネージドサービスアイデンティティの npm バージョンとして 2.2.0 が表示されています。つまり、記事執筆時点では「安定版の通常更新」と「β版の検証対象」を分けて考える必要があります。(GitHub)
本番環境で @azure/arm-msi を使っている場合、いきなり 2.3.0-beta.1 に上げるのではなく、開発環境または検証用サブスクリプションで動作確認を行うのが安全です。特に preview API を使う機能は、リージョン、クラウド環境、Azure側の提供状況によって挙動が変わる可能性があります。
主な変更点
新しい型とプロパティが追加された
CHANGELOG.md では、2.3.0-beta.1 の追加内容として、AssignmentRestrictions、ClaimsMatchingExpression、FederatedIdentityCredentialProperties、SystemAssignedIdentityProperties、UserAssignedIdentityProperties などのインターフェイス追加が記録されています。また、FederatedIdentityCredential に claimsMatchingExpression、Identity と IdentityUpdate に assignmentRestrictions が任意パラメーターとして追加されています。(GitHub)
実務上、特に注目すべきなのは次の2つです。
assignmentRestrictionsclaimsMatchingExpression
assignmentRestrictions は、ユーザー割り当てマネージド ID をどのリソースプロバイダーやリソース種別に割り当てられるか制限するためのプロパティです。Microsoft Learn の ARM/Bicep リファレンスでも、Microsoft.ManagedIdentity/userAssignedIdentities@2025-05-31-preview に assignmentRestrictions.providers が含まれており、例として Microsoft.Compute、Microsoft.Storage/Accounts、Microsoft.Network/VirtualNetworks などが示されています。(Microsoft Learn)
claimsMatchingExpression は、Federated Identity Credential でより柔軟なクレーム条件を扱うための要素です。SDKのβ版サンプルでは、claims['sub'] に対するマッチ条件を使う Flexible Federated Identity Credential の例が追加されています。(GitHub)
パッケージ構成がModular寄りになった
package.json では、@azure/arm-msi のバージョンが 2.3.0-beta.1 となり、Node.js >=20.0.0 が要求されています。また、./api、./api/userAssignedIdentities、./api/federatedIdentityCredentials、./api/systemAssignedIdentities、./api/operations、./models などのサブパスエクスポートが定義されています。依存関係には @azure-rest/core-client、@azure/core-rest-pipeline、@azure/core-auth、@azure/logger などが含まれています。(GitHub)
通常の利用では、従来どおり次のように ManagedServiceIdentityClient を使う形が基本です。
import { ManagedServiceIdentityClient } from "@azure/arm-msi";
import { DefaultAzureCredential } from "@azure/identity";
const client = new ManagedServiceIdentityClient(
new DefaultAzureCredential(),
subscriptionId
);ただし、過去に dist 配下や生成された内部ファイル、古い operation interface を直接 import していたコードは注意が必要です。公開されたエクスポートではなく内部パスに依存していると、生成方式の変更でビルドが壊れる可能性があります。
影響を受ける人・受けにくい人
| 対象者・システム | 影響度 | 確認すべきこと |
|---|---|---|
@azure/arm-msi でユーザー割り当てマネージド ID を作成・更新している開発者 | 高 | 2.3.0-beta.1で型、戻り値、ビルド結果を確認 |
| Federated Identity Credential をSDKで管理しているDevOps担当者 | 高 | claimsMatchingExpression、FIC上限、issuer/subjectの条件を確認 |
Bicep/ARM/Terraform AzAPIで 2025-05-31-preview を使う管理者 | 中 | assignmentRestrictions と isolationScope の扱いを確認 |
DefaultAzureCredential でAzureリソースに接続しているだけのアプリ開発者 | 低 | @azure/identity 側の更新ではないため直接影響は限定的 |
| 他言語のAzure SDK利用者 | 低〜中 | 各言語のManaged Identity管理SDK更新を個別に確認 |
この更新は「Managed Identityを使って認証するアプリ」よりも、「Managed Identityを作る・更新する・Federated Identity Credentialを設定する自動化コード」に近い領域です。ここを混同すると、不要な移行作業を始めてしまうことがあります。
管理者が確認すべき設定ポイント
assignmentRestrictionsを使う場合は割り当て先を具体的に決める
assignmentRestrictions.providers は、ユーザー割り当てマネージド ID を割り当てられるリソースプロバイダーを制限する用途です。たとえば、Compute系のワークロードだけに使わせたいなら Microsoft.Compute、特定のストレージアカウント種別に絞りたいなら Microsoft.Storage/Accounts のような指定が候補になります。
ただし、制限を強くしすぎると、VM、App Service、AKS、Functions など実際に利用するサービスへの割り当てが失敗する可能性があります。導入時は、次の順で確認すると安全です。
| 確認項目 | 実務での判断基準 |
|---|---|
| 対象リソースプロバイダー | 実際にIDを割り当てるサービスだけを列挙する |
| 検証環境での割り当て | VM、App Service、AKSなど対象サービスで実際に割り当てを試す |
| Azure Policyとの関係 | 既存のポリシーやRBACと矛盾しないか確認する |
| 障害時の切り戻し | assignmentRestrictions 未設定の既存構成に戻せる手順を用意する |
セキュリティ強化のために便利な機能ですが、「どのサービスに割り当てるか」を棚卸しせずに導入すると、デプロイ時のエラー原因になりやすい点に注意してください。
Federated Identity CredentialはUAMI前提で確認する
Microsoft Learn では、ユーザー割り当てマネージド ID に Federated Identity Credential を構成できる一方、システム割り当てマネージド ID への構成はサポートされないと説明されています。また、アプリケーションまたはユーザー割り当てマネージド ID に追加できる Federated Identity Credential は最大20個とされています。(Microsoft Learn)
GitHub Actions、AKS、外部IdP、オンプレミスKubernetesなどからワークロードID連携を使う場合は、次の点を必ず確認してください。
| 確認項目 | 注意点 |
|---|---|
| issuer | 外部IdPが発行するトークンのissuerと完全に一致させる |
| subject | ワークロード単位で十分に限定する |
| audiences | 想定するトークン交換用途に限定する |
| claimsMatchingExpression | 対象範囲を広げすぎない |
| FIC数 | 20個上限に近い場合は設計を見直す |
| 権限 | 作成・更新権限を持つ担当者を限定する |
特に claimsMatchingExpression は便利ですが、条件を広くしすぎると「想定していないワークロードも信頼してしまう」リスクがあります。ワイルドカード的な条件を使う場合は、トークンの sub、iss、aud をログや検証用環境で確認してから展開するべきです。
開発者が確認すべき移行ポイント
Node.js 20以上を前提にCI/CDを見直す
@azure/arm-msi の 2.3.0-beta.1 は package.json 上で Node.js >=20.0.0 を要求しています。ローカルでは動いても、CI/CDのNodeが18系や16系のままだと、インストールやテストで失敗する可能性があります。(GitHub)
まずは次を確認してください。
node -v
npm ls @azure/arm-msiGitHub Actionsを使っている場合は、たとえば次のようにNode 20系を指定します。
- uses: actions/setup-node@v4
with:
node-version: 20β版はバージョン固定で検証する
検証時は、曖昧なバージョン指定を避けます。
npm install @azure/[email protected] @azure/identitypackage.json でも、検証フェーズでは ^2.3.0-beta.1 のように広げるより、まずは厳密なバージョンで固定する方が安全です。β版では、次のβ版や正式版で型名、オプション、サンプル、生成コードの形が変わる可能性があります。
内部パスimportを使っていないか確認する
以下のようなimportをしている場合は要注意です。
// 避けたい例
import { ... } from "@azure/arm-msi/dist/...";
import { ... } from "@azure/arm-msi/src/...";基本は、パッケージの公開エクスポートからimportします。
import { ManagedServiceIdentityClient } from "@azure/arm-msi";今回のパッケージでは ./api や ./models などのサブパスエクスポートも定義されていますが、使う場合は package.json の exports に含まれる範囲に限定するのが安全です。(GitHub)
展開前のチェックリスト
本番展開前には、次の順で確認すると失敗を減らせます。
| チェック | 確認内容 | 未確認の場合のリスク |
|---|---|---|
| パッケージバージョン | @azure/[email protected] を明示指定しているか | 意図しないβ版・正式版へ更新される |
| Node.js | CI/CD、ローカル、コンテナがNode 20以上か | ビルド・テスト失敗 |
| TypeScript型 | tsc --noEmit が通るか | 型変更による実行前エラー |
| import経路 | 内部パスではなく公開APIからimportしているか | 生成構成変更で壊れる |
| FIC設定 | issuer、subject、audiences、式の範囲が適切か | 想定外ワークロードの信頼 |
| FIC上限 | 20個上限に近づいていないか | 追加設定に失敗 |
| assignmentRestrictions | 必要なリソースプロバイダーを許可しているか | ID割り当て失敗 |
| RBAC | 作成・更新・割り当て権限が最小限か | 権限過多または操作失敗 |
| 切り戻し | 既存の安定版 2.2.0 に戻せるか | 障害時の復旧遅延 |
よくある誤解
Azure SDK全体をすぐ更新しなければならないわけではない
今回の対象は @azure/arm-msi です。Azure SDK for JavaScript の全パッケージや、@azure/identity の認証挙動が一括で変わるわけではありません。
Managed Identityの利用アプリがすべて影響を受けるわけではない
アプリケーションが DefaultAzureCredential を使ってKey VaultやStorageにアクセスしているだけなら、今回の変更による直接影響は限定的です。影響が大きいのは、Managed Identityリソースそのものを作成・更新する管理コードです。
claimsMatchingExpressionは便利だが慎重に扱うべき
claimsMatchingExpression は、Federated Identity Credential の柔軟性を高める可能性があります。ただし、subjectを厳密に固定する従来方式よりも、条件設定のミスがセキュリティ境界に影響しやすくなります。GitHub ActionsやKubernetesのサービスアカウントを対象にする場合は、対象リポジトリ、ブランチ、namespace、service account の粒度で信頼範囲を確認してください。
まず何をすべきか
この Azure SDK documentation update を受けて、最初にやるべきことは明確です。@azure/arm-msi を使っていないなら、急いで対応する必要はありません。使っている場合は、現在のバージョン、Node.jsバージョン、import経路、Federated Identity Credentialやユーザー割り当てマネージド ID の自動化処理を確認してください。
特に、次のいずれかに当てはまるチームは、検証用ブランチで @azure/[email protected] を試す価値があります。
- Federated Identity Credential をSDKで作成・更新している
- ユーザー割り当てマネージド ID の作成をCI/CDで自動化している
2025-05-31-previewの Managed Identity API を評価したいassignmentRestrictionsによる割り当て制限を検討している- Node.js 20以降への移行を進めている
一方、本番環境では、安定版 2.2.0 とβ版 2.3.0-beta.1 を混同しないことが重要です。まず検証環境で型チェック、サンプル実行、実リソースへの作成・更新テストを行い、問題がなければ限定的な管理処理から段階的に展開してください。
コメント