.. _quickstart:

クイックスタート
******************

ここでは Unicorn ID Manager を設定して起動するところまでの一連の流れを説明いたします。
前提として、 Unicorn ID Manager は **/opt/osstech** をプレフィックスとする環境にインストール
されていることとして説明いたします。また、ここでは LDAP サーバーを
データストア (バックエンド) とする設定を行いますので、予め LDAP サーバーを準備してください。

また、Unicorn ID Managerは基本的にApache HTTP サーバーを前段に配置する構成で利用します。
予め ``httpd`` と ``mod_ssl`` をインストールしておいてください。

HTTPDサーバーのTLS設定にサーバー証明書が必要になります。
Unicorn ID Managerではインストール時に自己証明書の生成を行いますが、
本番サーバーなどでは適切な認証局が発行した証明書を利用するようにしてください。

.. _quickstart unicornidm.conf:

設定ファイルの準備
===================

Unicorn ID Manager の設定ファイル :file:`/opt/osstech/etc/unicornidm/unicornidm.conf` を以下の内容
で編集します。なお、必要であれば、このファイルのバックアップをとってください。

.. code-block:: cfg

    [__main__]
    debug_level                   = INFO
    debug_file                    = /opt/osstech/var/log/unicornidm.log
    targets                       = target1
    session_time_out              = 3600
    password_cache_duration       = 86400
    items_per_page                = 20
    multi_valued_attributes       = mail, phoneNumber, img, photo
    user_viewable_attributes      = userName, familyName, givenName
    group_viewable_attributes     = groupName, description
    allowed_hosts                 = uidm.example.com

    [target:target1]
    backends                                   = ldap1
    displayName                                = ターゲット1
    password_policy_max                        = 100
    password_policy_min                        = 8
    password_policy_upper                      = 1
    password_policy_lower                      = 1
    password_policy_symbol                     = 1
    password_policy_digit                      = 1
    password_policy_complexity                 = 3
    password_policy_prohibited                 =
    password_policy_must_not_contain_name      = yes
    password_policy_must_be_different_from_old = yes
    password_policy_must_be_various            = yes
    password_policy_must_be_disorder           = yes
    password_policy_random_prohibited          = !"#$%%&'()*+,-./:;<=>?@[\]^_`{|}~0DOQ1lI2Z5S6G8B9q
    password_policy_random_length              = 8
    lockout_policy_duration                    = 3600
    lockout_policy_max_failure                 = 3
    lockout_policy_failure_count_interval      = 1800
    self_password_reset                        = no
    self_modify                                = no

    [backend:ldap1]
    type               = ldap
    uris               = ldaps://ldap1.example.com/
    bind_user          = cn=Manager,dc=example,dc=com
    bind_password_file = /opt/osstech/etc/unicornidm/secrets/ldap1-password
    suffix             = dc=example,dc=com
    suffix_user        = ou=Users,%(suffix)s
    suffix_group       = ou=Groups,%(suffix)s
    filter_user        = (&(objectClass=posixAccount)(uid=*))
    filter_group       = (&(objectClass=posixGroup)(cn=*))
    password_hash      = PASSMOD

    [client]
    server_url              = https://localhost/
    admin_name              = tool-admin
    admin_password_file     = /opt/osstech/etc/unicornidm/secrets/tool-admin-password
    uid                     = unicornidm
    gid                     = unicornidm
    timezone                = Asia/Tokyo

.. note::
   ここではUnicorn ID ManagerのFQDNを ``uidm.example.com`` と仮定しています。
   ``arrowed_hosts`` の値は実際の接続に利用するFQDNを設定してください。
   ``arrowed_hosts`` で指定されたホスト名以外では接続できません。


また、 LDAP サーバーへの接続に必要な :file:`/opt/osstech/etc/unicornidm/secrets/ldap1-password`
を準備する必要があります。このファイルの中身は BIND DN のパスワードです。
たとえば、以下のコマンドで作成できます。

.. code-block:: shell-session

    # install -m 0600 -o unicornidm <(echo -n PASSWORD) /opt/osstech/etc/unicornidm/secrets/ldap1-password

.. note::
    ここでは、 LDAP サーバーへの接続情報が以下のとおりであることを前提とします。

    接続先:
        \ldap://ldap1.example.com/
    BIND DN:
        cn=Manager,dc=example,dc=com
    BIND password file:
        /opt/osstech/etc/unicornidm/secrets/ldap1-password
    Suffix:
        dc=example,dc=com
    User Suffix:
        ou=Users,dc=example,dc=com
    Group Suffix:
        ou=Groups,dc=example,dc=com
    User Filter:
        (&(objectClass=posixAccount)(uid=*))
    Group Filter:
        (&(objectClass=posixGroup)(cn=*))

.. warning::
    ここでは Unicorn ID Manager を unicornidm というユーザーで動作させることを
    前提としています。

.. _quickstart templates:

テンプレートファイルの準備
==========================

バックエンドである LDAP サーバーのテンプレートファイルを :file:`/opt/osstech/etc/unicornidm/templates/ldap1.py` として、以下の内容で作成します。

.. warning::
   このテンプレートファイルのファイル名は ``unicornidm.conf`` で指定したバックエンド名に ``.py`` をつけたファイル名である必要があります。
   Unicorn ID Managerは起動時に ``unicornidm.conf`` に存在するすべてのバックエンドに対して、テンプレートファイルを検索し、
   テンプレートファイルの存在しないバックエンドがあった場合は、起動に失敗します。

.. 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": default(mail),
        "description": default(description),
        "displayName": default(displayName, "%(familyName)s %(givenName)s"),
    }

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

.. _quickstart apache:

Apache HTTP サーバーの準備
==========================

前段となるApaceh HTTP サーバーを準備します。
以下はApacheの設定ファイル内の適切な箇所に以下の設定を追記してください。

.. code-block:: apacheconf

  ProxyRequests off

  ProxyPass /unicornidm/static !
  Alias /unicornidm/static /opt/osstech/var/lib/unicornidm/statics
  <Directory /opt/osstech/var/lib/unicornidm/statics>
    Require all granted
  </Directory>

  ProxyPass /favicon.ico !
  Alias /favicon.ico /opt/osstech/share/doc/osstech-unicornidm/documentation/favicon.ico
  ProxyPass /unicornidm/documentation !
  Alias /unicornidm/documentation /opt/osstech/share/doc/osstech-unicornidm/documentation
  <Directory /opt/osstech/share/doc/osstech-unicornidm/documentation>
    Require all granted
  </Directory>

  ProxyPass /unicornidm unix:/opt/osstech/var/run/unicornidm/uwsgi.sock|uwsgi://localhost/unicornidm retry=1

  <Location "/unicornidm/admin">
    Require all granted
    # <RequireAny>
    #   Require local
    #   Require ip xxx.xxx.xxx.xxx
    # </RequireAny>
  </Location>

  <Location "/unicornidm/user">
    Require all granted
  </Location>


:ref:`ApacheConfigSample` も参考にしてください。

Apache HTTP サーバーと Unicorn ID Manager の連携設定は以上です。

.. _start service:

Unicorn ID Manager の起動
==========================

以下のコマンドで Unicorn ID Manager を起動します。

.. code-block:: shell-session

    # systemctl start osstech-unicornidm

以下のコマンドで前段となる Apache HTTP サーバーを起動します。

.. code-block:: shell-session

    # systemctl start httpd

.. note::
    実行前に SELinux が ``Permissive`` か ``Disabled`` でかつファイヤーウォールが適切に設定されていることを確認してください。

.. warning::
   ``osstech-unicornidm`` は一度起動してから設定ファイルのチェック等を行う関係上、起動した5秒後ほどで終了することがあります。

   ``osstech-unicornidm`` の起動確認は数秒経ったのを確認してから ``systemctl status osstech-unicornidm`` を行うか、
   :file:`/opt/osstech/var/log/unicornidm/uwsgi.log` を確認し、``WSGI app 0 (mountpoint='') ready ...`` というログが出力されるのを確認するようにしてください。

   また :file:`/opt/osstech/var/log/unicornidm/uwsgi.log` は、起動に失敗した際のログ情報が出力されます。
   起動失敗時の原因特定などにもお役立てください。

.. _create administrator:

管理者の作成
=============

Unicorn ID Manager に管理者としてログインするため、管理者を作成します。
パスワードの入力を求められるので、登録する管理者のパスワードを入力してください。
ここでは、管理者の名前を *test-admin* としています。

.. code-block:: shell-session

    # /opt/osstech/sbin/unicornidm-tool admin add test-admin -r SuperAdministrator
    Password:
    Repeat for confirmation:

.. _access from browser:

Web ブラウザーからアクセス
============================

Unicorn ID Manager に Web ブラウザーからアクセスします。アクセスする URL は以下です。
なお、ここでは Unicorn ID Manager のインストールされたサーバーのホスト名が
*uidm.example.com* であることを前提としています。

.. code-block:: none

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

.. warning::
    URL のホスト名は Unicorn ID Manager をインストールしたサーバーのホスト名
    を指定してください (IP アドレスではアクセスできません) 。

アクセスすると、ログイン画面が表示されます。ここに `管理者の作成`_ で作成した
管理者の名前とパスワードを入力します。

.. _quickstart unicornidm-tool:

unicornidm-toolの準備
=====================

``unicornidm-tool`` の利用の準備をします。

.. _creat password file:

パスワードファイルの作成
------------------------

下記のコマンドなどを利用して :file:`/opt/osstech/etc/unicornidm/secrets/tool-admin-password` ファイルを作成してください。

.. code-block:: shell-session

    # install -m 0600 -o unicornidm <(echo -n PASSWORD) /opt/osstech/etc/unicornidm/secrets/tool-admin-password

.. note::
   エディタ等を用いて直接ファイルを編集しても大丈夫です。

.. note::
   ここで設定するパスワードはUnicorn ID Manager が内部で利用するものなので、100桁や200桁のランダムな文字列を設定することを推奨します。

.. warning::
   ここでのファイル名は `設定ファイルの準備`_ で ``client`` セクション内 ``admin_password_file`` に指定したファイル名と一致するようにしてください。

.. _administrator for unicornidm-tool:

unicornidm-tool用管理者の作成
-----------------------------

``unicornidm-tool`` が利用する管理者アカウントを作成します。
管理者名には `設定ファイルの準備`_ で ``client`` セクション内 ``admin_name`` に指定した名前を利用します。(ここではtool-admin)

.. code-block:: shell-session

    # cat /opt/osstech/etc/unicornidm/secrets/tool-admin-password | /opt/osstech/sbin/unicornidm-tool admin add tool-admin -r SuperAdministrator

.. _run unicornidm-tool:

unicornidm-toolの動作確認
-------------------------

下記のコマンドでユーザー一覧が取得できれば ``unicornidm-tool`` の設定は完了です。

.. code-block:: shell-session

   # /opt/osstech/sbin/unicornidm-tool user list target1 --refresh
   userName,uidNumber,gidNumber,loginShell,unixHomeDirectory,familyName,givenName,mail,displayName,ldap1
   test-user,1002,100,/bin/bash,/home/test-user,test,user,test@example.com,test user,Exists

   Page: 1/1
   Total: 2

.. note::
   ``unicornidm-tool`` コマンドを利用することで Unicorn ID Manager の様々な操作を行うことが出来ます。
   詳細は :doc:`unicornidm-tool` をご参照ください。
