1. OAA Runtime API
  2. Tasks
  3. Preferences

User Preferences are created/registered.

post

/oaa/runtime/preferences/v1

API to register user preferences. This API seeds user and his/her preferences in the OAA system. For data that is not cosistent/complete and error is returned. For users that already exist in the system, an error is returned. For such users combination of delete and update preferences can be used to change the preferences.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/xml ()
Root Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • 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.
  • 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.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.
Request Body - application/json ()
Root Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • 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.
  • 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.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.
Back to Top

Response

Supported Media Types

201 Response

User preferences are registerd.
Body ()
Root Schema : PreferencesResponse
Type: object
Show Source
Nested Schema : PrefAPIResponse
Type: object
Show Source
Nested Schema : schema
Type: object
Information about the user and user's challenge registration for each type of challenge factor.
Show Source
  • User's altername name that may be used in the user screens.
  • The default locale of the user. If not provided then a default value of "en_US" will be used.
  • User's display name that may be used in the user screens.
  • factorsRegistered
    Array of factor registration data for user.
  • GroupId / ApplicationId of the user whose preferences data is required. If this parameter is not present a value of "Default" is used.
  • Location of the secureImage. Example:/images/secureImage01.jpg. If system is configured to return the image path as a full URL, then following two properties need to be configured. 1.)oaa.preferences.prependBasePath = true (default is false), 2.)oaa.preferences.imageBasePath=. If system property oaa.preferences.prependBasePath = false, then only the location of the secureImage is returned as is. For set(post) only the relative path should be used and for get full URL will be returned if configured as above.
  • User preferred phrase string ex Hello World!
  • Immutable ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
  • Unique identifier of the user. May be further qualified by groupId.
Nested Schema : factorsRegistered
Type: array
Array of factor registration data for user.
Show Source
  • FactorRegData
    Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Nested Schema : FactorRegData
Type: object
Entry containing a factorName and map of keys and a values. Map of keys and values will contain attributes specific to that factor.
Show Source
  • factorAttributes
    Collection of attributes for a factor for this user.
  • 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.
  • 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.
  • Is the factor is preferred factor for the user to challenge.
Nested Schema : factorAttributes
Type: array
Collection of attributes for a factor for this user.
Show Source
Nested Schema : PrefFactorAttribute
Type: object
A map represented as an array of entries.
Show Source
Nested Schema : factorAttributeValue
Type: array
Value of factor specific attribute. Multiple values can be specified in the array.
Show Source
Nested Schema : PrefFactorAttributeValue
Type: object
Attribute value of the factor.
Show Source
  • "Date time string in the format rfc3339 sec 5.6. https://tools.ietf.org/html/rfc3339#section-5.6"
  • Indicates if the factor attribute is enabled or not. By default, it is set as true.
  • Indicates if the value of the attribute is preferred over other similar values in the array.
  • Default Value: true
    Indicates if the given attribute is validated. Some attributes do not require validation hence this field is optional.
  • Default Value: true
    Indicates if the given attribute is verified. Some attributes do not require verification hence this field is optional.
  • Friendly name of the device.
  • Value of the factor attribute.

401 Response

Unauthorized

412 Response

Invalid input
Body ()
Root Schema : PrefAPIResponse
Type: object
Show Source

500 Response

Internal server error

503 Response

Service Unavailable
Back to Top

Examples

The following example shows a sample request and response for creating user preferences. If users already exist in the system, an error is returned. For such users combination of delete and update preferences can be used to change the preferences.

cURL Command to Create User Preferences in JSON Format

curl --location --request POST '<OAAService>/oaa/runtime/preferences/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "userId": "user1",
    "groupId": "Default",
    "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
            }
          ]
        }'

Sample Response in JSON Format

{
    "preferences": {
        "userId": "user1",
        "groupId": "Default",
        "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",
                                "name": "Device1",
                                "isEnabled": true
                            }
                        ]
                    }
                ]
            },
            {
                "isPreferred": false,
                "factorName": "Email Challenge",
                "factorKey": "ChallengeEmail",
                "factorAttributes": [
                    {
                        "factorAttributeName": "email",
                        "factorAttributeValue": [
                            {
                                "value": "user1@example.com",
                                "name": "Device1",
                                "isEnabled": true
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "message": {
        "responseCode": "201",
        "responseMessage": "User preference is created."
    }
}

cURL Command to Create User Preferences in XML Format

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>Default</groupId>
<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>
'

Sample Response in XML Format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <PreferencesResponse>
     <preferences>
         <userId>user1</userId>
         <groupId>Default</groupId>
         <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>
                     <name>Device1</name>
                     <isEnabled>true</isEnabled>
                     <createTime>
                         <parseFailed>false</parseFailed>
                         <rawParam>2023-05-10T21:07:36.814Z</rawParam>
                         <dateTime>2023-05-10T21:07:36.814Z</dateTime>
                     </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>
                     <name>Device1</name>
                     <isEnabled>true</isEnabled>
                     <createTime>
                         <parseFailed>false</parseFailed>
                         <rawParam>2023-05-10T21:07:36.814Z</rawParam>
                         <dateTime>2023-05-10T21:07:36.814Z</dateTime>
                     </createTime>
                 </factorAttributeValue>
             </factorAttributes>
         </factorsRegistered>
     </preferences>
     <message>
         <responseCode>201</responseCode>
         <responseMessage>User preference is created.</responseMessage>
     </message>
 </PreferencesResponse>
Back to Top