unicornidm.template(5)
========================

概要
-----

::

    templates/<name>.py

説明
------

バックエンドセクションを定義する際に、必ずテンプレートファイルを定義する必要があります。
テンプレートファイルは unicornidm.conf と同じディレクトリにある、
templates ディレクトリ内に、 <name>.py のファイル名で登録します。 <name> はバックエンド
の名前です。

テンプレートファイルのルール
-----------------------------

テンプレートファイルは Python の構文に基づいて以下のルールで記載します。

* *User* 及び *Group* という変数に辞書オブジェクトを割り当てること

* *User* には必ず *userName* という属性 (フロントエンド属性) を含めること

* *Group* には必ず *groupName* という属性 (フロントエンド属性) を含めること

* 辞書オブジェクトは key-value の形式になっていること

* 辞書オブジェクトの key は必ず str 型であること

* 辞書オブジェクトの value は以下のいずれかであること

    - str 型

    - str 型 (printf(3) の文字列書式を含む)

    - list 型

    - dict 型

        + dict の各 value は str か任意の変数であること

    - 任意の変数

    - default 関数の返り値

例
-----

以下は LDAP バックエンドのテンプレートファイルです。

::

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


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

このテンプレートファイルの特徴は以下です。

* *objectClass* に要素すべてが str 型の list を格納しています

    - バックエンドに属性を渡す際、必ず objectClass がここで定義した属性になります

* User の *uid* には userName という Unicorn ID Manager の任意属性が割り当てられています

    - Unicorn ID Manager から **userName=user1** としてユーザー登録を行った時、
      バックエンドには **uid: user1** として登録されます

* User の *mail* には email という Unicorn ID Manager の任意属性が割り当てられています

    - ルールは *uid* と同様ですが、もし email に複数の値が格納されていた場合、
      バックエンドの mail 属性にも同様に複数の値が割り当てられます

* User の *loginShell* には default 関数の返り値が割り当てられています

    - default 関数の第一引数 loginShell が指定されなかった場合、第二引数の
      /bin/bash が loginShell に割り当てられます

* User の *homeDirectory* には default 関数の返り値が割り当てられています

    - default 関数の第一引数 homeDirectory が指定されなかった場合、第二引数の
      /home/%(userName)s が割り当てられます。なお、 %(userName)s は Unicorn ID Manager
      の任意属性 userName の値に展開されます

* Group の *description* には default 関数の返り値が割り当てられています

    - default 関数の第一引数 description が指定されなかった場合、 *description*
      は空になります

フロントエンド属性とバックエンド属性
-------------------------------------

Unicorn ID Manager は複数の種類の異なるバックエンドを扱うために、
*フロントエンド属性* と *バックエンド属性* を定義しています。

*フロントエンド属性* は管理者が任意に定義する属性です。普段の運用では主に、
この *フロントエンド属性* を見てユーザーやグループの管理を行います。

*バックエンド属性* はバックエンド固有の属性です。たとえば、バックエンドタイプが
LDAP の場合を考えます。 LDAP にはスキーマがあり、登録可能な属性が決まっています。
posixAccount という objectClass のスキーマの場合、必ず、 uidNumber, homeDirectory,
loginShell などの決まった属性が必要になります。このようなバックエンドに固有の属性を
Unicorn ID Manager はバックエンド属性として扱います。

管理者は Unicorn ID Manager の設定時に、 *フロントエンド属性* と *バックエンド属性*
を関連付けます。その関連付けた設定ファイルがバックエンドのテンプレートファイルとなります。
テンプレートファイルで *フロントエンド属性* にあたるのが、テンプレートファイルの
Python dict オブジェクト内の値に存在する識別子です (以下の場合、 userName が識別子です。
124 と True はそれぞれ数値と bool 値です) 。

.. code-block:: python

    User = {
        "cn": userName,
        "gidNumber": 124,
        "active": True,
        ...

それぞれのテンプレートファイルで共通の *フロントエンド属性* を定義しておくことで、
ID の一元管理が可能です。

::

    フロントエンド属性     バックエンド属性

    userName   ------+---> uid (LDAP)
                     |
                     +---> cn (AD)
                     |
                     +---> userPrincipalName (Azure)

    familyName ------+---> sn (LDAP)
                     |
                     +---> sn (AD)
                     |
                     +---> surname (Azure)
                     |
                     +---> familyName (Google)


特別なフロントエンド属性
-------------------------

*フロントエンド属性* は任意に定義可能ですが、以下に挙げる *フロントエンド属性*
は Unicorn ID Manager で特別な意味をもつものです。

* userName
* groupName
* password
* active
* member

userName
^^^^^^^^^

ターゲット内において、ユーザーを一意に識別するためのフロントエンド属性です。
ユーザーを一意に識別するために別の属性を定義することはできません。

groupName
^^^^^^^^^^

ターゲット内において、グループを一意に識別するためのフロントエンド属性です。
グループを一意に識別するために別の属性を定義することはできません。

password
^^^^^^^^^

ユーザーのパスワードを示すフロントエンド属性です。
他の属性名をパスワードを示すフロントエンド属性にすることはできません。
また、 password 属性はオプション属性として定義しなくてもユーザー登録時に
省略可能です。省略した場合、ターゲットの設定で定めたポリシーに基づいて
ランダムな文字列が割り当てられます。ランダムに生成されたパスワードは
:doc:`unicornidm-tool` や管理画面から確認できます。

active
^^^^^^^

ユーザーの有効・無効を示すフロントエンド属性です。 True の場合は有効を示し、
False の場合は無効を示します。ユーザーの有効・無効を示すために別の属性を
定義することはできません。

member
^^^^^^^

グループのメンバーを示す属性です。グループのメンバーを示すために別の属性を
定義することはできません。

フロントエンド属性の大文字・小文字
------------------------------------

*フロントエンド属性* は大文字と小文字を区別します。
