Microsoft Entra 属性マッピングを運用している管理者が最初に確認すべきポイントは、Application Provisioning の「式（Expression）」に関する制限が明確化されたことです。公式リポジトリでは 2026年5月22日表示のコミットで「Update App Provisioning Expressions Limits」として更新され、単一の属性マッピング式でサポートされる最大長が 10,000文字 と追記されています。日本時間では2026年5月23日前後の確認対象として扱うとよい更新です。(GitHub)
これは「今すぐ全テナントで設定変更が必要」という種類の告知ではありません。ただし、Microsoft Entra Application Provisioning で SaaS アプリへのユーザー作成・更新・ロール同期・SCIM カスタム属性を使っている環境では、長い式、照合属性、カスタムスキーマ、既定マッピングの復元操作を確認しておくべきです。属性マッピングは、Microsoft Entra ID とターゲットアプリケーション間でどの属性値を流すかを決める中核設定であり、既定マッピングの変更・削除・新規作成ができます。(Microsoft Learn)
Microsoft Entra 属性マッピング更新の要点
今回の実務上の変更点は、Microsoft Entra 属性マッピングの設計で使う「式」の上限が明文化されたことです。公式の差分では、対象ドキュメントに「1つの属性マッピング式でサポートされる最大長は10,000文字」という注記が追加されています。(GitHub)
| 確認項目 | 内容 | 管理者・開発者への影響 |
|---|---|---|
| 式の最大長 | 単一の属性マッピング式は最大10,000文字まで | 複雑な Switch、IIF、文字列変換を1つの式に詰め込んでいる環境は棚卸しが必要 |
| 影響対象 | Microsoft Entra Application Provisioning の属性マッピング | SaaSアプリ、SCIMアプリ、ロール同期、カスタム属性連携が主な確認対象 |
| 直ちに必要な対応 | 既存設定が自動変更されるとは示されていない | ただし、長大な式や属人化したマッピングは早めに見直すべき |
| 注意すべき操作 | 既定マッピングの復元、照合属性の変更、SCIM属性リスト編集 | 誤ると再同期、重複ユーザー、属性欠落、ロール残留につながる |
特に、退職者処理、部署別ロール、外部SaaSの権限制御を属性マッピングに依存している企業では、これは単なるドキュメント更新ではなく、IDライフサイクル管理の設計を見直すきっかけになります。
Microsoft Entra 属性マッピングとは何か
Microsoft Entra 属性マッピングは、Microsoft Entra ID のユーザー属性を、Salesforce、ServiceNow、Google Workspace、SCIM対応アプリなどのターゲットアプリにどのように渡すかを定義する設定です。Microsoft Entra ID では、非Microsoft SaaSアプリに対するユーザープロビジョニングをサポートしており、プロビジョニングを有効にすると、属性値は属性マッピングによって制御されます。(Microsoft Learn)
たとえば、Microsoft Entra ID の userPrincipalName を Salesforce 側の Username に渡す、department をSaaS側の部署項目に渡す、appRoleAssignments をSCIMアプリの roles に変換して送る、といった用途で使われます。
属性マッピングの4つの種類
Microsoft Entra の属性マッピングでは、主に次の4種類を使い分けます。(Microsoft Learn)
| 種類 | 使い方 | 実務での例 |
|---|---|---|
| Direct | ソース属性の値をそのままターゲット属性に渡す | mail を SaaS側のメールアドレスに同期 |
| Constant | 固定文字列をターゲット属性に渡す | 全ユーザーの organization に固定値を入れる |
| Expression | 式の結果をターゲット属性に渡す | 氏名の整形、ドメイン変換、ロール情報の変換 |
| None | ターゲット属性を変更しない | アプリ側で管理したい属性をMicrosoft Entraから上書きしない |
今回の更新で特に関係するのは Expression です。式は便利ですが、条件分岐や文字列加工を積み重ねすぎると、保守しにくくなり、今回明記された10,000文字上限にも近づきます。
影響範囲：確認すべき環境と優先度
Microsoft Entra 属性マッピングの更新は、すべてのMicrosoft Entraテナントに同じ深刻度で影響するわけではありません。SSOだけを使っていてプロビジョニングを有効にしていないアプリは、基本的に影響は小さいです。一方で、自動プロビジョニングを使ってユーザー・グループ・ロール・カスタム属性を同期している環境は確認が必要です。
| 対象環境 | 優先度 | 確認すべき理由 |
|---|---|---|
| Expression型の属性マッピングを多用しているSaaSアプリ | 高 | 式の10,000文字上限、変換ロジックの複雑化、同期失敗リスクを確認するため |
| SCIM対応のカスタムアプリ | 高 | カスタム属性、複数値属性、ロール属性、PATCH動作の設計が影響しやすいため |
| 既存ユーザーがいるアプリへ後からプロビジョニングを導入した環境 | 高 | 照合属性の選び方を誤ると、重複作成や別ユーザーへの誤マッチが起きるため |
| グループプロビジョニングを使うアプリ | 中 | グループ割り当てとグループオブジェクトのプロビジョニングは別概念のため |
| 既定マッピングの復元を検討しているアプリ | 高 | 復元時にすべてのユーザーの再同期が強制されるため |
| SSOのみ利用し、プロビジョニング未設定のアプリ | 低 | 属性マッピングの変更対象外であることが多いため |
Microsoftの説明では、属性マッピングの更新は同期サイクルのパフォーマンスに影響し、構成更新後はすべての管理対象オブジェクトの再評価が必要になります。連続的な変更は最小限に抑えることが推奨されています。(Microsoft Learn)
管理者が確認すべき設定
属性マッピング画面へのアクセス権限
属性マッピングを確認するには、少なくともアプリケーション管理者として Microsoft Entra 管理センターにサインインし、Entra ID、Enterprise アプリケーション、対象アプリ、プロビジョニング、Mappings の順に進みます。Microsoft Learnでは、この画面からユーザー属性や、ターゲットアプリが対応している場合はグループ属性の流れを表示・編集できると説明されています。(Microsoft Learn)
確認時は、いきなり保存せず、まず現在の設定を記録してください。可能であれば、スキーマのJSON表現を確認・ダウンロードし、変更前後を比較できる状態にしておくと安全です。Microsoft Learnでも、管理画面に加えてスキーマのJSON表現を確認・ダウンロード・編集できることが説明されています。(Microsoft Learn)
必須属性を不用意に変えない
SaaSアプリには、正常動作のために必要な属性マッピングがあります。必須属性では削除機能を使用できないとされていますが、「削除できないから安全」という意味ではありません。ソース属性や式を変更すれば、ターゲットアプリ側でユーザー名、メールアドレス、表示名、ロールが想定と異なる値になる可能性があります。(Microsoft Learn)
たとえば、userPrincipalName をユーザー名として使っているアプリで、途中から mail に切り替えると、既存アカウントとの照合に影響することがあります。特に、メールアドレスが未設定のユーザー、ゲストユーザー、旧ドメインを持つユーザーが混在する環境では注意が必要です。
Create のチェックは既存ユーザーに影響しないが、新規作成に影響する
属性マッピング画面では、作成・更新時の動作を制御できます。Microsoft Learnでは、Create をオフにしても既存ユーザーには影響しない一方、Create が選択されていない場合は新しいユーザーを作成できないと説明されています。(Microsoft Learn)
移行時に「既存ユーザーだけ同期したい」と考えて Create を外すケースがありますが、運用開始後に新入社員がターゲットSaaSに作成されない原因になりやすい設定です。検証時には、既存ユーザーの更新だけでなく、新規ユーザーの作成も必ず試してください。
開発者が確認すべき設計ポイント
式を10,000文字に近づけない
今回の更新で、単一の属性マッピング式の最大サポート長は10,000文字と明記されました。長大な式は、上限に達していなくても保守性の面で問題があります。(GitHub)
避けたい設計は、次のようなものです。
- 部署コード、勤務地、雇用形態、役職をすべて1つの
Switch式で判定する - 例外ユーザーを式の中に個別列挙する
- SaaSごとに似た式をコピーし、少しずつ変更して使い回す
- 退職者、休職者、外部委託先の判定まで属性マッピング式に詰め込む
おすすめは、Microsoft Entra の属性マッピングに複雑な業務ロジックを持たせすぎないことです。人事システム、ID管理基盤、オンプレミスAD、Microsoft Entra ID の拡張属性などで値を事前に整え、Application Provisioning ではできるだけ Direct または短い Expression で渡す設計にすると、変更時の影響範囲が読みやすくなります。
照合属性は「一意性」と「ターゲット側のフィルター対応」を確認する
Microsoft Entra プロビジョニングサービスは、ターゲットシステムにユーザーがいない新規導入と、既存ユーザーがいる環境の両方をサポートします。そのために重要なのが照合属性です。Microsoft Learnでは、userPrincipalName、mail、オブジェクトIDなどが照合属性として使われる例が示されています。複数の照合属性を設定した場合は優先順位の順に評価され、一致が見つかると後続の属性は評価されません。(Microsoft Learn)
注意すべきなのは、属性の組み合わせによる照合はサポートされない点です。たとえば「姓＋社員番号」「メール＋会社コード」の組み合わせで一意にしたい、という設計はそのままでは使えません。また、ターゲットアプリのAPIがその属性でフィルター検索できることも必要です。(Microsoft Learn)
実務では、次の観点で確認します。
| 確認項目 | 判断基準 |
|---|---|
| 一意性 | 同じ値を持つユーザーがいないか |
| 値の存在 | 同期対象ユーザー全員が少なくとも1つの照合属性を持っているか |
| 変更頻度 | 結婚、異動、ドメイン変更で値が変わりやすくないか |
| ターゲットAPI対応 | SaaS側APIがその属性で検索・フィルターできるか |
| 既存アカウントとの整合 | すでにあるSaaS側ユーザーと正しく一致するか |
既存SaaSに後から自動プロビジョニングを入れる場合、最初に失敗しやすいのはここです。同期対象を小さく絞り、代表ユーザー、例外ユーザー、外部ユーザー、退職予定ユーザーで確認してから範囲を広げるべきです。
SCIMカスタム属性を使う場合の注意点
SCIM対応アプリにカスタム属性を追加する場合、Microsoft Learnでは Show advanced options から属性リストを編集し、必要に応じてスキーマエディターを有効化する手順が説明されています。Edit attribute list for AppName が表示されない場合は、指定URLでスキーマエディターを有効化する必要があります。(Microsoft Learn)
SCIMアプリでは、カスタム属性名は次のような名前空間パターンに従う必要があります。
urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:CustomAttribute一方で、ServiceNow や Salesforce のようにSCIMを使って Microsoft Entra ID と統合されていないアプリでは、このSCIM名前空間は不要と説明されています。カスタム属性を参照属性、複数値、複合型の属性にすることはできず、カスタムの複数値・複合型の拡張属性はギャラリー内アプリケーションに対してのみサポートされるとされています。(Microsoft Learn)
ディレクトリ拡張属性は大文字・小文字を厳密に扱う
Microsoft Entra ID のディレクトリ拡張属性がドロップダウンに出ない場合、属性一覧に手動追加できます。ただし、ディレクトリ拡張属性名は大文字と小文字を区別します。さらに、複数値のディレクトリ拡張属性のプロビジョニングはサポートされていません。(Microsoft Learn)
たとえば、実際の属性名が次のように定義されている場合、
extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenterAcmeCostCenter や acmecostcenter のように大小文字を変えて登録すると、意図した値が流れない可能性があります。属性名はコピー＆ペーストで登録し、変更履歴にも残しておくのが安全です。
ロールプロビジョニングの確認ポイント
アプリケーションロールをSCIMアプリへプロビジョニングする場合、appRoleAssignment をロール属性へ直接マッピングしてはいけません。Microsoft Learnでは、ロールの詳細を解析するために式を使って変換する必要があると説明されています。(Microsoft Learn)
ロール連携で使われる代表的な式は次の3つです。
| 式 | 用途 | 注意点 |
|---|---|---|
SingleAppRoleAssignment | 1人のユーザーに単一ロールを渡す | 複数ロールが割り当てられていると、どのロールがプロビジョニングされるか保証されない |
AppRoleAssignmentsComplex | 複数ロールを渡す | PATCH add の動作では、ターゲット側に残ったロールを削除できない場合がある |
AssertiveAppRoleAssignmentsComplex | 複雑なロールでPATCH replaceを使いたい場合 | Microsoft Entra ID側で外れたロールをターゲット側からも削除しやすいが、スコープ設定との互換性に注意 |
AssertiveAppRoleAssignmentsComplex は、SCIMアプリが複数ロールをサポートし、PATCH Replace機能を使える場合に、Microsoft Entra IDで外れたロールをターゲットアプリからも削除する用途に向いています。一方、AppRoleAssignmentsComplex はPATCH addのみで、既存ロールを削除しない違いがあります。(Microsoft Learn)
ロールはアクセス権そのものに直結します。属性マッピングの中でも、セキュリティ影響が大きい設定です。特に「管理者ロールを外したのにSaaS側に残る」「複数ロールのうち想定外のロールが優先される」といった事故を防ぐため、ロール削除時の挙動まで検証してください。
グループ割り当てとグループプロビジョニングを混同しない
Microsoft Learnでは、グループオブジェクトのプロビジョニングと、アプリケーションへのグループ割り当ては別の概念だと説明されています。アプリにグループを割り当てても、プロビジョニングされるのはグループ内のユーザーだけであり、割り当てにグループを使うためにグループオブジェクト全体のプロビジョニングが必須というわけではありません。(Microsoft Learn)
この違いを誤解すると、次のようなトラブルが起きます。
| 誤解 | 実際に起きること |
|---|---|
| グループを割り当てればSaaS側にもグループが作られると思っている | ユーザーだけが同期され、SaaS側グループは作られない場合がある |
| グループプロビジョニングを無効にすればユーザー同期も止まると思っている | グループオブジェクト同期とユーザー同期は別管理 |
| グループ名やメールエイリアスも自動で揃うと思っている | ターゲットアプリがグループ属性プロビジョニングに対応している必要がある |
権限管理にグループを使う場合は、「アプリへの割り当てに使うグループ」と「SaaS側に作成・更新したいグループ」を分けて設計すると、後からのトラブルを避けやすくなります。
移行・展開前のチェックリスト
Microsoft Entra 属性マッピングを変更する前に、次のチェックリストを使って影響範囲を整理してください。
| フェーズ | 確認項目 | 失敗しやすいポイント |
|---|---|---|
| 棚卸し | プロビジョニング有効アプリ、Expression型マッピング、ロールマッピング、SCIMカスタム属性を一覧化 | 古いギャラリーアプリや退職者処理用アプリを見落とす |
| 設計 | 照合属性、一意性、ターゲットAPIのフィルター対応を確認 | mail 未設定ユーザーや重複メールを見落とす |
| 式の見直し | 10,000文字に近い式、複雑な条件分岐、属人化した式を確認 | 例外処理を式に追加し続けて保守不能になる |
| カスタム属性 | 属性名、型、必須、複数値、大文字小文字を確認 | SCIM名前空間や拡張属性名の大小文字を誤る |
| ロール同期 | 単一ロールか複数ロールか、削除時の挙動を確認 | SaaS側に不要なロールが残る |
| 展開 | 変更単位を小さくし、検証ユーザーで確認 | 複数変更を同時に入れて原因切り分けができない |
| 復元・切り戻し | 変更前のJSON、スクリーンショット、設定値を保存 | 既定マッピング復元でスコープフィルターまで戻る |
既定マッピングを復元する場合は特に注意が必要です。Microsoft Learnでは、既定マッピングの復元により、ギャラリーからアプリを追加したかのようにすべてのマッピングとスコープフィルターが設定され、プロビジョニングサービス実行中はすべてのユーザーの再同期が強制されると説明されています。また、この操作前にプロビジョニング状態をオフにすることが強く推奨されています。(Microsoft Learn)
設定確認の具体的な手順
- Microsoft Entra 管理センターに、少なくともアプリケーション管理者としてサインインします。
Entra ID、Enterprise アプリケーションの順に開きます。- 対象のSaaSアプリまたはSCIMアプリを選択します。
プロビジョニングを開き、Mappingsを展開します。Provision Microsoft Entra ID Usersなど、対象オブジェクトのマッピングを開きます。- 各属性について、次の項目を確認します。
- マッピング種類が Direct、Constant、Expression、None のどれか
- Source attribute と Target attribute が正しいか
Match objects using this attributeが有効な属性は何か- 照合の優先順位が妥当か
Apply this mappingが「常に」か「作成中のみ」か- Expression型の式が長すぎないか
- SCIMカスタム属性を使う場合は、
Show advanced optionsから属性リストを確認します。 - ロール同期を使う場合は、
appRoleAssignmentを直接マッピングしていないか、式で変換しているかを確認します。 - 変更前の設定を保存し、検証ユーザーで作成・更新・無効化・ロール削除まで確認します。
- 本番展開時は、変更をまとめすぎず、ログを見ながら段階的に広げます。
よくある失敗と回避策
null値が同期されると思っている
Microsoft Entra プロビジョニングサービスでは、null値のプロビジョニングはサポートされていません。Default value if null はありますが、これはユーザー作成時にのみプロビジョニングされ、既存ユーザー更新時には適用されません。(Microsoft Learn)
回避策は、ソース側で値を補完するか、作成時と更新時の要件を分けて設計することです。たとえば、役職が空のユーザーに初期値を入れたい場合でも、既存ユーザーの更新に同じ期待を持つと失敗します。
IsSoftDeleted を外して退職者処理が崩れる
IsSoftDeleted は、多くのアプリの既定マッピングに含まれます。この属性は、アプリから未割り当てになった、スコープフィルター外になった、Microsoft Entra IDで論理削除された、AccountEnabled が false になった、といったシナリオで true になることがあります。Microsoft Learnでは、属性マッピングで IsSoftDeleted を維持するよう推奨しています。(Microsoft Learn)
退職者や休職者のSaaSアカウント停止をプロビジョニングに任せている場合、この属性を安易に削除・変更しないでください。
主キーをターゲット属性に含める
主キー、一般的には ID は、属性マッピングのターゲット属性に含めるべきではありません。Microsoft Learnでも、主キーをターゲット属性として含めないよう説明されています。(Microsoft Learn)
ターゲットアプリ側のIDは、通常そのアプリが管理します。Microsoft Entra側から上書きしようとすると、更新失敗や重複、参照不整合につながります。
写真属性を追加しようとする
Microsoft Learnでは、写真を同期する形式を指定できないため、アプリへプロビジョニングする写真属性の追加は現在サポートされていないと説明されています。(Microsoft Learn)
プロフィール写真を同期したい場合は、Application Provisioning の属性マッピングだけで実現しようとせず、対象SaaSのAPI、専用コネクタ、別の同期手段を検討する必要があります。
管理者と開発者の分担
Microsoft Entra 属性マッピングは、管理者だけでも開発者だけでも安全に設計しにくい領域です。SaaSのAPI仕様、SCIMの属性設計、ID運用、退職者処理、監査要件が交差するため、役割を分けて確認すると抜け漏れが減ります。
| 役割 | 主な確認範囲 |
|---|---|
| Microsoft Entra管理者 | エンタープライズアプリ、プロビジョニング範囲、割り当て、スコープフィルター、照合属性、変更計画 |
| ID管理担当 | 社員番号、メール、UPN、部署、雇用形態などの正規データ |
| SaaS管理者 | ターゲットアプリ側の必須属性、ユーザー名仕様、ロール仕様、グループ仕様 |
| 開発者 | SCIMエンドポイント、属性スキーマ、フィルター対応、PATCH/POST処理、複数値属性の扱い |
| セキュリティ担当 | 退職者無効化、ロール削除、過剰権限、監査ログ、変更承認 |
特にSCIMカスタムアプリでは、ターゲットアプリが照合属性でフィルターできるか、ロール削除時にPATCH replaceを正しく処理できるか、複数ロールの表現がMicrosoft Entra側の式と合っているかを開発者が確認する必要があります。
次に取るべき対応
Microsoft Entra 属性マッピングを使っている場合、まずは本番設定を変更するのではなく、棚卸しから始めてください。
優先して確認すべき順番は次の通りです。
- プロビジョニング有効なエンタープライズアプリを一覧化する
- Expression型の属性マッピングを抽出し、長さと内容を確認する
- 照合属性が一意で、ターゲットAPIでフィルター可能か確認する
- SCIMカスタム属性の名前、型、大文字小文字、複数値対応を確認する
- ロールマッピングが直接マッピングではなく、適切な式で変換されているか確認する
IsSoftDeleted、null値、主キー、写真属性などの注意点を見直す- 変更前のJSONやスクリーンショットを保存し、検証ユーザーで段階的に展開する
今回の更新は、派手な機能追加ではありません。しかし、Microsoft Entra Application Provisioning の属性マッピングは、ユーザー作成、更新、無効化、ロール付与に直結します。式の上限が明確になった今、長くなりすぎた式や属人化したマッピングを整理し、誰が見ても判断できる設定にしておくことが、次の障害や権限事故を防ぐ最も現実的な対策です。
コメント