unicornidm.conf(5)
===================

概要
-----

::

    unicornidm.conf

説明
------

*unicornidm.conf* は Unicorn ID Manager の設定ファイルです。このファイルは Python
の configparser モジュールを利用して読み込まれます。 configparser モジュールの詳細
については、 https://docs.python.org/3/library/configparser.html をご覧ください。

*unicornidm.conf* は大きく分けて次のセクションで構成されています。

メインセクション
    Unicorn ID Manager サービス全体に及ぶ設定を記述するセクションです。

ターゲットセクション
    ターゲットに関するセクションです。ターゲットがどのバックエンドに紐付いているか、
    どのようなパスワードポリシーを適用するかを定義します。

バックエンドセクション
    バックエンドに関するセクションです。バックエンドへの接続用パラメーターなどを
    定義します。バックエンドセクションはバックエンドの *type* によって設定パラメーター
    が異なります。なお、バックエンドセクションにはかならずテンプレートファイルが
    必要になります。テンプレートファイルは unicornidm.conf と同じディレクトリにある、
    templates ディレクトリ内に、 <name>.py のファイル名で登録します。 <name> はバックエンド
    の名前です。

SCIM 属性マッピングセクション
    SCIM 属性と任意に定義したフロントエンド属性 (Unicorn ID Manager で使用する属性) との
    マッピングのためのセクションです。

クライアントセクション
    Unicorn ID Manager に付属する :doc:`unicornidm-tool` で使用されるセクションです。

メインセクション
-----------------

メインセクションは [__main__] という名前のセクションで定義されます。
ここでは以下のパラメーターを定義できます。

debug_level
    Unicorn ID Manager のデバッグレベルを定義します。定義可能な値は以下のとおりです。

    ::

        DEBUG           すべてのデバッグログを出力
        INFO            DEBUG を除いたデバッグログを出力
        WARNING         DEBUG, INFO を除いたデバッグログを出力
        ERROR           DEBUG, INFO, WARNING を除いたデバッグログを出力
        CRITICAL        DEBUG, INFO, WARNING, ERROR を除いたデバッグログを出力

debug_file
    Unicorn ID Manager のデバッグ情報を出力するファイルパスを定義します。

targets
    ターゲット一覧をカンマ区切りで定義します。ターゲット文字列内に **:** を含む場合、
    **:** の左側がシステムで利用するためのターゲット名になり、
    右側の文字列はターゲットの表示名になります。システムで利用するターゲット名は
    URL 等に利用されます。ターゲットの表示名は管理画面のダッシュボード上で
    ターゲットを表示するために利用されます。
    **:** を含まない場合、システムで利用するターゲット名とターゲットの表示名は同一になります。

session_time_out
    ログインしたアカウントのセッションタイムアウト (単位: 秒) を定義します。
    デフォルト値は 3600 です。

password_cache_duration
    ランダム生成されたパスワードを保持する期間 (単位: 秒) を設定します。
    デフォルト値は 86400 です。

items_per_page
    ユーザーやグループの一覧取得時に出力する項目数を指定します。
    デフォルト値は 20 です。

multi_valued_attributes
    複数値を持つフロントエンド属性をカンマ区切りで指定します。
    デフォルト値は mail,phoneNumbers,img,photo,streetAddress,locality,region,postalCode,country,entitlement,role,x509Certificate,azureLicense です。

user_viewable_attributes
    ユーザー一覧取得時に出力するフロントエンド属性名をカンマ区切りで定義します。
    デフォルト値は userName,familyName,givenName です。

group_viewable_attributes
    ユーザー一覧取得時に出力するフロントエンド属性名をカンマ区切りで定義します。
    デフォルト値は groupName,description です。

admin_lockout_policy_duration
    管理者のロックアウト期間 (単位: 秒) を定義します。デフォルト値は 3600 です。

admin_lockout_policy_max_failure
    管理者が連続で何回ログインに失敗したあとにロックアウトするかを定義します。
    デフォルト値は 3 です。

admin_lockout_policy_failure_count_interval
    認証失敗時刻の情報が存続する期間 (単位: 秒) を定義します。
    デフォルト値は 1800 です。この値を 0 にした場合、
    認証失敗時刻情報が削除されないため、 *lockout_policy_max_failure* で
    定義した回数だけ連続で認証が失敗すれば、たとえどんなに期間を空けても
    必ずロックアウトされます。


ターゲットセクション
--------------------

ターゲットセクションは [target:<name>] という名前のセクションで定義されます。
<name> はメインセクションの *targets* で列挙したうちのターゲット名になります。

たとえば、以下のようになります。

::

    [__main__]
    targets = Sales, Finance, Tech

    [target:Sales]
    ...

    [target:Finance]
    ...

    [target:Tech]
    ...

ターゲットセクションでは以下のパラメーターを定義できます。

backends
    ターゲットに紐づくバックエンドをカンマ区切りで定義します。

password_policy_max
    パスワードポリシーのうち、パスワードの最大長を定義します。
    デフォルト値は 16 です。

password_policy_min
    パスワードポリシーのうち、パスワードの最小長を定義します。
    デフォルト値は 8 です。

password_policy_upper
    パスワードポリシーのうち、パスワードに含めなければならない英大文字の数を定義します。
    デフォルト値は 1 です。

password_policy_lower
    パスワードポリシーのうち、パスワードに含めなければならない英小文字の数を定義します。
    デフォルト値は 1 です。

password_policy_symbol
    パスワードポリシーのうち、パスワードに含めなければならない印字 ASCII 記号の数を
    定義します。デフォルト値は 0 です。

password_policy_digit
    パスワードポリシーのうち、パスワードに含めなければならない数字の数を定義します。
    デフォルト値は 1 です。

password_policy_complexity
    パスワードポリシーのうち、パスワードの複雑性を定義します。
    具体的には、英大文字、英小文字、記号、数字という 4 つのカテゴリのうち、
    いくつのカテゴリをパスワードに含める必要があるかを定義します。
    デフォルト値は 3 です。

password_policy_prohibited
    パスワードポリシーのうち、パスワードに含めてはならない文字 (禁止文字) を定義します。
    デフォルト値は空文字 (禁止文字はなし) です。

password_policy_must_not_contain_name
    パスワードポリシーのうち、パスワードにユーザーの名前を含めてよいかどうかを定義します。
    デフォルト値は true (名前を含めてはならない) です。

password_policy_must_be_different_from_old
    パスワードポリシーのうち、パスワードが 1 つ前のパスワードと異なる必要が
    あるかを定義します。デフォルト値は true (異なる必要がある) です。

password_policy_must_be_various
    パスワードポリシーのうち、パスワードが多様な種類の文字で構成される必要があるか
    を定義します。です。 true (多様である必要がある) です。

password_policy_must_be_disorder
    パスワードポリシーのうち、パスワードが不規則である必要があるがあるかを定義します。
    デフォルト値は true (不規則である必要がある) です。

password_policy_dictionary_path
    パスワードポリシーのうち、パスワードが辞書に含まれていないものである必要が
    あるかを定義します。 デフォルト値はありません。

password_policy_message_path
    一般ユーザーなどのパスワード変更画面で、ユーザーオリジナルのポリシーメッセージが
    格納されたファイルパスを定義します。デフォルト値はありません。

password_policy_random_prohibited
    パスワード自動生成時に使用を禁止する文字列を定義します。
    デフォルト値は印字可能なすべての ASCII 記号です。

password_policy_random_length
    パスワード自動生成時に使用されるパスワード文字数です。
    デフォルト値は 8 です。

lockout_policy_duration
    ユーザーのロックアウト期間 (単位: 秒) を定義します。デフォルト値は 3600 です。

lockout_policy_max_failure
    ユーザーが連続で何回ログインに失敗したあとにロックアウトするかを定義します。
    デフォルト値は 3 です。

lockout_policy_failure_count_interval
    認証失敗時刻の情報が存続する期間 (単位: 秒) を定義します。
    デフォルト値は 1800 です。この値を 0 にした場合、
    認証失敗時刻情報が削除されないため、 *lockout_policy_max_failure* で
    定義した回数だけ連続で認証が失敗すれば、たとえどんなに期間を空けても
    必ずロックアウトされます。

self_password_reset
    self_password_reset を利用するかどうかを定義します。この機能を
    有効にすることで、ユーザーが自分自身でパスワードリセットを行うことが
    できるようになります。
    デフォルト値は no (self_password_reset は利用しない) です。

    .. versionadded::
        v3.4.0

self_password_reset_mail_attribute
    Unicorn ID Manager は self_password_reset 有効時、
    パスワードリセット用 URL をユーザーに伝達します。このときの伝達には
    メールが使われます。この設定は、 **メール** を示す *フロントエンド属性*
    が何かを指定するために使われます。デフォルト値は mail です。

    .. versionadded::
        v3.4.0

self_password_reset_url_duration
    self_password_reset 有効時、 パスワードリセット用 URL の有効期間 (単位: 秒)
    を定義します。デフォルト値は 3600 です。

    .. versionadded::
        v3.4.0

self_password_reset_smtp_host
    self_password_reset 有効時、メール配送に利用する SMTP サーバーのホスト名を
    指定します。デフォルト値は "" (localhost に配送) です。

    .. versionadded::
        v3.4.0

self_password_reset_smtp_port
    self_password_reset 有効時、メール配送に利用する SMTP サーバーのポート番号を
    指定します。デフォルト値は 0 (self_password_reset_smtp_tls が有効な場合 465 、
    無効な場合 25 に配送) です。

    .. versionadded::
        v3.4.0

self_password_reset_smtp_tls
    self_password_reset 有効時、メール配送に利用する SMTP サーバーへの接続に、
    TLS を利用するかどうかのフラグを指定します。
    デフォルト値は no (TLS は利用しない) です。

    .. versionadded::
        v3.4.0

self_password_reset_smtp_login_name
    self_password_reset 有効時、メール配送に利用する SMTP サーバーへの接続時に、
    認証を行うためのユーザー名を指定します。
    デフォルト値は "" です。 "" の場合、 SMTP 接続時の認証は行われません。

    .. versionadded::
        v3.4.0

self_password_reset_smtp_login_password_file
    self_password_reset_smtp_login_name のパスワードを格納したファイルパスを
    指定します。デフォルト値は "" です。

    .. versionadded::
        v3.4.0

self_password_reset_from
    self_password_reset 有効時、メール配送の際の *From:* を指定します。
    デフォルト値は "" (Unicorn ID Manager のインストールされたホスト名) です。

    .. versionadded::
        v3.4.0

self_password_reset_bcc
    self_password_reset 有効時、メール配送の際の *Bcc:* を指定します。
    デフォルト値は "" (Bcc: に値はセットされない) です。

    .. versionadded::
        v3.4.0

self_password_reset_subject
    self_password_reset 有効時、メール配送の際の件名を指定します。
    デフォルト値は "" (システムで自動生成) です。

    .. versionadded::
        v3.4.0

self_password_reset_body_file
    self_password_reset 有効時、メール配送の際のボディの内容を含むファイルパスを指定します。
    デフォルト値は "" (システムで自動生成) です。

    ボディに *%(url)s* というプレースホルダーを含めると、そのプレースホルダーに
    パスワードリセット用の URL が挿入されます。 *%(url)s* が含まれない場合、ボディの
    末尾にパスワードリセット用の URL が追記されます。

    ボディに *%(name)s* というプレースホルダーを含めると、そのプレースホルダーに
    ユーザー名が挿入されます。 *%(name)s* が含まれない場合、
    ボディにユーザー名は含まれません。

    例::


        %(name)s様

        ご利用のアカウントに対してパスワードリセットの要求が行われました。
        以下の URL にアクセスしてパスワードリセットを行ってください。

        %(url)s

        なお、この URL は一定時間経過後、無効になります。

    .. versionadded::
        v3.4.0

self_modify
    self_modify を利用するかどうかを定義します。この機能を
    有効にすることで、ユーザーが自身の属性を変更することが
    できるようになります。
    デフォルト値は no (self_modify は利用しない) です。

    .. versionadded::
        v3.7.0

self_modify_attributes
    self_modify を利用する際、どのフロントエンド属性を変更可能かを指定します。
    デフォルト値は familyName, givenName, mail です。

    .. versionadded::
        v3.7.0

self_modify_duration
    self_modify を利用する際のユーザーのセッションタイムアウトを指定します。
    デフォルト値は 3600 (秒) です。

    .. versionadded::
        v3.7.0

header_auth
    header_auth を利用するかどうかを定義します。この機能を
    有効にすることで、ユーザーがパスワード変更画面や属性変更画面
    にアクセスした際に、ログイン済み状態として扱うことができます。
    この機能は後述の header_auth_user_header で指定した
    HTTP リクエストヘッダーに指定されたユーザー名から、
    そのユーザーがログイン済み状態と判定します。
    また、ユーザー名を示すリクエストヘッダーがセットされていたとしても、
    後述の header_auth_trust_ips で指定した
    IP アドレス (ネットワークアドレス) からの通信の場合のみに
    ログイン済み状態となります。
    デフォルト値は no (header_auth は利用しない) です。

    .. versionadded::
        v3.7.1

header_auth_trust_ips
    header_auth を利用する際の信頼できるソース IP アドレスを
    カンマ区切りで指定します。
    ソース IP アドレスは CIDR 表記やサブネットマスクによる表記で
    指定することもできます。その場合、表記のネットワークアドレス範囲内に
    ソース IP アドレスが含まれれば、そのアクセスは信頼できるアクセスと
    みなされます。デフォルト値は 127.0.0.1 です。

    .. versionadded::
        v3.7.1

header_auth_user_header
    header_auth を利用する際のユーザー名を示すヘッダー名を指定します。
    header_auth 機能では、この属性で示したヘッダー名を参照します。
    デフォルト値は Remote-User です。

    .. versionadded::
        v3.7.1

header_auth_require_old_password
    header_auth を利用する際パスワード変更画面で、古いパスワードの
    入力を要求するかどうかを指定します。
    デフォルト値は yes (古いパスワードの入力が必要) です。

    .. versionadded::
        v3.7.2

extension_ldap_ppolicy_unlock
    ldap_ppolicy_unlock 拡張を利用するかどうかを定義します。この拡張は ldap
    バックエンドが OpenLDAP でかつ、 ppolicy overlay を利用してアカウントロックを
    実装している場合に、ロック状態のアカウントをブラウザーからアンロックできるようにする
    機能です。デフォルト値は no (ldap_ppolicy_unlock 拡張は利用しない) です。

バックエンドセクション
----------------------

バックエンドセクションは [backend:<name>] という名前のセクションで定義されます。
<name> はターゲットセクションの *backends* で列挙したうちのバックエンド名になります。

たとえば、以下のようになります。

::

    [__main__]
    targets = Sales, Finance, Tech

    [target:Sales]
    backends = b1, b2

    [target:Finance]
    backends = b2

    [target:Tech]
    backends = b3

    [backend:b1]
    ...

    [backend:b2]
    ...

    [backend:b3]
    ...


バックエンドセクションはバックエンドのタイプによって定義可能なパラメーターが異なります。
詳細は :doc:`unicornidm-template-ldap` :doc:`unicornidm-template-samba_ldap`
:doc:`unicornidm-template-ad` :doc:`unicornidm-template-google` :doc:`unicornidm-template-azure`
:doc:`unicornidm-template-command` をご覧ください。

SCIM 属性マッピングセクション
-----------------------------

SCIM 属性マッピングセクションには *[scim-attribute-map-user]* というセクションと、
*[scim-attribute-map-group]* というセクションがあります。それぞれ、ユーザー向けと
グループ向けの SCIM 属性マッピングを行います。

SCIM 属性マッピングとは、 SCIM で定義されている属性と Unicorn ID Manager で
使用する任意のフロントエンド属性とをマッピングする機構です。

たとえば、以下のように定義します。

::

    [scim-attribute-map-user]
    externalId     = userName
    name.givenName = givenName

この場合、ユーザー情報を扱う際、 SCIM の *externalId* を Unicorn ID Manager の
userName に、 *name.givenName* を Unicorn ID Manager の *givenName* にマッピングします。

SCIM 属性に **.** (ドット) を含まなければそのまま Unicorn ID Manager のフロントエンド属性に
マッピングされます。 **.** を含む場合、その SCIM 属性は Complex 属性である必要があります。

クライアントセクション
----------------------

クライアントセクションは :doc:`unicornidm-tool` で利用されます。詳細は :doc:`unicornidm-tool`
をご覧ください。

例
---

FIXME
