midPointにおける「IDライフサイクル管理」実践編（CSV/画面からの取り込み）



# はじめに

今回は、前回の[記事](https://qiita.com/tama1/items/e4ea135aa43a9222fb71)の続きとして、IDライフサイクル管理を体験するための設定を行って行きたいと思います。

midPoint をインストールした状態では、ユーザー（ID）がまだ登録されていません。初期データとして人事システムなどの他のシステムからアカウントを取り込む必要があります。**実践編**では、すぐに試せるように midPoint に付属しているサンプルを元にCSVファイルからアカウントをまとめて取り込む手順を説明させて頂きます。

また、midPoint は、**GUI(画面)** でユーザーを登録する機能もありますので、後半はそちらも紹介したいと思います。

# 源泉(CSV)からのデータ取り込み

midPoint のユーザーを人事システムなどの**源泉データ**から取り込む場合、midPointに接続しているシステムは**リソース**と呼び、リソースとの接続は**コネクタ**と呼ばれるモジュールで行います。

今回は源泉データであるCSVファイルをmidPointに取り込む設定を行います。midPointの[ライブデモ](https://wiki.evolveum.com/display/midPoint/Live+Demo#LiveDemo-SituationandRequirements)にある下図でいえば左側の`CSV File`、`HR Feed`の部分の設定を行って行こうと思います。
`CSV File`、`HR Feed`が**リソース**、`CSV File`、`HR Feed`をつなぐ矢印が**コネクタ**にあたります。データの取得先であるこのリソースを**ターゲットリソース**とします。

![electra-deployment.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/01c0aec1-11ba-67a0-e67a-bc599b1f8cf3.png)

図の引用元:[Live Demo](https://wiki.evolveum.com/display/midPoint/Live+Demo#LiveDemo-SituationandRequirements)

実際に源泉データの取り込み設定を行う前に、midPoint上でデータがどのように扱われているかについて軽く解説します。詳細はPDFのBook [Practical Identity Management with MidPoint](https://evolveum.com/midpoint/midpoint-guide-about-practical-identity-management/) が公開されていますので、ご参照ください。

### midPointのオブジェクト

midPont では、リソースのデータを取り込むために**リソースオブジェクト**、**リソースオブジェクトシャドウ**、**フォーカスオブジェクト**というオブジェクトを使用します。それぞれ以下のようになります。

- **リソースオブジェクト**
　取り込み対象のターゲットリソースにあるアカウント情報です。midPoint 内部ではオブジェクトとして扱われるため、リソースオブジェクトと呼ばれます。**プロジェクション**とも呼ばれます。

- **リソースオブジェクトシャドウ**
　midPoint内のオブジェクトと、リソースオブジェクトとのデータ形式の違いを吸収する役割を持つオブジェクトです。ターゲットリソースにアカウントが追加されると、midPoint 上にそれに対応するシャドウオブジェクトが作成され、ターゲットリソースのアカウント情報が変更されると、対応するシャドウオブジェクトも更新されます。**シャドウオブジェクト**、**シャドウ**とも呼ばれます。

- **フォーカスオブジェクト**
   midPoint のユーザー一覧に表示されるユーザーの本体である User オブジェクトを指します。**フォーカスオブジェクト**または**フォーカス**と呼ばれます。ターゲットリソースから取り込まれるとシャドウとフォーカスは**リンク**されます。

![focus-projection-3.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/8008c6b1-beeb-a6bb-e9fd-8832d5fe70da.png)

図の引用元:[Focus and Projections](https://wiki.evolveum.com/display/midPoint/Focus+and+Projections)
:notebook:シャドウオブジェクトについて:[Shadow Objects](https://wiki.evolveum.com/display/midPoint/Shadow+Objects)
:notebook:フォーカスとプロジェクション:[Focus and Projections](https://wiki.evolveum.com/display/midPoint/Focus+and+Projections)

図中の**Inbound**、**Outboud** はそれぞれ以下のようになります。

- **インバウンド（Inbound）**
　インバウンドは、リソース側のシャドウ（アカウントなど）からmidPoint側のフォーカス（Userなど）にデータを変換するための[マッピング設定](https://wiki.evolveum.com/display/midPoint/Mapping)です。

- **アウトバウンド（Outbound）**
　アウトバウンド（Outbound）は、インバウンドとは逆にmidPoint側のフォーカスからリソース側のシャドウにデータを変換するための[マッピング設定](https://wiki.evolveum.com/display/midPoint/Mapping)です。

:notebook: [User](https://wiki.evolveum.com/display/midPoint/UserType) 以外に [Role](https://wiki.evolveum.com/display/midPoint/RoleType)、[Organization](https://wiki.evolveum.com/display/midPoint/OrgType)、[Service](https://wiki.evolveum.com/display/midPoint/Services) オブジェクトもフォーカスとして機能します。

### CSVを取り込むための設定

CSVを取り込むための設定である**リソース定義**は、midPoint に付属しているサンプルを元にします。サンプルは midPont のインストールディレクトリの下の `doc/samples/`に用意されています。使用するファイルは以下です。

| ファイル                               | 内容                                                         |
| :------------------------------------- | :----------------------------------------------------------- |
| doc/samples/book/5/resource-csv-hr.xml | ターゲットリソースからデータを取り込むための設定が書かれている**リソース定義**ファイルです。|
| doc/samples/book/5/hr.csv              | ターゲットリソースである CSV 形式の源泉データです。  |

:information_source: github 上ではサンプルは midPoint 本体とは[別プロジェクト](https://github.com/Evolveum/midpoint-samples)なっています。付属しているサンプルが動かない場合はこちらが最新なのでチェックしてみてください。

### リソース定義の取り込み

リソース定義のインポート画面を開いて`組み込みエディタ`を選択します。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/8ec4314a-42bc-5199-aaa7-ecd145c85e65.png" width="50%" alt="リソース定義1">

エディタの編集フォームが開きますので、`resource-csv-hr.xml`の内容をまるごとコピー＆ペーストします。

![image008.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/2f0c854a-528b-e07d-62f7-53212540ad9a.png)

`オブジェクトのインポート`ボタンを押して設定を取り込みます。

![image011.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/83863939-be00-3e8d-d3ad-54db73c3b94d.png)

最初の状態ではユーザー一覧には`administrator`しかいません。

![image014.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/3c3f3b7f-3055-b92f-93d2-773fb5d43e65.png)


リソース一覧には`HR System`の定義が取り込まれていますので`HR System`をクリックして詳細画面を開きます。

![image017.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/28fed32f-e0c9-1178-123a-844ccec98e8a.png)


`リソースの状態が不明`と表示されていますので`ウィザードを使用して編集`ボタンを押して設定を確認します。

![image021.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/b4eb7c3c-8727-e176-a9c9-befc6a7c9dd7.png)


最初の画面は変更する必要が無いので`次`ボタンを押して次の画面に行きます。

![image024.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/6cffe7d5-84d1-b955-53d0-d75088135569.png)

`File path` の項目を実際に csv ファイルがあるパスに変更して`保存と接続テスト`ボタンを押してテストを行います。

![image028.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/d453253d-d3d7-7c84-7f88-436a954218ea.png)

接続テスト結果ウィンドウが開いてテストが始まります。全て緑になれば成功です。

![image033.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/d6414d83-097f-a413-a797-6d395e4f8265.png)

`完了`ボタンを押して前の画面に戻ると、`リソースは起動しています`というメッセージに変わっているはずです。

![image036.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/1a48d074-4c84-76bd-b595-920d3612979a.png)


`アカウント`タブ、`リソース`ボタンを押すとターゲットリソースにあるアカウントの一覧が表示されます。これでリソースの設定が完了しました。

![image042.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/0b4a0f78-1883-6334-90fb-3caae8e75534.png)


### アカウントのインポート

源泉データであるCSVファイルのアカウント一覧から midPoint にユーザーを取り込んでみましょう。源泉データのインポートはタスクにより自動化できますが今回は手動で行います。

`リソース`の`アカウント`一覧の中からインポートしたいアカウントの右側にある`▼`から`インポート`を選択してインポート出来ます。

![image047.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/6af87038-308e-5ebc-cfc1-df2a86b69a71.png)

### アカウントをまとめてインポート

先頭行の`名前`の左側のチェックボックスをチェックすると、表示されている全てのアカウントのチェックボックスがチェックされます。その状態で先頭行の右側の`▼`でインポートするとまとめてインポートされます。

![image052.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/9bfc86f6-9e6e-9dab-57f8-c42771a2d197.png)


インポートが終わり`すべてのユーザー`画面を開くとユーザーがインポートされていることが確認できます。


![image056.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/851dec82-c618-a4e4-dfdb-1a3cb6ca9543.png)

### リソース定義

リソース定義ファイル `resource-csv-hr.xml` には、これらの処理を行うための各種設定がなされています。主な設定内容を紹介します。詳細は midPoint の Wiki をご参照ください。

| タグ | 説明 |
|:--------|:-------------------------------------|
|&lt;name&gt;|リソースの名前を設定します。サンプルでは HR System になっています。|
|&lt;connectorRef&gt;|リソースと接続するためのコネクタの設定です。サンプルではCSVのデータの読み書きを行える com.evolveum.polygon.connector.csv.CsvConnector が指定してあります。|
|&lt;connectorConfiguration&gt;|コネクタの各種設定を記述します。|
|&lt;schemaHandling&gt;|CSVのどの項目をどのように反映させるか、インバウンドの設定を記述します。サンプルでは empno 項目をフォーカスオブジェクトのname項目と employeeNumber の両方に反映させる設定になっています。|
|&lt;synchronization &gt;|ターゲットリソースのアカウントと、どのように同期するかを設定を記述します。今回の例では手動でアカウントのインポートを行いましたが、タスク機能を使用することで自動的に同期させることが出来ます。|

:notebook: コネクタの設定:[Connector Setup](https://wiki.evolveum.com/display/midPoint/Connector+Setup)
:notebook: 各種コネクタについて:[Identity Connectors](https://wiki.evolveum.com/display/midPoint/Identity+Connectors)
:notebook: リソース設定:[Resource Configuration](https://wiki.evolveum.com/display/midPoint/Resource+Configuration)
:notebook: インバウンドマッピング設定:[Inbound Mapping](https://wiki.evolveum.com/display/midPoint/Inbound+Mapping)
:notebook: User に設定できる項目について: [UserType](https://wiki.evolveum.com/display/midPoint/UserType)
:notebook: 同期設定:[Synchronization Configuration](https://wiki.evolveum.com/display/midPoint/Synchronization+Configuration)
:notebook: Expression:[Expression](https://wiki.evolveum.com/display/midPoint/Expression)

:information_source:前の記事 [midPointにおける「IDライフサイクル管理」を解説する](https://qiita.com/tama1/private/e4ea135aa43a9222fb71) では、CSV ファイルに Eメールアドレスの項目 email を追加し、リソース定義の、&lt;schemaHandling&gt; に以下のようなインバウンド設定を追加しました。

```xml
<attribute>
    <ref>ri:email</ref>
    <displayName>Email Address</displayName>
    <inbound>
        <target>
            <path>$focus/emailAddress</path>
        </target>
    </inbound>
</attribute>
```
:information_source:サンプルの &lt;credentials&gt; 設定では初期パスワードを自動生成するようになっているので、CSVのパスワードをそのまま使う場合は &lt;expression&gt; の&lt;generate/&gt; を &lt;asIs/&gt;に変更して下さい。

```xml
<credentials>
    <password>
        <inbound>
            <strength>weak</strength>
            <expression>
                <asIs/>
            </expression>
        </inbound>
    </password>
</credentials>
```

:information_source:サンプルの設定で取り込んだユーザーがログインするためには`End User`ロールの付与が必要です。自動的に付与するためには別途設定が必要になります。:notebook: [Automatic Role Assignment HOWTO](https://wiki.evolveum.com/display/midPoint/Automatic+Role+Assignment+HOWTO)


# 画面からのユーザー登録

CSVファイルのような元となる源泉データが無い場合は、midPoint の画面から直接ユーザーを登録することが出来ます。

## 基本情報を入力する

管理者 `Administrator` でログイン、メニューの`ユーザー`、`新規ユーザー` より`新規ユーザー作成`画面を開きます。入力項目が大量にありますが、全部入れなくてもいいので必要な項目を入力していきます。

![image004.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/e80d6ec2-ce0e-d8a4-e903-748cae7ee00e.png)

###プロパティー

入力可能な項目は以下になります。midPoint のユーザーを一意に識別するための`名前`以外は全てオプション扱いになっているので、必要に応じて使用することになります。

|項目名(英語名)|内容|
| ------ | ------ |
|名前(Name)|User を一意に識別するための文字列、これだけは**必須**です。|
|説明(Description)|説明などがあれば記入します。|
|サブタイプ(Subtype)|プロジェクト、チームが異なっている場合など、ユーザーの種類を区別する必要がある場合に記入します。|
|ライフサイクル状態(Lifecycle state)|オブジェクトの状態（ドラフト、アクティブ、非推奨など）を記入します。|
|氏名(Full name)|氏名を記入します。**通常は使用することになると思います。**|
|名(Given name)|名を記入します。**通常は使用することになると思います。**|
|姓(Family name)|姓を記入します。**通常は使用することになると思います。**|
|追加名（ミドルネーム）(Additional Name)|ミドルネームを記入します。|
|ニックネーム(Nickname)|ニックネームを記入します。|
|敬称接頭語(Honorific Prefix)|名前の前にある敬称、キャプテン・・・、など|
|敬称接尾語(Honorific Suffix)|名前の後ろにある敬称、・・・教授、など|
|タイトル(Title)|タイトルを記入します。|
|優先言語(Preferred Language)|多言語で使用する場合に優先する言語を記入します。|
|ロケール(Locale)|多言語で使用する場合のロケールを記入します。|
|タイムゾーン(Timezone)|タイムゾーンを記入します。|
|テナント(Tenant)|テナントを記入します。|
|Eメール(Email)|Eメールアドレスを記入します。**通常は使用することになると思います。**これを設定しないとEメールによる各種**通知**ができません。|
|電話番号(Telephone number)|電話番号を記入します。|
|従業員番号(Employee Number)|従業員番号を記入します。|
|コストセンター(Cost Center)|必要に応じて記入します。|
|組織(Organization)|組織、会社名などを記入します。|
|所属組織(Organizational Unit)|組織、部署名などを記入します。|
|地域(Locality)|組織の地域などを記入します。|
|JPEG写真(Jpeg photo)|ユーザーの写真をアップロードします。|

###アクティベーション

ユーザーの有効期限やパスワードロックを設定します。必要に応じて使用します。

|項目名(英語名)|内容|
| ------ | ------ |
|管理ステータス(Administrative status)|有効、無効、アーカイブ済などのIDの状態を設定します。|
|開始日時(Valid from)|有効期限の開始日を設定します。|
|終了日時(Valid to)|有効期限の終了日を設定します。|
|ロックアウト・ステータス(Lock-out Status)|ログイン失敗回数によるアカウントロックが有効化されていて、該当ユーザーがアカウントロックされていた場合は「ロックされています」と表示されます。「通常に設定」ボタンでロックを解除できます。|
|ロックアウトの有効期限(Lock-out Expiration)|ロックされたアカウントが有効になるまでの期限を設定します。|

###パスワード

パスワードも必須ではありませんが、**これを設定しないと midPoint にログインできず、他システムとの連携も難しいため**、通常は設定することになると思います。

|項目名|内容|
| ------ | ------ |
|パスワード|パスワードを入力します。|
|パスワードを再入力|確認用にパスワードを再度入力します。|

ここでは必要最低限の項目のみ入れます。`名前`、`名`、`姓`、`Eメール`、`パスワード`を入力して`保存`ボタンを押すととりあえずユーザーの登録が完了します。緑の帯が表示されれば成功です。しかし、まだユーザーのアイコンが黒くなっています。

![image007.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/e7da5fd3-dfcd-672e-949b-867b085abeff.png)

##ロールを追加する

次に必要最低限のロールを設定します。登録したユーザーの`名前`をクリックし、詳細画面を開き`アサイン`タブをクリックします。

![image010.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/19c5d651-65ed-4bb2-d282-42d5a9a8dcf4.png)

チェックボックスの下の `新規割り当て` ボタンを押すとロールの選択画面が開きます。

![image013.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/170f9f16-3cf0-76f9-f30e-ff24abdb785e.png)

`End User`をチェックして`追加`ボタンを押します。

![image018.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/afa81b07-907b-3c8b-858e-961d26b290f3.png)

:information_source:デフォルトの状態では、以下のようなロールが用意されています。

|ロール|説明|
| ----- | ---------- |
|Approver|アクセス認定の承認者用のロールです。|
|Delegator|アクセス認定で承認を行う権限を他のユーザーに委譲することを許可するロールです。|
|End user|ログイン、パスワードの変更を許可する基本的なロールです。|
|Reviewer|アクセス認定のレビュワー用のロールです。|
|Superuser|administrator などの midPoint の管理者用のロールです。|


ロールの選択画面が閉じると、先ほど選択したロールが薄い緑色で表示されていますので、`保存`ボタンを押します。

![image021.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/38f1d168-f677-626a-8211-7a7b414687aa.png)

緑の帯が表示されれば成功です。登録したユーザーのアイコンが青くなりログインできるようになりました。

![image023.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/bb792623-f455-e90e-7a37-67cb590ad47e.png)














##まとめ
midPoint は用意されている多くのサンプルを使用することで動作を確認することが出来ます。リソース定義用の GUI も用意されていますが、現状ではまだ発展途上の部分も多く、サンプルのXMLをベースにカスタマイズする方が近道だと思いました。この辺りは今後の改良に期待したいと思います。

##付録1: 参考URL

https://www.youtube.com/channel/UCSDs8qBlv7MgRKRLu1rU_FQ
Evolveum社の Youtubeチャンネルです。いくつかデモ動画がアップされています。やや古いバージョン 3.6 を使っていますが、イメージはつかめると思います。

##付録2: midPointの内部処理

midPoint では ID　はオブジェクトとして扱われています。オブジェクトはIDライフサイクルを制御する特別なプロパティLifecycleStateを持っており、以下のような値を取ります。

![schemas-lifecycle-statechart.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/227018/87911d7f-0fe3-fa62-deae-42db9327e426.png)

引用元:[Object Lifecycle](https://wiki.evolveum.com/display/midPoint/Object+Lifecycle)

|状態|アクティブ|説明|
|:--|---|:--|
|ドラフト(Draft)|no|IDは、まだ準備ができておらず、変更される可能性があります。|
|提案済み(Proposed)|no|IDの定義は完了していますが、まだレビュー（承認など）がされていません。|
|アクティブ(Active)|YES|IDは有効であり、使用可能な状態です。|
|非推奨(Deprecated)|YES|まだ使用可能ですが、段階的に廃止される予定であるため新たに使用（承認）すべきではありません。|
|アーカイブ済み(Archived)|no|既に使用できない状態であり、履歴として確認するためにのみ存在しています。|
|失敗(Failed)|no|ライフサイクル中に予期しないエラーが発生しています。オブジェクトは非アクティブになり、手動での対応が必要です。|

**アクティブ**列は、オブジェクトが有効かどうかです。noの場合は非アクティブ（無効またはアーカイブ済み）な状態です。通常は lifecycleState や有効期限などから自動的にアクティブにすべきかどうか決定されますが、特別な理由で管理者が判断する必要がある場合は、以下の管理ステータスで明示的に決定することもできます。

|値|説明|
|:--|:--|
|値なし|明示的な決定はなされていません|
|enabled|アクティブな状態|
|disabled|非アクティブな状態。後で有効にする場合に指定します。育児休業中、休暇中、セキュリティ上の理由など、一時的にアカウントを無効にする場合に使用します。|
|archived|非アクティブな状態。後で有効化されることはありません。従業員が退職した場合などに使用します。|


参考：
[Object Lifecycle](https://wiki.evolveum.com/display/midPoint/Object+Lifecycle)
[Activation](https://wiki.evolveum.com/display/midPoint/Activation)