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

ユーザー・プリファレンスが作成/登録される。

post

/oaa/runtime/preferences/v1

ユーザー・プリファレンスを登録するAPI。このAPIは、OAAシステムにユーザーとそのプリファレンスをシードします。整合性がとれていない/完全でないデータの場合、エラーが返されます。

ユーザーを一意に識別できる正規のuniqueUserIdがクライアントにある場合、正規のuniqueUserIdを使用するすべてのAPIコールで正規のuniqueUserIdを指定する必要があります。ユーザーを識別する正規のuniqueUserIdがクライアントにない場合、OAAシステムではユーザーの作成時に正規のIDが生成されます。そのユーザーに対する後続のすべてのAPIコールで、生成された正規のuniqueUserIdをそのユーザーに指定する必要があります。指定された正規のuniqueUserIdがシステムにすでに存在する場合、APIコールはHTTPレスポンス・コード412を返します。

リクエスト

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

サポートされているメディア・タイプ
リクエスト本文 - application/xml ()
ルート・スキーマ: 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
    指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
  • デバイスのわかりやすい名前。
  • ファクタ属性の値。
リクエスト本文 - application/json ()
ルート・スキーマ: 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
    指定された属性が検証されているかどうかを示します。一部の属性には検証が不要なため、このフィールドはオプションです。
  • デバイスのわかりやすい名前。
  • ファクタ属性の値。
先頭に戻る

レスポンス

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

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レスポンス

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

例

次の例は、ユーザー・プリファレンスを作成するサンプルのリクエストとレスポンスを示します。ユーザーがシステムにすでに存在する場合は、「412 事前条件が失敗しました」エラーが返されます。このようなユーザーの場合、「ユーザー・プリファレンスが切り捨てられる」と「ユーザー・プリファレンスが更新される」の組合せを使用して、ユーザー・プリファレンスを変更できます。

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

curl --location --request POST '<OAAService>/oaa/runtime/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "userId": "user1",
    "groupId": "financeapp",
    "uniqueUserId": "user1",
    "imageReference": "/u01/oracle/service/store/img001.jpg ",
    "phraseString": "Hello World!",
  "factorsRegistered": [
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "user1@example.com",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "email"
                }
              ],
              "factorKey": "ChallengeEmail",
              "isPreferred": false
            },
            {
              "factorAttributes": [
                {
                  "factorAttributeValue": [
                    {
                      "value": "secret_key",
                      "name": "Device1",
                      "isEnabled": true
                    }
                  ],
                  "factorAttributeName": "omatotpsecretkey"
                }
              ],
              "factorKey": "ChallengeOMATOTP",
              "isPreferred": false
            }
          ]
        }'

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

{
    "preferences": {
        "userId": "user1",
        "groupId": "financeapp",
        "uniqueUserId": "user1",
        "imageReference": "/u01/oracle/service/store/img001.jpg",
        "phraseString": "Hello World!",
        "factorsRegistered": [
            {
                "isPreferred": false,
                "factorName": "Oracle Mobile Authenticator",
                "factorKey": "ChallengeOMATOTP",
                "factorAttributes": [
                    {
                        "factorAttributeName": "omatotpsecretkey",
                        "factorAttributeValue": [
                            {
                                "value": "secret_key",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "Device1",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T19:57:47.262Z",
                                    "rawParam": "2025-03-07T19:57:47.262Z"
                                }
                            }
                        ]
                    }
                ]
            },
            {
                "isPreferred": false,
                "factorName": "Email Challenge",
                "factorKey": "ChallengeEmail",
                "factorAttributes": [
                    {
                        "factorAttributeName": "email",
                        "factorAttributeValue": [
                            {
                                "value": "user1@example.com",
                                "isPreferred": false,
                                "isVerified": true,
                                "isValidated": true,
                                "name": "Device1",
                                "isEnabled": true,
                                "createTime": {
                                    "parseFailed": false,
                                    "dateTime": "2025-03-07T19:57:47.261Z",
                                    "rawParam": "2025-03-07T19:57:47.261Z"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "message": {
        "responseCode": "201",
        "responseMessage": "User preference is created."
    }
}

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

curl --location --request POST '<OAAService>/oaa/runtime/preferences/v1' \
--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>financeapp</groupId>
     <uniqueUserId>user1</uniqueUserId>
<imageReference>/u01/oracle/service/store/img001.jpg </imageReference>
     <phraseString>Hello World!</phraseString>
     <factorsRegistered>
         <factorAttributes>
             <factorAttributeValue>
                 <value>user1@example.com</value>
                 <name>Device1</name>
                 <isEnabled>true</isEnabled>
             </factorAttributeValue>
             <factorAttributeName>email</factorAttributeName>
         </factorAttributes>
         <factorKey>ChallengeEmail</factorKey>
         <isPreferred>false</isPreferred>
     </factorsRegistered>
     <factorsRegistered>
         <factorAttributes>
             <factorAttributeValue>
                 <value>secret_key</value>
                 <name>Device1</name>
                 <isEnabled>true</isEnabled>
             </factorAttributeValue>
             <factorAttributeName>omatotpsecretkey</factorAttributeName>
         </factorAttributes>
         <factorKey>ChallengeOMATOTP</factorKey>
         <isPreferred>false</isPreferred>
     </factorsRegistered>
</UserPreferences>'

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <PreferencesResponse>
    <preferences>
        <userId>user1</userId>
        <groupId>financeapp1</groupId>
        <uniqueUserId>user1</uniqueUserId>
        <imageReference>/u01/oracle/service/store/img001.jpg</imageReference>
        <phraseString>Hello World!</phraseString>
        <factorsRegistered>
            <isPreferred>false</isPreferred>
            <factorName>Oracle Mobile Authenticator</factorName>
            <factorKey>ChallengeOMATOTP</factorKey>
            <factorAttributes>
                <factorAttributeName>omatotpsecretkey</factorAttributeName>
                <factorAttributeValue>
                    <value>secret_key</value>
                    <isPreferred>false</isPreferred>
                    <isVerified>true</isVerified>
                    <isValidated>true</isValidated>
                    <name>Device1</name>
                    <isEnabled>true</isEnabled>
                    <createTime>
                        <dateTime>2025-03-07T20:37:40.988Z</dateTime>
                        <parseFailed>false</parseFailed>
                        <rawParam>2025-03-07T20:37:40.988Z</rawParam>
                    </createTime>
                </factorAttributeValue>
            </factorAttributes>
        </factorsRegistered>
        <factorsRegistered>
            <isPreferred>false</isPreferred>
            <factorName>Email Challenge</factorName>
            <factorKey>ChallengeEmail</factorKey>
            <factorAttributes>
                <factorAttributeName>email</factorAttributeName>
                <factorAttributeValue>
                    <value>user1@example.com</value>
                    <isPreferred>false</isPreferred>
                    <isVerified>true</isVerified>
                    <isValidated>true</isValidated>
                    <name>Device1</name>
                    <isEnabled>true</isEnabled>
                    <createTime>
                        <dateTime>2025-03-07T20:37:40.987Z</dateTime>
                        <parseFailed>false</parseFailed>
                        <rawParam>2025-03-07T20:37:40.987Z</rawParam>
                    </createTime>
                </factorAttributeValue>
            </factorAttributes>
        </factorsRegistered>
    </preferences>
    <message>
        <responseCode>201</responseCode>
        <responseMessage>User preference is created.</responseMessage>
    </message>
</PreferencesResponse>
先頭に戻る