Google (Google Workspace) バックエンド
======================================

概要
-----

::

    unicornidm.conf, templates/<backendname>.py

説明
------

バックエンドセクションのうち、 *type* が *google* となっているバックエンドは、
Google Workspace (旧名 Google G Suite) への接続に関する設定を行います。

リファレンス
------------

unicornidm.conf のパラメーター
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. envvar:: type

    バックエンドのタイプを指定します。 `google` に設定してください。

.. envvar:: description

    バックエンドの説明文を指定します。

    .. versionadded:: 3.18.7

.. envvar:: domain

    接続する Google Workspace のドメイン名を指定します。

.. envvar:: bind_user

    Google Workspace の管理者を指定します。
    APIキーの作成に使った管理者を指定してください。

.. envvar:: json_key_path

    Google Workspace で API を利用するための設定をする際に生成される
    JSON key ファイルのパスを指定します。
    作成方法については :ref:`prepare Google Workspace` を参照してください。

.. envvar:: user_enable_check_result_retry_count

   ユーザー有効化時に結果の反映を待つ際のリトライ回数を指定します。
   有効化処理完了後に結果が反映されていることを1秒おきにチェックします。
   有効化処理自体は成功した後に反映されるのを待つだけですので、0に設定しても動作上問題ありません。
   デフォルト値は3です。

.. versionadded:: 3.18.6

.. envvar:: user_disable_check_result_retry_count

   ユーザー無効化時に結果の反映を待つ際のリトライ回数を指定します。
   無効化処理完了後に結果が反映されていることを1秒おきにチェックします。
   無効化処理自体は成功した後に反映されるのを待つだけですので、0に設定しても動作上問題ありません。
   デフォルト値は3です。

.. versionadded:: 3.18.6

テンプレートファイル
^^^^^^^^^^^^^^^^^^^^

注意すべき点は以下のとおりです。

* `userName` は `primaryEmail` バックエンド属性にしか紐付けることはできません。

* `groupName` は `email` バックエンド属性にしか紐付けることはできません。

* `User` には必ず次のバックエンド属性を付与してください。

    - `primaryEmail`

    - `name.givenName`

    - `name.familyName`

    - `password`

* `User` に `hashFunction` バックエンド属性を付与する場合、必ず `crypt` か `SHA-1` か `MD5` を指定してください。

基本的な設定
------------

1. :ref:`prepare Google Workspace` を参照してサービスアカウントと APIキー（JSONキー）を作成してください。

2. :doc:`../unicornidm-conf` に以下のように設定してください。

::

    [backend:<Google バックエンドの名前>]
    type = google
    domain = <サービスアカウントがアクセスできるドメイン>
    bind_user = <APIキーの作成に使った管理者>
    json_key_path = <APIキーへのパス>

`<...>` の部分はご自身の環境での値に書き換えてください。

3. テンプレートファイル :file:`templates/<Google バックエンドの名前>.py` を作成し、以下のように書いてください。
   これはRPMパッケージをインストールすると作成される :file:`templates/google-example.py` の中身と同じです。

::

    User = {
        "primaryEmail": userName,
        "name": {
            "givenName": givenName,
            "familyName": familyName,
        },
        "password": password,
        "aliases": default(alias),
        "hashFunction": "crypt",  # SHA-1 or MD5 or crypt
        "orgUnitPath": default(orgUnitPath, "/"),
        "changePasswordAtNextLogin": default(changePasswordAtNextLogin, False),
        "suspended": not default_hidden(active, True),
    }


    Group = {
        "email": groupName,
        "description": default(description),
    }


上記バックエンドをターゲットに紐付けると、そのターゲットからバックエンドに操作ができます。

Google バックエンド特有の動作
-----------------------------

* `userName`, `groupName` の `@` 以降のドメイン部は無視されます。
  操作実行時にドメイン部を省略すると :file:`unicornidm.conf` で設定したドメイン部が補われます。
  一覧画面やユーザー詳細画面などではドメイン部を除いた部分が `userName`, `groupName` として表示されます。


* 名前変更操作を行うと、変更前の名前 (`userName`, `groupName`) は `aliases` バックエンド属性に追加されます。


制限
----

* 複数のドメインを1つのバックエンドで管理することはできません。

* メールエイリアス (`aliases`) には `<別名>@<ドメイン名>` 形式の
  有効なメールアドレスを指定する必要がありますが、無効な形式を指定しても
  エラーを報告せずに単に無視します。

.. issue #439 G Suite: aliases に無効な値を設定しようとしてもエラーにならず単に無視される

* 組織部門 (`orgUnitPath`) の管理には対応していません。
  ユーザーに所属させたい組織部門は別途 G Suite の管理ツールで作成しておいてください。

* ユーザーの一覧表示のフィルターや操作対象を組織部門やグループ
  で制限することはできません。

.. issue #417 G Suite: ユーザーのフィルターに対応

* グループのメーリングリスト関連の設定に対応していません。
  (Groups Settings API に未対応)

.. issue #437 G Suite: Groups Settings API に対応して欲しい (メーリングリスト設定)

G Suite 由来の制限
^^^^^^^^^^^^^^^^^^

Google G Suite への操作は G Suite Directory API 経由で実行しています。
以下の制限はその API に起因するものであり、 Unicorn ID Manager 側で解決することができません。

* 更新操作直後にユーザー/グループを閲覧すると更新前の状態が表示される場合があります。

* 更新操作の結果が成功となっていても、更新が実際には行われない場合があります。
  これは必須属性の削除など、 G Suite の制約を違反する更新をしようとした場合などに生じる場合があります。

* `primaryEmail`, `email` は登録時、名前変更時の大文字小文字を保つことができません。含まれる大文字は全て小文字に変換されて G Suite に保存されます。

* 作成直後のグループにメンバーを追加することはできません。しばらく時間をあけてからメンバー追加をしてください。
