1. OAAランタイムAPI
  2. タスク
  3. プリファレンス

ユーザーのプリファレンスを同期する

put

/oaa/runtime/preferences/v1/sync

ユーザー・プリファレンスが、リクエストに存在するデータと同期されます。OAAには、ファクタとその必須情報とともにユーザー情報がすでに存在している必要があります。ファクタがすでに登録されており、同じデータが存在する場合、データはオーバーライドされます。ただし、既存のファクタに新しいデータが指定された場合、このAPIは指定された"name"パラメータで新しいデバイスを追加します。また、わかりやすい名前がない場合、登録されるデバイスの新しい名前が生成されます。その他のパラメータには、デバイスのisEnabled、isPreferredおよびisVerifiedなどがあり、ブール値として指定できます。

リクエスト

この操作にはリクエスト・パラメータはありません。

サポートされているメディア・タイプ
リクエスト本文 - application/xml ()
ルート・スキーマ: schema
型: object
プリファレンスを同期化するためのリクエスト・オブジェクト。
ソースの表示
  • attributes
    ユーザーの属性
  • 同期されるファクタ・キー。これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ChallengeEmail、ChallengeSMS、ChallengeOMATOTP、ChallangeYOTPおよびChallengeFIDO2です。
  • ユーザーのGroupId/ApplicationId。この値が存在しない場合、Defaultが使用されます。
  • 外部システムのユーザーの不変ID。これが存在する場合は、userId + groupIdの組合せよりも優先されます。
  • ユーザーの一意の識別子。さらにgroupIdで修飾できます。
ネストされたスキーマ: attributes
型: array
ユーザーの属性
ソースの表示
ネストされたスキーマ: KeyValPair
型: object
一般的に使用できるキーと値のペア。
ソースの表示
ネストされたスキーマ: value
型: object
関連付けられた値。
リクエスト本文 - application/json ()
ルート・スキーマ: schema
型: object
プリファレンスを同期化するためのリクエスト・オブジェクト。
ソースの表示
  • attributes
    ユーザーの属性
  • 同期されるファクタ・キー。これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ChallengeEmail、ChallengeSMS、ChallengeOMATOTP、ChallangeYOTPおよびChallengeFIDO2です。
  • ユーザーのGroupId/ApplicationId。この値が存在しない場合、Defaultが使用されます。
  • 外部システムのユーザーの不変ID。これが存在する場合は、userId + groupIdの組合せよりも優先されます。
  • ユーザーの一意の識別子。さらにgroupIdで修飾できます。
ネストされたスキーマ: attributes
型: array
ユーザーの属性
ソースの表示
ネストされたスキーマ: KeyValPair
型: object
一般的に使用できるキーと値のペア。
ソースの表示
ネストされたスキーマ: value
型: object
関連付けられた値。
先頭に戻る

レスポンス

サポートされているメディア・タイプ

201レスポンス

ユーザー・プリファレンスが同期されました。
本文()
ルート・スキーマ: PreferencesResponse
型: object
ソースの表示
ネストされたスキーマ: PrefAPIResponse
型: object
ソースの表示
ネストされたスキーマ: schema
型: object
各タイプのチャレンジ・ファクタに対するユーザーおよびユーザーのチャレンジの登録に関する情報。
ソースの表示
  • ユーザー画面で使用できるユーザーの代替名。
  • ユーザーのデフォルト・ロケール。指定しない場合は、デフォルト値の「en_US」が使用されます。
  • ユーザー画面で使用できるユーザーの表示名。
  • factorsRegistered
    ユーザーのファクタ登録データの配列。
  • プリファレンス・データが必要なユーザーのGroupId/ApplicationId。このパラメータが存在しない場合、"Default"という値が使用されます。
  • secureImageの場所。Example:/images/secureImage01.jpg.イメージ・パスを完全なURLとして返すようにシステムが構成されている場合、次の2つのプロパティを構成する必要があります。1.)oaa.preferences.prependBasePath = true (デフォルトはfalse)、2.)oaa.preferences.imageBasePath=。システム・プロパティoaa.preferences.prependBasePath = falseの場合、secureImageの場所のみがそのまま返されます。set (post)の場合は、相対パスのみが使用され、getの場合は、前述のように設定されていれば完全なURLが返されます。
  • ユーザー優先フレーズ文字列(例: Hello World!)
  • 外部システムのユーザーの不変ID。これが存在する場合は、userId + groupIdの組合せよりも優先されます。
  • ユーザーの一意の識別子。さらにgroupIdで修飾できます。
ネストされたスキーマ: factorsRegistered
型: array
ユーザーのファクタ登録データの配列。
ソースの表示
  • FactorRegData
    factorNameおよびキーと値のマップを含むエントリ。キーと値のマップには、そのファクタに固有の属性が含まれます。
ネストされたスキーマ: FactorRegData
型: object
factorNameおよびキーと値のマップを含むエントリ。キーと値のマップには、そのファクタに固有の属性が含まれます。
ソースの表示
  • factorAttributes
    このユーザーのファクタの属性のコレクション。
  • ファクタのキー。これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ChallengeEmail、ChallengeSMS、ChallengeOMATOTP、ChallangeYOTPおよびChallengeFIDO2です。
  • これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ファクタが電子メールの場合、factorNameはEmail Challengeです。例として、Email Challenge、SMS Challenge、OMA TOTP Challenge、Yubikey OTP Challange、FIDO2 Challengeがあります。
  • ファクタが、ユーザーがチャレンジする優先ファクタかどうか。
ネストされたスキーマ: factorAttributes
型: array
このユーザーのファクタの属性のコレクション。
ソースの表示
ネストされたスキーマ: PrefFactorAttribute
型: object
エントリの配列として表されるマップ。
ソースの表示
ネストされたスキーマ: factorAttributeValue
型: array
ファクタ固有属性の値。配列に複数の値を指定できます。
ソースの表示
ネストされたスキーマ: PrefFactorAttributeValue
型: object
ファクタの属性値。
ソースの表示
  • "rfc3339セクション5.6の形式の日時文字列。https://tools.ietf.org/html/rfc3339#section-5.6"
  • ファクタ属性が有効どうかを示します。デフォルトでは、trueに設定されています。
  • 属性の値が配列の他の同様の値よりも優先されるかどうかを示します。
  • デフォルト値: true
    指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
  • デフォルト値: true
    指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
  • デバイスのわかりやすい名前。
  • ファクタ属性の値。

401レスポンス

未認可

412レスポンス

無効な入力
本文()
ルート・スキーマ: PrefAPIResponse
型: object
ソースの表示

500レスポンス

内部サーバー・エラー

503レスポンス

サービス使用不可
先頭に戻る

例

次の例は、ユーザーのプリファレンスを同期するためのリクエストとレスポンスのサンプルを示しています。

JSON形式でユーザー・プリファレンスを同期するcURLコマンド

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1/sync' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
  "userId": "user1",
  "groupId": "Default",
  "factorKey": "ChallengeEmail",
  "attributes": [
 {"key": "name",  "value": "Device1"     }
,
 {"key": "email",  "value": "user1@example.com"     }
,
 {"key": "isEnabled",  "value": "true"     }
,
 {"key": "isValidated", "value": "true"     }
,
 {"key": "isPreferred", "value": "false"     }
,
{"key": "attr1", "value": "value1"     }
,
{"key": "attr2", "value": "val2"     }
  ]
}'

JSON形式のサンプル・レスポンス

{
  "preferences": {
    "userId": "user1",
    "groupId": "Default",
    "factorsRegistered": [
      {
        "isPreferred": false,
        "factorName": "Email Challenge",
        "factorKey": "ChallengeEmail",
        "factorAttributes": [
          {
            "factorAttributeName": "email",
            "factorAttributeValue": [
              {
                "value": "user1@example.com",
                "name": "Device1",
                "isEnabled": true,
                "isValidated": true,
                "isPreferred": false
              }
            ]
          },
          {
            "factorAttributeName": "Device1",
            "factorAttributeValue": [
              {
                "value": "value1",
                "name": "attr1",
                "isEnabled": true,
                "isValidated": true,
                "isPreferred": false
              },
              {
                "value": "value2",
                "name": "attr2",
                "isEnabled": true,
                "isValidated": true,
                "isPreferred": false
              }
            ]
          }
        ]
      }
    ]
  },
  "message": {
    "responseCode": "201",
    "responseMessage": "User preference is created."
  }
}

XML形式でユーザー・プリファレンスを同期するcURLコマンド

curl --location --request PUT '<OAAService>/oaa/runtime/preferences/v1/sync' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '<?xml version="1.0" encoding="UTF-8" ?>
<UserPreferences>
  <userId>user1</userId>
  <groupId>Default</groupId>
  <factorKey>ChallengeEmail</factorKey>
  <attributes>
    <key>name</key>
    <value>Device1</value>
  </attributes>
  <attributes>
    <key>email</key>
    <value>user1@example.com</value>
  </attributes>
  <attributes>
    <key>isEnabled</key>
    <value>true</value>
  </attributes>
  <attributes>
    <key>isValidated</key>
    <value>true</value>
  </attributes>
  <attributes>
    <key>isPreferred</key>
    <value>false</value>
  </attributes>
  <attributes>
    <key>attr1</key>
    <value>value1</value>
  </attributes>
  <attributes>
    <key>attr2</key>
    <value>val2</value>
  </attributes>
</UserPreferences>'

XML形式のサンプル・レスポンス

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PreferencesResponse>
  <preferences>
    <userId>user1</userId>
    <groupId>Default</groupId>
    <factorsRegistered>
      <isPreferred>false</isPreferred>
      <factorName>Email Challenge</factorName>
      <factorKey>ChallengeEmail</factorKey>
      <factorAttributes>
        <factorAttributeName>email</factorAttributeName>
        <factorAttributeValue>
          <value>user1@example.com</value>
          <name>Device1</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
      </factorAttributes>
      <factorAttributes>
        <factorAttributeName>Device1</factorAttributeName>
        <factorAttributeValue>
          <value>value1</value>
          <name>attr1</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
        <factorAttributeValue>
          <value>value2</value>
          <name>attr2</name>
          <isEnabled>true</isEnabled>
          <isValidated>true</isValidated>
          <isPreferred>false</isPreferred>
        </factorAttributeValue>
      </factorAttributes>
    </factorsRegistered>
  </preferences>
  <message>
    <responseCode>201</responseCode>
    <responseMessage>User preference is created.</responseMessage>
  </message>
</PreferencesResponse>
先頭に戻る