SERVICE API REST API USERDATA API

ACR API

K2HR3 REST APIの+サービス（+SERVICE）機能で利用するACR(ACCESS CROSS ROLE)に関連するAPI群です。

POST

サービス（SERVICE）の利用側（MEMBER）としてテナント（TENANT）を紐付けます。（yrn:yahoo:service name::tenant name を作成します。）
紐付けられるテナント（TENANT）には、acr_role、acr_policyと、サービス（SERVICE）所有側（OWNER）から設定されたリソース（RESOURCE）が自動的に作成されます。
このリソース（RESOURCE）は所有側（OWNER）がサービス（SERVICE）に設定した値（VERIFY URLの値、もしくはREST APIのレスポンスの値）です。
作成時には、Unscoped User Token、Scoped User Tokenのいずれかを指定することができます。

動作（詳細）

事前にサービス（SERVICE）所有側（OWNER）によりテナント（TENANT）が利用側（MEMBER）として登録されている必要があります。
作成は、以下のように動作します。（VERIFY URLとしてリソース（RESOURCE）が登録されている場合）

上記のフローによりサービス（SERVICE）利用側（MEMBER）としてテナント（TENANT）が紐付けられます。
VERIFY URLがURL以外の場合には、途中処理（VERIFY URLの呼び出し）が省略され、VERIFY URLに設定されている値を固定値としてリソース（RESOURCE）に設定します。

このフローを下記の図に示します。
K2HR3 REST API - ACR Register Flow

VERIFY URLに渡されるトークン（TOKEN）について

VERIFY URLに渡されるScoped User Tokenは、上述のフロー処理中のみ有効であるワンタイムのトークン（TOKEN）となります。
ACR APIのGETが呼び出された時点で、このトークン（TOKEN）は削除され、利用できなくなります。

Endpoint(URL)

http(s)://API SERVER:PORT/v1/acr/service name

Unscoped User Token時

Content-Type: application/json
x-auth-token: U=<Unscoped User Token>

Scoped User Token時

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Request Body

Unscoped User Token時

{
    "tenant":  <tenant name>
}

Scoped User Token時

なし

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

PUT

サービス（SERVICE）の利用側（MEMBER）としてテナント（TENANT）を紐付けます。（yrn:yahoo:service name::tenant name を作成します。）
紐付けられるテナント（TENANT）には、acr_role、acr_policyと、サービス（SERVICE）所有側（OWNER）から設定されたリソース（RESOURCE）が自動的に作成されます。
このリソース（RESOURCE）は所有側（OWNER）がサービス（SERVICE）に設定した値（VERIFY URLの値、もしくはREST APIのレスポンスの値）です。
作成時には、Unscoped User Token、Scoped User Tokenのいずれかを指定することができます。

Endpoint(URL)

http(s)://API SERVER:PORT/v1/acr/service name
http(s)://API SERVER:PORT/v1/acr/service name?urlarg

Header

Unscoped User Token時

Content-Type: application/json
x-auth-token: U=<Unscoped User Token>

Scoped User Token時

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Unscoped User Token時

Scoped User Token時

なし

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

GET

本メソッドには、2つの機能があり、それぞれの利用用途があります。 それぞれの機能と用途（目的）を以下に説明します。

Scoped User Tokenの情報を取得する

本ACR APIのPUT（POST）メソッドのサービス（SERVICE）利用側（MEMBER）のテナント（TENANT）を紐付ける処理のときに呼び出されることを想定したエントリポイントです。
本メソッドを直接ユーザ（USER）や外部システムが利用することはありません。

本ACR APIのPUT（POST）メソッドの内部処理において、サービス（SERVICE）所有側（OWNER）がVERIFY URLを設定していた場合、この内部処理はVERIFY URLを呼び出します。
このVERIFY URLに対してリクエストを送信するとき、ワンタイムScoped User Tokenが自動的に付加されます。
VERIFY URL側では、このトークン（TOKEN）の確認と、トークン（TOKEN）に紐づけられたユーザ（USER）などの情報を取得します。

本メソッドは、このワンタイムScoped User Tokenの確認を行い、ユーザ（USER）情報を返します。

サービス（SERVICE）利用側（MEMBER）のリソース（RESOURCE）を取得する

本メソッドは、サービス（SERVICE）利用側（MEMBER）に登録されている全リソース（RESOURCE）を取得します。

+サービス（+SERVICE）機能による連携（２）に示すユースケース、サービス（SERVICE）の所有側（OWNER）のシステムが認証・認可をK2HR3システムに委譲する時に呼び出されるAPIです。

これは、サービス（SERVICE）利用側（MEMBER）が、サービス（SERVICE）所有側（OWNER）のシステムにアクセスするとき（前提としてこのシステムでは利用側（MEMBER）固有のリソース（RESOURCE）が必要とする）、K2HR3システムから利用側（MEMBER）のリソース（RESOURCE）を取得せず、直接所有側（OWNER）システムにアクセスすることを目的として提供されるAPIです。
つまり、利用側（MEMBER）固有のリソース（RESOURCE）を所有側（OWNER）のシステムがK2HR3システムから代理で取得するフローになります。
これにより、利用側（MEMBER）は、所有側（OWNER）が提供した固有のリソース（RESOURCE）を知る必要がありません。
利用側（MEMBER）固有のリソース（RESOURCE）は、所有側（OWNER）が提供したものですが、所有側（OWNER）システムにアクセスするとき、事前に利用側（MEMBER）はそのリソース（RESOURCE）を取得する必要がありません。

本メソッドは、所有側（OWNER）が利用側（MEMBER）の代理として、利用側（MEMBER）のサービス（SERVICE）へのアクセス確認、および固有リソース（RESOURCE）の取得を行うためのAPIです。

このフローを以下に示します。

このフローを以下の図に示します。 K2HR3 REST API - ACR GET for one step

側（MEMBER）クライアントホスト（HOST）が属するロール（ROLE）です。
この値はクライアントホスト（HOST）から指定された値を所有側（OWNER）システムが転送します。

Response status

200、40x

Response Body(JSON)

Scoped User Tokenの情報を取得する

{
    result:     <true/false>
    message:    <null or error message string>
    tokeninfo = {
        user:   <user name>
        tenant: <tenant name>
        service:<service name>
    }
}

サービス（SERVICE）利用側（MEMBER）に設定された全リソース（RESOURCE）を取得する

{
    result:     <true/false>
    message:    <null or error message string>
    response:   [
        {
            name:       <resource name>
            expire:     <expire>
            type:       <resource type>
            data:       <resource data>
            keys:       {
                foo:    bar
                ...
            }
        },
        ...
    ]
}

DELETE

サービス（SERVICE）所有側（MEMBER）に登録されている利用側（MEMBER）のテナント（TENANT）を削除します。
テナント（TENANT）のScoped User Tokenを指定します。

Endpoint(URL)

http(s)://API SERVER:PORT/v1/acr/service name

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Response status

204、40x

Response Body(JSON)

なし

SERVICE API REST API USERDATA API