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

注釈

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

Unicorn ID Manager はブラウザや 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属性の属性名が全く同じものは省略しています。なお、この対応は設定で変更することができます。

ユーザー:

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
}