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

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

.. _config directory:

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

.. _file or directory configurtion:

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

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 の設定ファイルです。
    uWSGI の設定を変更する場合にはこちらのファイルを編集してください。

.. _unicornidm.conf:

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

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

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

.. _uwsgi.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
------------

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

.. _templates:

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

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

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

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

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

.. _secrets:

secrets/
--------

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



.. _log files:

ログの場所
==========

Unicorn ID Manager のログは ``/opt/osstech/var/log/unicornidm/`` 配下に出力されます。

以下の3つのファイルがあります。

.. envvar:: unicornidm.log

    メインのログファイルです。

.. envvar:: uwsgi.log

    uWSGI のログファイルです。
    **Unicorn ID Manager の設定ミス時には原因がこのファイルに出力されます。**
    また、開発者の予期しないエラーが発生した場合にはこのファイルにスタックトレースが出力される場合があります。

.. envvar:: mongod.log

    Unicorn ID Manager が内部で使っているデータベースである MongoDB のログファイルです。
    通常このファイルを見る必要はありません。


.. _Administrators and Roles:

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

.. _Administrator manage:

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

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` の *管理者に関する操作*
をご覧ください。

.. _Role manage:

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

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` の *ロールに関する操作*
をご覧ください。

.. _manage from web browser:

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: ログイン画面
    :align: center
    :width: 40%

    ログイン画面

.. _dashboard:

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

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

.. figure:: img/02-dashboard.png
    :alt: ダッシュボード画面
    :align: center
    :width: 40%

    ダッシュボード画面

.. _user or group list view:

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

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

.. _user list view:

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

.. figure:: img/03-user-list.png
    :alt: ユーザー一覧画面
    :align: center
    :width: 40%

    ユーザー一覧画面

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

* ダッシュボード画面

* グループ一覧画面

* 結果画面

* ユーザー登録画面

* 一括処理画面

* 個別のユーザー画面

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

* 自動生成されたパスワード一覧を取得（一定期間内のもののみ）

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

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

* 検索

* ログアウト

.. _group list view:

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

.. figure:: img/04-group-list.png
    :alt: グループ一覧画面
    :align: center
    :width: 40%

    グループ一覧画面


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

* ダッシュボード画面

* ユーザー一覧画面

* 結果画面

* グループ登録画面

* 一括処理画面

* 個別のグループ画面

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

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

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

* 検索

* ログアウト

.. _user or group view:

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

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

.. _user view:

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

* ユーザー更新

* ユーザー有効化

* ユーザー無効化

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

* ユーザー削除

.. _group view:

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

* グループ更新

* グループ削除

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

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

これらの画面は以下のようになっています。

.. figure:: img/resource-detail.png
    :alt: ユーザー詳細画面
    :align: center
    :width: 70%

    ユーザー詳細画面

グレー色で表示されている属性の説明などの設定方法については :ref:`attribute-names-descriptions` をご覧ください。

.. _result view:

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

結果画面には以下のニ種類があります。
どちらも検索、表示順の変更に対応しています。

.. figure:: img/05-result-submissions.png
    :alt: 結果サマリー画面
    :align: center
    :width: 80%

    結果画面


.. figure:: img/06-result-operations.png
    :alt: 結果詳細画面
    :align: center
    :width: 80%

    結果画面

.. _manage operations:

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

.. _manage opration user:

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

.. _manage opration user add:

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

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

.. _manage opration user modify:

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

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

.. _manage opration user enable:

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

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

.. _manage opration user disable:

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

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

.. _manage opration user delete:

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

ユーザーを削除します。

.. _manage opration user change password:

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

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

.. _manage opration user rename:

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

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

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

.. _manage opration group:

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

.. _manage opration group add:

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

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

.. _manage opration group modify:

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

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

.. _manage opration group delete:

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

グループを削除します。

.. _manage opration group rename:

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

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

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

.. _manage opration group add members:

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

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

.. _manage opration group delete members:

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

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

.. _bulk csv format:

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

.. _bulk csv header:

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

.. _bulk csv header upper or lower case:

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

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

.. _bulk csv empty cell:

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

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

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

例::

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

.. _bulk csv miltivalue:

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

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 を混在させることはできません。

.. _bulk csv format manage members:

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

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

::

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

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

.. _bulk csv format rename:

名前変更時
-------------------------------

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

ユーザーのリネーム::

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

グループのリネーム::

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

.. _bulk csv format change password:

パスワード変更時のCSVフォーマット
---------------------------------

.. code-block:: none

    userName,password
    user1,newpassword
    user2,
    user3,#random#

``password`` カラムで指定されたパスワードに変更しようとします。
パスワードが空の場合にはパスワード変更は行われません（上記例3行目）。

``#random`` の場合にはランダムパスワード生成規則に基づいてパスワードを自動生成します（上記例4行目）。
自動生成されたパスワードは
*unicornidm-tool user getpassword* コマンドで取得してください。

.. _bulk csv format manage group:

ユーザー登録、更新時に所属グループを変更する際のフォーマット
------------------------------------------------------------

CSVによるユーザー登録、更新時に操作対象ユーザーの所属グループも変更したい場合には、 ``backend-name.groups`` 特殊属性を使用してください。
名前が ``x`` であるバックエンドが存在する場合に、 ``x.groups`` とCSVヘッダーに書き、その値にグループ名を ``,`` （カンマ）区切りで列挙することで、それらのグループに対するメンバー追加、削除をユーザー登録、更新と同時に行うことができます。

この特殊属性は、他の複数値属性のように値の数だけCSVヘッダー部に同じ属性名を書く必要がない点にご注意ください。代わりにCSVの同じ列に ``,`` 区切りで複数の値を記入します。
この際 ``,`` 区切りのグループ名のリストは各グループ名がCSVの別カラムとして解釈されないように ``"`` などで囲む必要があります。

.. _bulk csv format manage group when user add:

ユーザー登録時
^^^^^^^^^^^^^^

``backend-name.groups`` にグループ名を列挙すると、登録するユーザーをそれらのグループに対してメンバーとして追加する処理がユーザー登録の直後に実行されます。

.. _bulk csv format manage group when user modify:

ユーザー更新時
^^^^^^^^^^^^^^

ユーザー更新時のグループメンバーへの追加・削除は ``+`` , ``-`` 接頭辞を ``backend-name.groups`` ヘッダーに付与することで表現します。
``+backend-name.groups`` に書いたグループでは更新対象ユーザーがメンバーとして追加されます。
``-backend-name.groups`` に書いたグループでは更新対象ユーザーがメンバーから削除されます。

この2つの接頭辞は、1つのCSVファイル内で同時に使うことが可能です。

なお、 ``--`` 接頭辞は使用できません。

.. _manage for restriction Administrator:

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

管理者の操作は :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
    - グループのリネーム
