OAAランタイムAPI

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

put

/oaa/runtime/preferences/v1/sync

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

リクエスト

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

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

application/xml
application/json

ルート・スキーマ: schema

型: object

プリファレンスを同期化するためのリクエスト・オブジェクト。

ソースの表示

attributes: array attributes

ユーザーの属性
factorkey: string

同期されるファクタ・キー。これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ChallengeEmail、ChallengeSMS、ChallengeOMATOTP、ChallangeYOTPおよびChallengeFIDO2です。
groupId: string

ユーザーのGroupId/ApplicationId。この値が存在しない場合、Defaultが使用されます。
uniqueUserId: string

外部システムのユーザーの不変ID。これが存在する場合は、userId + groupIdの組合せよりも優先されます。
userId: string

ユーザーの一意の識別子。さらにgroupIdで修飾できます。

{
    "type":"object",
    "properties":{
        "userId":{
            "type":"string",
            "description":"Unique identifier of the user. May be further qualified by groupId."
        },
        "groupId":{
            "type":"string",
            "description":"GroupId / ApplicationId of the user. If this value is not present then Default will be used."
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        },
        "factorkey":{
            "type":"string",
            "description":"The factor key for which it will be synced. This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. Examples are ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallangeYOTP and ChallengeFIDO2."
        },
        "attributes":{
            "type":"array",
            "description":"Attributes of the user",
            "items":{
                "$ref":"#/components/schemas/KeyValPair"
            }
        }
    },
    "description":"Request object for synchronizing the preferences."
}

ネストされたスキーマ: attributes

型: array

ユーザーの属性

ソースの表示

配列: object KeyValPair

一般的に使用できるキーと値のペア。

{
    "type":"array",
    "description":"Attributes of the user",
    "items":{
        "$ref":"#/components/schemas/KeyValPair"
    }
}

ネストされたスキーマ: KeyValPair

型: object

一般的に使用できるキーと値のペア。

ソースの表示

key(required): string

関連値のフェッチに使用できるキー。
value(required): object value

関連付けられた値。

{
    "required":[
        "key",
        "value"
    ],
    "type":"object",
    "properties":{
        "key":{
            "type":"string",
            "description":"Key that can be used to fetch the related value."
        },
        "value":{
            "type":"object",
            "description":"associated value."
        }
    },
    "description":"Key-value pair which can be used generically."
}

ネストされたスキーマ: value

型: object

レスポンス

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

application/xml
application/json
text/plain

201レスポンス

ユーザー・プリファレンスが同期されました。

ルート・スキーマ: PreferencesResponse

型: object

ソースの表示

message: object PrefAPIResponse
preferences: object schema

各タイプのチャレンジ・ファクタに対するユーザーおよびユーザーのチャレンジの登録に関する情報。

{
    "type":"object",
    "properties":{
        "preferences":{
            "$ref":"#/components/schemas/UserPreferences"
        },
        "message":{
            "$ref":"#/components/schemas/PrefAPIResponse"
        }
    }
}

ネストされたスキーマ: PrefAPIResponse

型: object

ソースの表示

responseCode: string
responseMessage: string

{
    "type":"object",
    "properties":{
        "responseCode":{
            "type":"string"
        },
        "responseMessage":{
            "type":"string"
        }
    }
}

ネストされたスキーマ: schema

型: object

各タイプのチャレンジ・ファクタに対するユーザーおよびユーザーのチャレンジの登録に関する情報。

ソースの表示

alternateName: string

ユーザー画面で使用できるユーザーの代替名。
defaultlocale: string

ユーザーのデフォルト・ロケール。指定しない場合は、デフォルト値の「en_US」が使用されます。
displayName: string

ユーザー画面で使用できるユーザーの表示名。
factorsRegistered: array factorsRegistered

ユーザーのファクタ登録データの配列。
groupId: string

プリファレンス・データが必要なユーザーのGroupId/ApplicationId。このパラメータが存在しない場合、"Default"という値が使用されます。
imageReference: string

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が返されます。
phraseString: string

ユーザー優先フレーズ文字列(例: Hello World!)
uniqueUserId: string

外部システムのユーザーの不変ID。これが存在する場合は、userId + groupIdの組合せよりも優先されます。
userId: string

ユーザーの一意の識別子。さらにgroupIdで修飾できます。

{
    "required":[
        "userId|groupId"
    ],
    "type":"object",
    "properties":{
        "userId":{
            "type":"string",
            "description":"Unique identifier of the user. May be further qualified by groupId."
        },
        "groupId":{
            "type":"string",
            "description":"GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of \"Default\" is used."
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        },
        "defaultlocale":{
            "type":"string",
            "description":"The default locale of the user. If not provided then a default value of \"en_US\" will be used."
        },
        "displayName":{
            "type":"string",
            "description":"User's display name that may be used in the user screens."
        },
        "alternateName":{
            "type":"string",
            "description":"User's altername name that may be used in the user screens."
        },
        "imageReference":{
            "type":"string",
            "description":"Location of the secureImage. Example:/images/secureImage01.jpg.\nIf system is configured to return the image path as a full URL, then following two properties need to be configured. \n1.)oaa.preferences.prependBasePath = true (default is false),\n2.)oaa.preferences.imageBasePath=<base path of the URL>.\nIf system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is.\nFor set(post) only the relative path should be used and for get full URL will be returned if configured as above.\n"
        },
        "phraseString":{
            "type":"string",
            "description":"User preferred phrase string ex Hello World!"
        },
        "factorsRegistered":{
            "type":"array",
            "description":"Array of factor registration data for user.",
            "items":{
                "$ref":"#/components/schemas/FactorRegData"
            }
        }
    },
    "description":"Information about the user and user's challenge registration for each type of challenge factor."
}

ネストされたスキーマ: factorsRegistered

型: array

ユーザーのファクタ登録データの配列。

ソースの表示

配列: object FactorRegData

factorNameおよびキーと値のマップを含むエントリ。キーと値のマップには、そのファクタに固有の属性が含まれます。

{
    "type":"array",
    "description":"Array of factor registration data for user.",
    "items":{
        "$ref":"#/components/schemas/FactorRegData"
    }
}

ネストされたスキーマ: FactorRegData

型: object

factorNameおよびキーと値のマップを含むエントリ。キーと値のマップには、そのファクタに固有の属性が含まれます。

ソースの表示

factorAttributes: array factorAttributes

このユーザーのファクタの属性のコレクション。
factorKey: string

ファクタのキー。これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ChallengeEmail、ChallengeSMS、ChallengeOMATOTP、ChallangeYOTPおよびChallengeFIDO2です。
factorName: string

これは、OAAシステムで使用可能なファクタの1つにマップする必要がある名前です。これは、challenge.type.enumの列挙名の1つである必要があります。たとえば、ファクタが電子メールの場合、factorNameはEmail Challengeです。例として、Email Challenge、SMS Challenge、OMA TOTP Challenge、Yubikey OTP Challange、FIDO2 Challengeがあります。
isPreferred: boolean

ファクタが、ユーザーがチャレンジする優先ファクタかどうか。

{
    "required":[
        "factorName|factorAttributes"
    ],
    "type":"object",
    "properties":{
        "isPreferred":{
            "type":"boolean",
            "description":"Is the factor is preferred factor for the user to challenge."
        },
        "factorName":{
            "type":"string",
            "description":"This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum.  For Example if factor is email then factorName should be Email Challenge. Examples are Email Challenge, SMS Challenge, OMA TOTP Challenge, Yubikey OTP Challange and FIDO2 Challenge."
        },
        "factorKey":{
            "type":"string",
            "description":"Key of the factor. This is the name that should map to one of the available factors in the OAA system. This should be one of the enum name in challenge.type.enum. Examples are ChallengeEmail, ChallengeSMS, ChallengeOMATOTP, ChallangeYOTP and ChallengeFIDO2."
        },
        "factorAttributes":{
            "type":"array",
            "description":"Collection of attributes for a factor for this user.",
            "items":{
                "$ref":"#/components/schemas/PrefFactorAttribute"
            }
        }
    },
    "description":"Entry containing a factorName and map of keys and a values.  Map of keys and values will contain attributes specific to that factor."
}

ネストされたスキーマ: factorAttributes

型: array

このユーザーのファクタの属性のコレクション。

ソースの表示

配列: object PrefFactorAttribute

エントリの配列として表されるマップ。

{
    "type":"array",
    "description":"Collection of attributes for a factor for this user.",
    "items":{
        "$ref":"#/components/schemas/PrefFactorAttribute"
    }
}

ネストされたスキーマ: PrefFactorAttribute

型: object

エントリの配列として表されるマップ。

ソースの表示

factorAttributeName: string

ファクタ固有属性の名前。
factorAttributeValue: array factorAttributeValue

ファクタ固有属性の値。配列に複数の値を指定できます。

{
    "type":"object",
    "properties":{
        "factorAttributeName":{
            "type":"string",
            "description":"Name of factor specific attribute."
        },
        "factorAttributeValue":{
            "type":"array",
            "description":"Value of factor specific attribute. Multiple values can be specified in the array.",
            "items":{
                "$ref":"#/components/schemas/PrefFactorAttributeValue"
            }
        }
    },
    "description":"A map represented as an array of entries."
}

ネストされたスキーマ: factorAttributeValue

型: array

ファクタ固有属性の値。配列に複数の値を指定できます。

ソースの表示

配列: object PrefFactorAttributeValue

ファクタの属性値。

{
    "type":"array",
    "description":"Value of factor specific attribute. Multiple values can be specified in the array.",
    "items":{
        "$ref":"#/components/schemas/PrefFactorAttributeValue"
    }
}

ネストされたスキーマ: PrefFactorAttributeValue

型: object

ファクタの属性値。

ソースの表示

createTime: string (date-time)

"rfc3339セクション5.6の形式の日時文字列。https://tools.ietf.org/html/rfc3339#section-5.6"
isEnabled: boolean

ファクタ属性が有効どうかを示します。デフォルトでは、trueに設定されています。
isPreferred: boolean

属性の値が配列の他の同様の値よりも優先されるかどうかを示します。
isValidated: boolean

デフォルト値: true

指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
isVerified: boolean

デフォルト値: true

指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
name: string

デバイスのわかりやすい名前。
value: string

ファクタ属性の値。

{
    "required":[
        "value|name"
    ],
    "type":"object",
    "properties":{
        "value":{
            "type":"string",
            "description":"Value of the factor attribute."
        },
        "isPreferred":{
            "type":"boolean",
            "description":"Indicates if the value of the attribute is preferred over other similar values in the array."
        },
        "isVerified":{
            "type":"boolean",
            "description":"Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.",
            "default":true
        },
        "isValidated":{
            "type":"boolean",
            "description":"Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.",
            "default":true
        },
        "name":{
            "type":"string",
            "description":"Friendly name of the device."
        },
        "isEnabled":{
            "type":"boolean",
            "description":"Indicates if the factor attribute is enabled or not. By default, it is set as true."
        },
        "createTime":{
            "$ref":"#/components/schemas/DateTime"
        }
    },
    "description":"Attribute value of the factor."
}

401レスポンス

未認可

412レスポンス

無効な入力

ルート・スキーマ: PrefAPIResponse

型: object

ソースの表示

responseCode: string
responseMessage: string

{
    "type":"object",
    "properties":{
        "responseCode":{
            "type":"string"
        },
        "responseMessage":{
            "type":"string"
        }
    }
}

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>

先頭に戻る