5.11. HTTP リクエスト (REST API) による操作¶
注釈
この章はプログラマー向けの情報を記載しています。それ以外の人は読む意味がない、読んでも理解できない可能性が高いです。
Unicorn ID Manager はブラウザや unicornidm-tool(8) だけでなく、任意のプログラムから HTTPリクエストを送ることでユーザー、グループに対する操作を行うことができます。
このセクションでは、その API の仕様を説明します。
5.11.1. 仕様の概要¶
API は SCIM 2.0 の仕様にほぼ準拠しています。
SCIM 2.0 では、データは JSON でやりとりされ、ユーザーやグループ（リソース）の作成、更新、削除などの処理は HTTPメソッド名で識別されます。
5.11.2. 仕様の詳細¶
5.11.2.1. 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 で規定されたものではありません。
5.11.2.2. 認証方式¶
SCIMエンドポイントにおける認証方式は、Basic認証です。
5.11.2.3. 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 }
]
5.11.2.4. URLクエリパラメータについて¶
- refresh
trueを設定することで最新の情報を取得することができます。 デフォルトはfalseです。- backends
- バックエンド名を
,でつなげて書くことで、操作対象のバックエンドを指定することができます。 デフォルトでは操作対象のターゲットのバックエンド全てが操作対象になります。 - page
取得したいリソースのページ番号を整数で指定します。
複数のリソースを取得するときにリソースの数が多い場合、Unicorn ID Manager は全てのリソースを一回の HTTPレスポンスで返そうとせず、一定数のリソース（ページ）を返します。 このとき、どのページが欲しいかをこのパラメータで決定します。
- q
- 検索クエリを指定します。
5.11.2.5. その他¶
この API によるリソースの追加、更新においてはUnicorn ID Manager による必須属性チェックは行われません。
5.11.3. 操作例¶
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
}