1. OAA Runtime API
  2. Tasks
  3. Preferences

Synchronize the preferences of the user

put

/oaa/runtime/preferences/v1/sync

User preferences will be synchronized with the data present in the request. OAA must already have user info present along with factor and its required info. If factor is already registered and same data in present then the data will be overriden. However, if new data is provided for the existing factor, then, this API will add new device with the given "name" parameter. Also in case of missing friendly name, it will generate a new name for the device being registered. Other parameters include isEnabled, isPreferred and isVerified for a device can also be provided as boolean values.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/xml ()
Root Schema : schema
Type: object
Request object for synchronizing the preferences.
Show Source
  • attributes
    Attributes of the user
  • 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.
  • GroupId / ApplicationId of the user. If this value is not present then Default will be used.
  • 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 : attributes
Type: array
Attributes of the user
Show Source
Nested Schema : KeyValPair
Type: object
Key-value pair which can be used generically.
Show Source
Nested Schema : value
Type: object
associated value.
Request Body - application/json ()
Root Schema : schema
Type: object
Request object for synchronizing the preferences.
Show Source
  • attributes
    Attributes of the user
  • 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.
  • GroupId / ApplicationId of the user. If this value is not present then Default will be used.
  • 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 : attributes
Type: array
Attributes of the user
Show Source
Nested Schema : KeyValPair
Type: object
Key-value pair which can be used generically.
Show Source
Nested Schema : value
Type: object
associated value.
Back to Top

Response

Supported Media Types

201 Response

User preferences are synchronized.
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 synchronizing the preferences of the user.

cURL Command to Synchronize the User Preferences in JSON Format

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"     }
  ]
}'

Sample Response in JSON Format

{
  "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."   }
}

cURL Command to Synchronize the User Preferences in XML Format

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>'

Sample Response in XML Format

<?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>
Back to Top