HTTP リクエスト (REST API) による操作 
*************************************

.. note::
    この章はプログラマー向けの情報を記載しています。それ以外の人は読む意味がない、読んでも理解できない可能性が高いです。

Unicorn ID Manager はブラウザや :doc:`unicornidm-tool` だけでなく、任意のプログラムから HTTPリクエストを送ることでユーザー、グループに対する操作を行うことができます。

このセクションでは、その API の仕様を説明します。

仕様の概要
==========

API は `SCIM 2.0`_ の仕様にほぼ準拠しています。

`SCIM 2.0`_ では、データは JSON でやりとりされ、ユーザーやグループ（**リソース**）の作成、更新、削除などの処理は HTTPメソッド名で識別されます。

仕様の詳細
==========

Unicorn ID Manager の SCIM 2.0 対応状況
---------------------------------------

以下の表の *エンドポイント* とはURLの ``unicornidm/scim/<Target ID>`` 以降の部分を指しています。
そのURLに、対応するHTTPメソッドのリクエストを送ることで操作が行われます。

+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|リソース       |エンドポイント              |操作            |HTTPメソッド|対応状況|受理するURLクエリパラメータ       |
+===============+============================+================+============+========+==================================+
|ユーザー       |``/Users``                  |リソース所得    |GET         |OK      | ``refresh`` , ``page`` , ``q``   |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース所得    |POST        |非対応  |                                  |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース追加    |POST        |OK      | ``backends``                     |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|グループ       |``/Groups``                 |リソース所得    |GET         |OK      | ``refresh`` , ``page`` , ``q``   |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース所得    |POST        |非対応  |                                  |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース追加    |POST        |OK      | ``backends``                     |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|ユーザー       |``/Users/%(userName)s``     |リソース所得    |GET         |OK      | ``refresh``                      |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース置換    |PUT         |OK      | ``backends``                     |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース修正    |PATCH       |非対応  |                                  |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース削除    |DELETE      |OK      | ``backends``                     |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|グループ       |``/Groups/%(groupName)s``   |リソース所得    |GET         |OK      | ``refresh``                      |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース置換    |PUT         |OK      | ``backends``                     |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース修正    |PATCH       |非対応  |                                  |
|               |                            +----------------+------------+--------+----------------------------------+
|               |                            |リソース削除    |DELETE      |OK      | ``backends``                     |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|               |``/Me``                     |                |            |非対応  |                                  |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|               |``/Bulk``                   |一括処理        |            |非対応  |                                  |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+
|               |``[prefix]/.search``        |                |            |非対応  |                                  |
+---------------+----------------------------+----------------+------------+--------+----------------------------------+

上記で示した以外のURLクエリパラメータは無視されます。
またこれらのURLクエリパラメータはどれも `SCIM 2.0`_ で規定されたものではありません。

認証方式
--------
SCIMエンドポイントにおける認証方式は、Basic認証です。

HTTPリクエストボディー部のデータフォーマット
--------------------------------------------
上述した操作のうち、HTTPメソッドが ``POST`` , ``PUT`` のものは、HTTPリクエストのボディー部にJSONのデータを与える必要があります。
このJSONのフォーマットは `RFC7643`_ で定義されています。

リソースがユーザーの場合は ``urn:ietf:params:scim:schemas:core:2.0:User`` のスキーマに、
グループの場合は ``urn:ietf:params:scim:schemas:core:2.0:Group`` のスキーマに従ってください。

デフォルトでは Unicorn ID Manager のフロントエンド属性と SCIM の属性の対応は以下のようになっています。
ただし、ここではフロントエンド属性と SCIM属性の属性名が全く同じものは省略しています。
なお、この対応は設定で変更することができます。

.. TODO: scim-attribute-map へのリンクを貼る。

ユーザー::

    id: %(userName)s,
    externalId: %(userName)s,
    name: {
        familyName: %(familyName)s,
        givenName:  %(givenName)s,
        formatted:  %(formatted)s,
        middleName: %(middleName)s,
        honorificPrefix: %(honorificPrefix)s,
        honorificSuffix: %(honirificSuffix)s,
    }
    emails: [
        { value: %(mail)s }
    ],
    phoneNumbers: [
        { value: %(phoneNumber)s }
    ],
    imgs: [
        { value: %(img)s }
    },
    photos: [
        { value: %(photo)s }
    ],
    addresses: [
        {
            streetAddress: %(streetAddress)s,
            locality: %(locality)s,
            region: %(region)s,
            postralCode: %(postralCode)s,
            country: %(country)s,
        }
    ],
    entitlements: [
        { value: %(entitlement)s }
    ],
    roles: [
        { value: %(role)s }
    ],
    x509Certificates: [
        { value: %(x509Certificate)s }
    ],
    manager: {
        displayName: %(manager)s
    }

グループ::

    id: %(groupName)s,
    displayName: %(groupName)s,
    externalId: %(groupName)s,
    members: [
        { display: %(member)s }
    ]


URLクエリパラメータについて
---------------------------

refresh
    ``true`` を設定することで最新の情報を所得することができます。
    デフォルトは ``false`` です。

backends
    バックエンド名を ``,`` でつなげて書くことで、捜査対象のバックエンドを指定することができます。
    デフォルトでは捜査対象のターゲットのバックエンド全てが操作対象になります。

page
    所得したいリソースのページ番号を整数で指定します。

    複数のリソースを所得するときにリソースの数が多い場合、Unicorn ID Manager は全てのリソースを一回の HTTPレスポンスで返そうとせず、一定数のリソース（ページ）を返します。
    このとき、どのページが欲しいかをこのパラメータで決定します。

q
    検索クエリを指定します。


その他
------

この API によるリソースの追加、更新においてはUnicorn ID Manager による必須属性チェックは行われません。

操作例
======
curlコマンドによる操作例です。


リソースの所得::

    $ curl -D - -H 'Authorization: Basic dGVdChGpjzWyXQ=' --request GET https://localhost/unicornidm/scim/Target3/Users
    HTTP/1.1 200 OK
    Vary: Accept-Language, Cookie
    Content-Type: application/scim+json
    Content-Language: en
    X-Frame-Options: DENY

    {
      "totalResults": 11,
      "Resources": [
        {
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "meta": {
            "resourceType": "User"
          },
          "externalId": "demo 1",
          "id": "demo 1",
          "name": {
            "familyName": "demo",
            "givenName": "1"
          },
          "userName": "demo 1"
        },
        {
          "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
          ],
          "meta": {
            "resourceType": "User"
          },
          "externalId": "demo 2",
          "id": "demo 2",
          "name": {
            "familyName": "demo",
            "givenName": "2"
          },
          "userName": "demo 2"
        },
        （中略）
      "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
      ],
      "startIndex": 1,
      "itemsPerPage": 11
    }




.. _SCIM 2.0: http://www.simplecloud.info/

.. _RFC7643: https://tools.ietf.org/html/rfc7643

.. _RFC7644: https://tools.ietf.org/html/rfc7644
