midPoint における名寄せ処理

[midPoint by OpenStandia Advent Calendar 2024](https://qiita.com/advent-calendar/2024/midpoint-by-openstandia) の10日目は、[5日目](https://qiita.com/wadahiro/items/a239a743af5404a7325f)で設定した[リソース設定のCorrelation設定（名寄せ設定）](https://qiita.com/wadahiro/items/a239a743af5404a7325f#correlation%E3%81%AE%E8%A8%AD%E5%AE%9A)について、補足します。

:::note info
5日目までで構築した環境が前提となります。
:::

# 名寄のための設定

設定のポイントは以下の2点です。

- リソースの「Correlationの設定」で、名寄せルールを設定する（参考： [5日目のCorrelationの設定](https://qiita.com/wadahiro/items/a239a743af5404a7325f#correlation%E3%81%AE%E8%A8%AD%E5%AE%9A)）
- リソースの「同期の設定」で、状況が`Unlinked`時のアクションを設定する（参考： [5日目の同期の設定](https://qiita.com/wadahiro/items/a239a743af5404a7325f#%E5%90%8C%E6%9C%9F%E3%81%AE%E8%A8%AD%E5%AE%9A)）

1つ目の設定で、名寄せ対象のデータをどういうロジックで探し出すか定義します。

2つ目の設定では、名寄せ対象のデータを発見した際に、実行するアクションを設定します。通常、名寄対象を発見した際には同期を行うようにしたいケースが多いので、5日目の記事では **「紐づけ（Link）」** というアクションを指定していました。要件に合わせて別のアクションを設定することも可能です。

# 名寄せのシナリオを試す

以下のシナリオを試してみます。

1. HRシステムからユーザー情報が連携される前に、諸事情により先行してIGA/IDM側に手動でユーザー登録を実施した
2. その後、HRシステムから正式なユーザー情報が連携されたので、名寄せを行いHRシステムのデータで更新をかけたい

:::note info
その他のシナリオとして、複数の源泉システムからデータを取り込み、midPoint上の同一ユーザーに反映するといったことも考えられます。例えば、電話番号やメールアドレスはHRシステムから連携されず、別システムで割り当てが行われ、そこからデータが連携されるなどです。
:::


# 手動によるユーザー登録

5日目では以下のユーザーCSVを取り込んでいました。

```csvs:users.csv
employeeNumber,givenName,familyName,email,primaryOrgId,secondaryOrgIds
1001,太郎,山田,taro.yamada@example.com,005,006;007
1002,花子,佐藤,hanako.sato@example.com,006,005;009
1003,次郎,鈴木,jiro.suzuki@example.com,007,006
1004,美咲,高橋,misaki.takahashi@example.com,008,009
1005,健一,田中,kenichi.tanaka@example.com,009,008
1006,陽菜,伊藤,hina.ito@example.com,005,
1007,翔,渡辺,sho.watanabe@example.com,006,
1008,さくら,小林,sakura.kobayashi@example.com,007,
1009,優,中村,yu.nakamura@example.com,008,005;007
1010,一郎,山本,ichiro.yamamoto@example.com,009,006
```

ここにまだ存在しない、`1011`を手動で追加します。画面左メニューより「ユーザー ＞ 新規ユーザー」をクリックします。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/2cd249fe-0779-5959-9f6c-7c819506c516.png)

種類は、「すべてのユーザー」を選択します。

:::note info
アーキタイプを使ってユーザー種別を別途定義しておくと、そのユーザー種別を表示させて、種別ごとに異なる作成画面を提供できるようになります。「Person」というアーキタイプがデフォルトで設定されているので、ここではPersonを選ぶことができます。
:::

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/7aa988ae-cf42-3e06-d9ee-ab6e5da66025.png)

新規ユーザー画面が開くので、以下の情報を入力して保存します。メールアドレスや所属組織はHRから後日来るものとして、ここでは未設定としておきます。

- **名前**：`1011`
- **名**：`太郎`
- **姓**：`鈴木`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/1c465ba9-8827-4750-6caf-47b0746fede9.png)


# HRシステムからの同期で名寄せして更新

CSVに、`1011,太郎,鈴木,taro.suzuki@example.com,009,`行を追加します。

```csvs:users.csv
employeeNumber,givenName,familyName,email,primaryOrgId,secondaryOrgIds
1001,太郎,山田,taro.yamada@example.com,005,006;007
1002,花子,佐藤,hanako.sato@example.com,006,005;009
1003,次郎,鈴木,jiro.suzuki@example.com,007,006
1004,美咲,高橋,misaki.takahashi@example.com,008,009
1005,健一,田中,kenichi.tanaka@example.com,009,008
1006,陽菜,伊藤,hina.ito@example.com,005,
1007,翔,渡辺,sho.watanabe@example.com,006,
1008,さくら,小林,sakura.kobayashi@example.com,007,
1009,優,中村,yu.nakamura@example.com,008,005;007
1010,一郎,山本,ichiro.yamamoto@example.com,009,006
1011,太郎,鈴木,taro.suzuki@example.com,009,
```

これで取り込みのタスクを実行します。タスク実行完了後、タスクの「オペレーション統計」メニューを開くと、「Synchronization situation transitions」のところに、`Unlinked`が`Linked`になったものが1件あると示されています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/6a94a9df-86a7-5160-e90a-0f62e447b4ab.png)


ユーザー一覧を確認してみます。手動登録していた`1011`にメールアドレスが設定されていることが分かります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/82804b89-fa40-7982-20f5-60f17ef631f7.png)

詳細を開くと、所属組織も反映されていることが分かります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/d5c1575e-b90f-14bb-f4fb-e52cedf86144.png)


:::note warn
もし、リソースの同期設定で**状況が`Unlinked`時のアクション設定をせずに**インポートタスクを実行すると、CSVから`1011`のユーザー情報は取り込まれず、更新は行われません。タスクの「オペレーション統計」メニューを開くと、Correlation設定により名寄せを行い状況が`Unlinked`のものを検知したが、対応する同期のアクション設定がないため、何も行われていないことが示されています（`Unlinked`のまま終了）。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/df60aaf5-8973-6d12-e51a-9a3aa5f40cc0.png)

逆に、リソースの**Correlation設定をせずに**インポートタスクを実行すると、タスクは「部分的なエラー」で終了します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/e26c858f-d843-1aec-2490-dc09d4794e46.png)

タスクの「オペレーション統計」メニューを開くと、名寄せを行っていないため`Unlinked`は検出されず、`Unmatched`と判定されています。そして「失敗」としてカウントされていることが分かります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/6b9ad689-c9d3-c286-f465-91043316318d.png)

状況が`Unmatched`の場合は、midPointに新規追加を行うアクション（フォーカスを追加）を設定しているため、midPointにユーザーの登録が発生します。しかし今回、`1011`は先行して画面から登録済みであり、そしてname属性はユニークチェックが行われますので、`1011`は重複しエラーとなっています。タスクの「エラー」メニューを開くとこのエラーについて記録されていることが分かります。このように、名寄せ設定を行っていないと同一のユーザーかどうか判断できないため、エラーとなります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/71ab109d-cd33-66e6-24ed-18b0a1a9eac3.png)
:::

# プロビジョニング時の名寄せ

今回は源泉からmidPointに取り込む際の名寄せ処理でしたが、プロビジョニング時の名寄せ処理も存在します。例えば、プロビジョニング先となる連携先システム側において、同名のユーザーが管理者操作により先に登録されてしまったケースです。

その他、まだ連携先としては繋がっていない既存システムを、midPointからのプロビジョニング先に新たに加えるというケースでも、既にアカウントなどが存在しますので名寄せ処理が必要になります。

プロビジョニングの設定については今後の記事で紹介する予定ですので、その際にプロビジョニング時の名寄せの挙動についても紹介できればと思います。


# 高度な名寄せ

設定の詳細については今回は割愛しますが、より複雑な名寄せ処理を実装することも可能です。

今回は`employeeNumber`で名寄せを行うというシンプルなものでしたが、他の属性を利用したり、複数の属性を組み合わせて名寄せすることもできます。以下のドキュメントに詳細情報が記載されています。

https://docs.evolveum.com/midpoint/reference/support-4.8/correlation/

また、名寄せでマッチングしたユーザーが複数存在する場合に、ワークフローを起動して管理者によるマニュアル判定させることも可能です。以下は例として「姓」だけで名寄せした場合に、名寄せ候補が二人見つかった場合のマニュアル作業の画面です。管理者が判断してどれを紐付けるか決定します。このようなマニュアル操作と組み合わせた名寄せ処理も、midPointでは実装することができます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/35233/facbcf4b-3811-da6d-286c-d0ac7c6d8f72.png)


# まとめ

10日目では、[5日目](https://qiita.com/wadahiro/items/a239a743af5404a7325f)で設定した[リソース設定のCorrelation設定（名寄せ設定）](https://qiita.com/wadahiro/items/a239a743af5404a7325f#correlation%E3%81%AE%E8%A8%AD%E5%AE%9A)について、補足解説しました。実際の現場では、この名寄せが中々難しくて検討に時間がかかることがありますが、ロジックさえうまく決まれば、midPointの名寄せ機能を使ってスマートに対応できる可能性があります。是非活用していただければと思います。

次回はいよいよ、プロビジョニング設定を追加予定です。お楽しみに！