管理ガイド
*************

ここでは Unicorn ID Manager を管理するための情報を説明いたします。
前提として、 Unicorn ID Manager は **/opt/osstech** をプレフィックスとする環境にインストール
されていることを前提として説明いたします。

設定ディレクトリー
====================

ファイル/ディレクトリー構成
----------------------------

Unicorn ID Manager の設定ディレクトリーは **/opt/osstech/etc/unicornidm** です。
このディレクトリー以下のファイル/ディレクトリー構成は以下のとおりです。

::

    .
    ├── secrets/
    ├── templates/
    ├── mongodb.conf
    ├── unicornidm.conf
    └── uwsgi.conf

それぞれのファイル及びディレクトリーの用途は以下のとおりです。

secrets/
    パスワード情報を格納したファイルなどを格納するためのディレクトリーです。
templates/
    バックエンドのテンプレートファイルを格納するためのディレクトリーです。
mongodb.conf
    Unicorn ID Manager のキャッシュ情報を格納する MongoDB の設定ファイルです。
    通常、このファイルを編集する必要はございません。
unicornidm.conf
    Unicorn ID Manager の設定ファイルです。
uwsgi.conf
    Unicorn ID Manager の HTTP サーバーである uWSGI の設定ファイルです。

unicornidm.conf
-----------------

*unicornidm.conf* は Unicorn ID Manager を動作させるために必要な設定ファイルです。

詳細は :doc:`unicornidm-conf` を参照してください。

uwsgi.conf
-----------

*uwsgi.conf* は Unicorn ID Manager の HTTP サーバーである uWSGI の設定ファイルです。
Unicorn ID Manager はそれ単体で HTTP サーバーとして動作しますので、この設定ファイル
が必要になります。

ほとんどの場合、このファイルを編集する必要はありませんが、 Unicorn ID Manager を
リバースプロキシーのバックエンドで動作させるためには以下の修正が必要です。

* chown-socket パラメーターのグループをリバースプロキシーの実行グループに修正

* gid パラメーターをリバースプロキシーの実行グループに修正

* https パラメーターの行を削除 (あるいはコメントアウト)

* http-socket パラメーターを `http-socket = :8081` として追記

    - 8081 は uWSGI がリッスンするポート番号

デフォルトの *uwsgi.conf* に Apache HTTPD のリバースプロキシー配下で動作させるための
設定例がコメントアウトされて記載されています。そちらも参考にしてください。

mongodb.conf
-------------

*mongodb.conf* は Unicorn ID Manager のキャッシュ情報を格納する MongoDB の設定ファイルです。
このファイルを編集する必要はありません。設定パラメーターの詳細については
https://docs.mongodb.org/manual/reference/configuration-options/ をご覧ください。


templates/
-----------

*templates/* は Unicorn ID Manager のバックエンドのテンプレートファイルを
格納するためのディレクトリーです。テンプレートファイルは **<name>.py** というように
必ず末尾が **.py** のファイルで保存する必要があります。
また、テンプレートファイルはそれぞれのバックエンドごとに用意する必要があります。

テンプレートファイルの概要については :doc:`unicornidm-template` を参照してください。

それぞれのバックエンドごとのテンプレートファイルは以下を参照してください。

:doc:`unicornidm-template-ldap`
    ldap バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-samba_ldap`
    samba_ldap バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-ad`
    ad バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-google`
    google バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-azure`
    azure バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-sql`
    sql バックエンドのテンプレートに関するドキュメント
:doc:`unicornidm-template-command`
    command バックエンドのテンプレートに関するドキュメント

secrets/
---------

*secrets/* パスワード情報を格納したファイルなどを格納するためのディレクトリーです。
Unicorn ID Manager としては必ずしも必要なディレクトリーではありません。


管理者とロール
===============

管理者の管理
-------------

Unicorn ID Manager でユーザーやグループを管理するためには
管理者アカウントが必要です。

管理者は :doc:`unicornidm-tool` **admin add** コマンドで作成します。
例えば、以下のようなコマンドで作成できます。

.. code-block:: shell-session

    # unicornidm-tool admin add ADMINISTRATOR_NAME -r SuperAdministrator

**-r** オプションは作成する管理者のロールを指定するためのオプションです。
デフォルトは **SuperViewer** で、このロールはすべてのターゲットにおいて、
ユーザーやグループの参照が可能な役割を持っています (更新はできません) 。
上の例で指定している SuperAdministrator はすべての操作が可能な役割を
有する特別なロールです。

管理者の管理の詳細は :doc:`unicornidm-tool` の *管理者に関する操作*
をご覧ください。

ロールの管理
-------------

Unicorn ID Manager の管理者アカウントには必ずロールが必要です。

システムでは予め以下のロールが定義されています。

SuperAdministrator
    すべてのターゲットに対してすべての管理操作が可能な役割
SuperViewer
    すべてのターゲットに対してユーザーとグループの一覧の参照が可能な役割

この他にも、独自のロールを作成することが可能です。
新しいロールは :doc:`unicornidm-tool` **role add** コマンドで作成します。
例えば、以下のようなコマンドで作成できます。

.. code-block:: shell-session

    # unicornidm-tool role add /path/to/ROLE_FILE

/path/to/ROLE_FILE の内容は以下のような JSON 形式のものです。

::

    {
      "name": "role_name",
      "privileges": [
        {
          "target": "target_name",
          "actions": [
            "user_list",
            "user_change_password"
          ]
        }
      ]
    }

この新しく定義したロールはユーザーの参照とユーザーのパスワードリセットを
行うことができます。

ロールの管理の詳細は :doc:`unicornidm-tool` の *ロールに関する操作*
をご覧ください。


Web ブラウザーからの管理
===========================

Unicorn ID Manager は Web ブラウザーから管理することができます。 Unicorn ID Manager
がインストールされたサーバーのホスト名が unicornidm.example.com の場合、以下の URL
からアクセスしてログインしてください。

.. code-block:: none

    https://unicornidm.example.com/unicornidm/admin/

.. figure:: img/01-login.png
    :alt: ログイン画面

    ログイン画面

ダッシュボード画面
-------------------

ログインをすると、ダッシュボード画面が表示されます。ここで管理しようとしているターゲットを
選択します。なお、あるターゲットに対する何らかの権限がない管理者に対してはそのターゲットが
表示されません。

.. figure:: img/02-dashboard.png
    :alt: ダッシュボード画面

    ダッシュボード画面


ユーザーまたはグループの一覧画面
---------------------------------

ダッシュボード画面からターゲットを選択すると、そのターゲットのユーザー一覧画面が表示されます。

ユーザー一覧画面
^^^^^^^^^^^^^^^^^

.. figure:: img/03-user-list.png
    :alt: ユーザー一覧画面

    ユーザー一覧画面

この画面から以下の画面に遷移することができます。

* ダッシュボード画面

* グループ一覧画面

* 結果画面

* ユーザー登録画面

* 一括処理画面

* 個別のユーザー画面

また、以下の操作を行うことができます。

* 自動生成されたパスワード一覧を取得

* ユーザー一覧を CSV でダウンロード

* バックエンドとの同期 (リフレッシュ)

* 検索

* ログアウト

グループ一覧画面
^^^^^^^^^^^^^^^^^

.. figure:: img/04-group-list.png
    :alt: グループ一覧画面

    グループ一覧画面


この画面から以下の画面に遷移することができます。

* ダッシュボード画面

* ユーザー一覧画面

* 結果画面

* グループ登録画面

* 一括処理画面

* 個別のグループ画面

また、以下の操作を行うことができます。

* グループ一覧を CSV でダウンロード

* バックエンドとの同期 (リフレッシュ)

* 検索

* ログアウト


ユーザーまたはグループの個別画面
---------------------------------

`ユーザーまたはグループの一覧画面`_ から個別画面に遷移すると、ユーザーとグループそれぞれで
以下のような操作を行えます。

ユーザー個別画面
^^^^^^^^^^^^^^^^^

* ユーザー更新

* ユーザー有効化

* ユーザー無効化

* ユーザーのパスワード変更

* ユーザー削除


グループ個別画面
^^^^^^^^^^^^^^^^^

* グループ更新

* グループ削除

* グループへのメンバー追加

* グループからのメンバー削除

結果画面
^^^^^^^^^^^


.. figure:: img/05-result.png
    :alt: 結果画面

    結果画面

結果画面は管理者が行った「登録」や「削除」等の操作結果が実行日時の降順に表示されます。
表示する結果を絞りたい場合は「検索」ボックスで以下のような文字列を入力することで
範囲を絞れます。

after:<日付>
    実行日が **<日付>** 以降の結果を表示します。 **<日付>** は **YYYY-MM-DD** の形式でなければ
    なりません。たとえば、 *after:2015-11-29* と入力します。

before:<日付>
    実行日が **<日付>** 以前の結果を表示します。 **<日付>** は **YYYY-MM-DD** の形式でなければ
    なりません。たとえば、 *before:2015-11-29* と入力します。

ip:<IPアドレス>
    操作実行者の IP アドレスが **<IPアドレス>** と一致する結果を表示します。
    たとえば、 *ip:192.168.0.23* と入力します。

admin:<管理者名>
    操作実行者の名前が **<管理者名>** と一致する結果を表示します。
    たとば、 *admin:test-admin* と入力します。

op:<実行種別>
    操作の実行種別が **<実行種別>** と一致する結果を表示します。
    たとえば、 *op:change_password* と入力します。

is_succeeded:<実行結果>
    操作の実行結果が **<実行結果>** と一致する結果を表示します。
    **<実行結果>** は *true* か *false* を選択します。
    たとえば、 *is_succeeded:false* と入力します。

backend:<バックエンド>
    操作対象が **<バックエンド>** に対する実行結果を表示します。
    たとえば、 *backend:ldap-server* と入力します。

resource_type:<リソースタイプ>
    捜査対象が **リソースタイプ** に対する実行結果を表示します。リソースタイプは
    *User* か *Group* を選択してください。
    たとえば、 *resource_type:Group* と入力します。

検索条件は複数指定できます。複数指定する場合は空白区切りで入力してください。


管理操作一覧
===================

ユーザー
---------

登録 (add)
^^^^^^^^^^^^

ユーザーを新規に登録します。

更新 (modify)
^^^^^^^^^^^^^^^^^

ユーザー情報を更新します。
更新操作でパスワードを変更することはできません。

有効化 (enable)
^^^^^^^^^^^^^^^^^

ユーザーのステータスを有効化します。

無効化 (disable)
^^^^^^^^^^^^^^^^^

ユーザーのステータスを無効化します。

削除 (delete)
^^^^^^^^^^^^^^^^^

ユーザーを削除します。

パスワードリセット (change_password)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ユーザーのパスワードをリセットします。管理者がユーザーのパスワードリセットを
行う場合、設定しているパスワードポリシーのうち、最大文字数及び最小文字数の
パスワードポリシーのみがチェックされます。これは、管理者によるパスワードリセット
を簡便化するための仕様です。

リネーム (rename)
^^^^^^^^^^^^^^^^^^^^

ユーザーのリネームをします。

.. caution::
    リネームを実行する際に一部のバックエンドだけに操作対象を指定した場合、
    リネーム前のユーザーが指定していないバックエンドに存在することになります。
    これにより、 **実質的に** 同一のユーザーが複数存在することになります。

グループ
---------

登録 (add)
^^^^^^^^^^^^

グループを新規に登録します。

更新 (modify)
^^^^^^^^^^^^^^^^^

グループ情報を更新します。

削除 (delete)
^^^^^^^^^^^^^^^^^

グループを削除します。

リネーム (rename)
^^^^^^^^^^^^^^^^^^^^

グループのリネームをします。

.. caution::
    リネームを実行する際に一部のバックエンドだけに操作対象を指定した場合、
    リネーム前のグループが指定していないバックエンドに存在することになります。
    これにより、 **実質的に** 同一のグループが複数存在することになります。


メンバー追加 (add_members)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

グループにメンバーを追加します。

メンバー削除 (delete_members)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

グループからメンバーを削除します。


一括操作のための CSV ファイルのフォーマットについて
=========================================================

CSV ファイルのヘッダーについて
-------------------------------

Unicorn ID Manager はコマンドラインツールか管理画面から一括操作を行うことができます。
CSV ファイルのフォーマットは 1 行目に属性 (フロントエンド属性) のヘッダーを記載し、
2 行目以降に ユーザーやグループそれぞれの属性値を指定します。

例::

    userName,familyName,givenName,password,mail,mail
    user1,User,One,secret,user1@example.com,user1@sub.example.com
    user2,User,Two,secret,user1@example.com,

1 行目の属性名はバックエンドのテンプレート設定によって決められます。
たとえば、あるターゲットに 2 つバックエンドが関連付けられている設定で、
それぞれのバックエンドが以下のテンプレートだとします。

.. code-block:: python

    User = {
        "objectClass": [
            "top",
            "person",
            "organizationalPerson",
            "inetOrgPerson",
            "posixAccount",
        ],
        "uid": userName,
        "cn": userName,
        "uidNumber": default(uidNumber),
        "gidNumber": default(gidNumber, 100),
        "loginShell": default(loginShell, "/bin/bash"),
        "homeDirectory": default(unixHomeDirectory, "/home/%(userName)s"),
        "sn": familyName,
        "givenName": givenName,
        "userPassword": password,
        "mail": mail,
        "description": default(description),
        "displayName": default(displayName, "%(familyName)s %(givenName)s"),
    }

    Group = {
        "objectClass": [
            "top",
            "posixGroup",
            ],
        "cn": groupName,
        "gidNumber": default(gidNumber),
        "description": default(description),
    }

.. code-block:: python

    User = {
        "userPrincipalName": userName,
        "immutableId": default(immutableId),
        "displayName": default(displayName, "%(familyName)s %(givenName)s"),
        "surname": familyName,
        "givenName": givenName,
        "mailNickname": userName,
        "accountEnabled": default(active, True),
        "passwordProfile": {
          "password": password,
          "forceChangePasswordNextLogin": default(forceChangePasswordNextLogin, True),
        },
        "passwordPolicies": "DisablePasswordExpiration,DisableStrongPassword",
        "usageLocation": default(usageLocation, "JP"),
        "assignedLicenses": default(azureLicense),
    }


    Group = {
        "displayName": groupName,
        "mailNickname": groupName,
        "mailEnabled": False,
        "securityEnabled": True,
        "description": default(description),
    }

この設定の場合、たとえば、以下のような CSV ヘッダーが使用可能です。

::

    userName,familyName,givenName,password,mail,immutableId,azureLicense

テンプレートは JSON のような見た目の形式 (Python の dict 型) になっており、
値部分に存在する識別子が属性 (フロントエンド属性) になります。

テンプレートに存在する default(..) というシンタックスは属性がオプション属性
であることを示します。たとえば、 default(active, True) の設定で、 active 属性
が存在していない場合は True が適用されます。また、 default(description) の設定で、
description が存在しない場合、 description は空になります。

上の設定のオプション属性まで含めたすべての属性を含むユーザーの CSV ヘッダーは
以下のようになります (見やすいように改行していますが、CSV ヘッダーは 1 行です) 。

::

    userName,uidNumber,gidNumber,loginShell,unixHomeDirectory,familyName,
    givenName,password,mail,description,displayName,immutableId,active,
    forceChangePasswordNextLogin,usageLocation,azureLicense

CSV ファイルのヘッダーの大文字・小文字
---------------------------------------

CSV ファイルのヘッダーに指定する属性名は大文字と小文字を区別します。

CSV データ部分の空のセルについて
---------------------------------

一括更新の際、 CSV ファイルの空のセルは無視されます。

たとえば以下の場合、 user1 の givenName は更新されません。
同様に、 user2 の description 、 user3 の givenName 及び description は更新されません。

例::

    userName,familyName,givenName,description
    user1,User,,This is user1
    user2,User,Two,
    user3,User

複数値について
---------------

CSV ファイルで複数値を表現するためには、フロントエンド属性を複数ヘッダーに指定します。
なお、複数属性として定義できるフロントエンド属性は :doc:`unicornidm-conf` の
*multi_valued_attributes* で指定されたものに限ります。

例::

    userName,mail,mail,mail
    user1,user1@example.com,user1@sub.example.com,user1@example.jp
    user2,user2@example.com

更新操作の際は以下ののようにフロントエンド属性名の先頭に `+` 、 `-` 、 `--`
を指定することができます。これにより、属性値の追加、属性値の削除、属性値の全削除
が可能です。

部分追加、部分削除の例::

    userName,+mail,-mail
    user1,user1@plus.example.jp,user1@sub.example.com
    user2,user2@p.example.com,

全削除の例 (全削除の場合データ部の指定は空でも全削除される)::

    userName,--mail
    user1
    user2

なお、グループ操作時に「メンバー追加」及び「メンバー削除」する際には
+member と -member を混在させることはできません。

グループにメンバーを追加・削除する際のフォーマット
---------------------------------------------------

グループへのメンバー一括追加・削除の CSV フォーマットは以下のようになります。

::

    groupName,member,member,member
    group1,user1,user2,user3
    group2,user1,
    group3,user1,user2

このように、あるグループに対してはメンバーを 1 人追加/削除する、
あるグループに対してはメンバーを 2 人追加/削除する、などの要求を
1 つの CSV にまとめることができます。

リネームをする際のフォーマット
-------------------------------

ユーザーやグループをリネームする際はそれぞれ以下のフォーマットになります。

ユーザーのリネーム::

    userName,newUserName
    user1,new-user1
    user2,new-user2

グループのリネーム::

    groupName,newGroupName
    group1,new-group1
    group2,new-group2


一覧取得が制限された管理者の操作について
==============================================

管理者の操作は :doc:`unicornidm-tool` で作成するロールによって制限されます。
その際、 **user_list** か **group_list** の操作を許可されていないロールを
割り当てられている管理者は次の URL パスで対象のユーザー名かグループ名を
指定して操作ができます。 TARGET は設定されているターゲット名です。

* /unicornidm/admin/TARGET/Users/_add
    - ユーザーの作成
* /unicornidm/admin/TARGET/Users/_password
    - ユーザーのパスワード変更
* /unicornidm/admin/TARGET/Users/_confirm
    - ユーザーの有効化
    - ユーザーの無効化
    - ユーザーの削除
    - ユーザーの ppolicy アンロック
* /unicornidm/admin/TARGET/Users/_rename
    - ユーザーのリネーム
* /unicornidm/admin/TARGET/Groups/_add
    - グループの作成
* /unicornidm/admin/TARGET/Groups/_confirm
    - グループの削除
* /unicornidm/admin/TARGET/Groups/_rename
    - グループのリネーム
