第3章 認証ポリシー API

認証ポリシーにより、アプリケーションユーザーの 認証 と 承認 を行うための異なるメソッドを定義することができます。異なる認証ポリシーにより、異なる認証設定オプションを定義する必要があります。各種の認証設定オプションの構造は、認証設定オプションで定義されます。

3.1. 認証ポリシーの作成

3.1.1. 説明

新規の認証ポリシーを作成します。

3.1.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/create
  • メソッド: POST

3.1.3. リクエストボディー

{
  // required - a unique id for the policy. Used by $fh.auth() to
  // specify which Auth policy to use for authenticating/authorizing users
  "policyId": "<for example, oauth-google>",
  // required - the type of Autheitcation policy
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  // required, the configuration parameters for the policy
  // See Configuration Options section for full details
  "configurations": {<Config JSON Object>},
  // optional, default false
  // Flag to indicate if a check should be performed to
  // validate that the user id of the user being autheticated exists
  // in the platform. This should be set to
  // true for private apps & false for public apps.
  "checkUserExists": true | false,
  // Flag to indicate if our User needs to be approved for Auth
  "checkUserApproved": true | false
}

3.1.4. レスポンスボディー

3.1.4.1. 成功

{
  "status": "ok",
  "guid": "<new_auth_policy_global_unique_id>"
}

3.1.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.2. 認証ポリシーの読み込み

3.2.1. 説明

既存の認証ポリシーの詳細を読み込みます。

3.2.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/read
  • メソッド: POST

3.2.3. リクエストボディー

{
  // required - the unique id the policy to read
  "policyId": "<for example, oauth-google>"
}

3.2.4. レスポンスボディー

3.2.4.1. 成功

{
  "status": "ok",
  "guid": "<auth_policy_global_unique_id>",
  "policyId" : "<user_defined_policy_identifier>"
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  "configurations": {<Config JSON Object>},
  "checkUserExists": true | false,
  "checkUserApproved": true | false,
  "users" : [<user-id>]
}

3.2.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.3. 認証ポリシーの更新

3.3.1. 説明

既存の認証ポリシーを更新します。

3.3.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/update
  • メソッド: POST

3.3.3. リクエストボディー

{
  // required - the global unique identifier for the policy to update
  "guid" : "<global_unique_identifier>",
  // required - a unique id for the policy. Used by $fh.auth() to
  // specify which authentication policy to use for authenticating/authorizing users
  "policyId": "<for example, oauth-google>",
  // required - the type of Auth policy
  "policyType": "<oauth1 | oauth2 | ldap | openid>",
  // required, the configuration parameters for the policy
  // See See Configuration Options section for full details
  "configurations": {<Config JSON Object>},
  // optional, default false
  // Flag to indicate if a check should be performed to
  // validate that the user id of the user being authenticated exists
  // in the platform. This should be set to
  // true for private apps & false for public apps.
  "checkUserExists": true | false,
  // Flag to indicate if our User needs to be approved for Auth
  "checkUserApproved": true | false
}

3.3.4. レスポンスボディー

3.3.4.1. 成功

{
  "status": "ok",
  "guid": "<auth_policy_global_unique_id>"
}

3.3.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.4. 認証ポリシーの削除

3.4.1. 説明

既存の認証ポリシーを削除します。

3.4.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/delete
  • メソッド: POST

3.4.3. リクエストボディー

{
  // required - the global unique identifier for the policy to delete
  "guid" : "<global_unique_identifier>"
}

3.4.4. レスポンスボディー

3.4.4.1. 成功

{
  "status": "ok"
}

3.4.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.5. 認証ポリシーの一覧表示

3.5.1. 説明

既存のすべての認証ポリシーを一覧表示します。

3.5.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/list
  • メソッド: POST | GET

3.5.3. リクエストボディー

該当なし

3.5.4. レスポンスボディー

3.5.4.1. 成功

{
  "status": "ok",
  "list" : [
    {
      "guid": "<auth_policy_global_unique_id#1>",
      "policyId" : "<user_defined_policy_identifier#1>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    },
    {
      "guid": "<auth_policy_global_unique_id#2>",
      "policyId" : "<user_defined_policy_identifier#2>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    },
    ...
    {
      "guid": "<auth_policy_global_unique_id#N>",
      "policyId" : "<user_defined_policy_identifier#N>"
      "policyType": "<oauth1 | oauth2 | ldap | openid>",
      "configurations": {<Config JSON Object>},
      "checkUserExists": true | false,
      "checkUserApproved": true | false
    }
  ],
  "count" : "<number_of_policies>"
}

3.5.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.6. ポリシーユーザーの一覧表示

3.6.1. 説明

認証ポリシーに関連付けられたすべてのユーザーを一覧表示します。

3.6.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/users
  • メソッド: POST

3.6.3. リクエストボディー

{
  "guid": "<policy_guid>",
}

3.6.4. レスポンスボディー

3.6.4.1. 成功

{
  "status": "ok",
  "list" : [
    {
      "userid": "<user_id>",
      "name" : "<user_name>"
      "email": "<user_email>",
    }
  ],
  "count" : "<number_of_users_for_this_policy>"
}

3.6.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.7. ユーザーのポリシーへの追加

3.7.1. 説明

ユーザーを認証ポリシーに関連付けます。

3.7.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/addusers
  • メソッド: POST

3.7.3. リクエストボディー

{
  "guid": "<policy_guid>",
  "users": ["<user_id>"]
}

3.7.4. レスポンスボディー

3.7.4.1. 成功

{
  "status": "ok"
}

3.7.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.8. ユーザーのポリシーからの削除

3.8.1. 説明

認証ポリシーに関連付けられたユーザーを削除します。

3.8.2. エンドポイント

  • URI: /box/srv/1.1/admin/authpolicy/removeusers
  • メソッド: POST

3.8.3. リクエストボディー

{
  "guid": "<policy_guid>",
  "users": ["<user_id>"]
}

3.8.4. レスポンスボディー

3.8.4.1. 成功

{
  "status": "ok"
}

3.8.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

3.9. 認証設定オプション

3.9.1. OAuth 2.0

  • clientId: 認証を要求しているクライアントを特定するために使用されるパブリックキーです。このキーは、クライアントに渡され、クライアントによって使用されます。
  • clientSecret: OAuth プロバイダーによって割り当てられるシークレットキーです。このキーはクライアントに設定されたり、クライアントに保存されることはありません。これは、プラットフォームと OAuth プロバイダー間のサーバー間通信で使用されます。

3.9.1.1. 例:

{
  "clientId": "1234567890.apps.example.com",
  "clientSecret": "Wfv8DQw80hhyaBqnW37x5R23"
}

3.9.2. LDAP

  • authmethod - LDAP サーバーに対する認証時に使用する認証メソッドです。これは以下のいずれかになります。'simple'、'DIGEST-MD5'、'CRAM-MD5'、または 'GSSAPI'。
  • url - LDAP Server url (例: "ldap://foo.example.com:389/")
  • dn: 使用する「識別名」です。DN はカンマでつなげられた相対識別名 (RDN) のシーケンスです (例: "ou=people,dc=example,dc=com")。
  • dn_prefix: 認証に使用するプレフィックスです (例: "uid" または "cn")。

3.9.2.1. 例:

{
  "authmethod" : "simple",
  "url" : "ldap://foo.example.com:389/",
  "dn": "ou=people,dc=example,dc=com",
  "dn_prefix": "cn",
}