OAA Runtime API

Associate and update questions with answers specific to user.

put

/oaa-kba/runtime/kba/v1/questions

The user is challenged with the active questions. Questions associated with users will be used during authentication to verify the user's identity. The answers provided are stored as the user private answer for the question. The user identity data must be present in the body of the put request. The user associations as well as the user answers with the provided questions alone will be updated. Questions with Active flag set to true are considered active and may be used for challenging the user subsequently. The user needs to activate atleast one question per each choice of questions. The user may activate more than one question per choice based on the system property challenge.question.registration.maxcount.from.each.groups. By default, the user may be challenged by any one of the active questions during authentication. Since 12.2.1.4.1-20230630, this behavior may be overridden by the system property oracle.security.oaa.kba.challenge.number if the system has been configured with adequate active questions. If the OAA server is configured to challenge the user with multiple questions, the generated challenge will contain the multiple challenges as a string that contains the list of challenges separated by the value of the system property oracle.security.oaa.kba.challenge.separator. When the response to the challenge is presented to the OAA server, the response is also expected to be seperated by the same separator. By default, this separator is declared as '|' character. This may be overridden with any other character, or combination of characters that should not be used in the challenge or the response.

Request

There are no request parameters for this operation.

Supported Media Types

application/xml
application/json

Root Schema : schema

Type: object

Show Source

choices: array choices
user: object User

User related data. userid is mandatory parameter. API call should be made with canonical uniqueUserId along with userid and group. If userid and group combination is unique, the call can also be made using userid and group.

{
    "type":"object",
    "required":[
        "categories"
    ],
    "properties":{
        "user":{
            "$ref":"#/components/schemas/User"
        },
        "choices":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Choice"
            }
        }
    }
}

Nested Schema : choices

Type: array

Show Source

Array of: object Choice

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Choice"
    }
}

Nested Schema : User

Type: object

User related data. userid is mandatory parameter. API call should be made with canonical uniqueUserId along with userid and group. If userid and group combination is unique, the call can also be made using userid and group.

Show Source

group: string

Default Value: Default

Group name to which user belongs
uniqueUserId: string

Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
userid: string

Unique username in group.

{
    "type":"object",
    "description":"User related data. userid is mandatory parameter.  API call should be made with canonical uniqueUserId along with userid and group.  If userid and group combination is unique, the call can also be made using userid and group.\n",
    "properties":{
        "userid":{
            "type":"string",
            "description":"Unique username in group."
        },
        "group":{
            "type":"string",
            "description":"Group name to which user belongs",
            "default":"Default"
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        }
    }
}

Nested Schema : Choice

Type: object

Show Source

questions: array questions

{
    "type":"object",
    "properties":{
        "questions":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Question"
            }
        }
    }
}

Nested Schema : questions

Type: array

Show Source

Array of: object Question

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Question"
    }
}

Nested Schema : Question

Type: object

Show Source

active: boolean

Default Value: true

If true, this question is associated with user and will be used to challenge the user.
answer: string

User's answer to question associated with user
question: string

question text associated with user
questionId: integer (int64)

unique identifier of question associated with user

{
    "type":"object",
    "required":[
        "questionid"
    ],
    "properties":{
        "questionId":{
            "description":"unique identifier of question associated with user",
            "type":"integer",
            "format":"int64"
        },
        "question":{
            "description":"question text associated with user",
            "type":"string"
        },
        "answer":{
            "description":"User's answer to question associated with user",
            "type":"string"
        },
        "active":{
            "description":"If true, this question is associated with user and will be used to challenge the user.",
            "type":"boolean",
            "default":"true"
        }
    }
}

Root Schema : schema

Type: object

Show Source

choices: array choices
user: object User

User related data. userid is mandatory parameter. API call should be made with canonical uniqueUserId along with userid and group. If userid and group combination is unique, the call can also be made using userid and group.

{
    "type":"object",
    "required":[
        "categories"
    ],
    "properties":{
        "user":{
            "$ref":"#/components/schemas/User"
        },
        "choices":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Choice"
            }
        }
    }
}

Nested Schema : choices

Type: array

Show Source

Array of: object Choice

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Choice"
    }
}

Nested Schema : User

Type: object

Show Source

group: string

Default Value: Default

Group name to which user belongs
uniqueUserId: string

Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination.
userid: string

Unique username in group.

{
    "type":"object",
    "description":"User related data. userid is mandatory parameter.  API call should be made with canonical uniqueUserId along with userid and group.  If userid and group combination is unique, the call can also be made using userid and group.\n",
    "properties":{
        "userid":{
            "type":"string",
            "description":"Unique username in group."
        },
        "group":{
            "type":"string",
            "description":"Group name to which user belongs",
            "default":"Default"
        },
        "uniqueUserId":{
            "type":"string",
            "description":"Canonical ID of the user in the external systems. If this is present, then it takes precedence over userId + groupId combination."
        }
    }
}

Nested Schema : Choice

Type: object

Show Source

questions: array questions

{
    "type":"object",
    "properties":{
        "questions":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/Question"
            }
        }
    }
}

Nested Schema : questions

Type: array

Show Source

Array of: object Question

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Question"
    }
}

Nested Schema : Question

Type: object

Show Source

active: boolean

Default Value: true

If true, this question is associated with user and will be used to challenge the user.
answer: string

User's answer to question associated with user
question: string

question text associated with user
questionId: integer (int64)

unique identifier of question associated with user

{
    "type":"object",
    "required":[
        "questionid"
    ],
    "properties":{
        "questionId":{
            "description":"unique identifier of question associated with user",
            "type":"integer",
            "format":"int64"
        },
        "question":{
            "description":"question text associated with user",
            "type":"string"
        },
        "answer":{
            "description":"User's answer to question associated with user",
            "type":"string"
        },
        "active":{
            "description":"If true, this question is associated with user and will be used to challenge the user.",
            "type":"boolean",
            "default":"true"
        }
    }
}

Response

Supported Media Types

application/json

204 Response

Success

401 Response

Unauthorized

Root Schema : KBAAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

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

415 Response

Content-Type header value is invalid or not accepted on the server

Root Schema : KBAAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

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

422 Response

Unprocessable Entity. Failed to update user question data.

Root Schema : KBAAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

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

500 Response

Server error.

Root Schema : KBAAPIResponse

Type: object

Show Source

responseCode: string
responseMessage: string

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

Examples

The following example shows a sample request and response for verifying a user's identity based on private information of user.

cURL Command to Verify a User's Identity in JSON Format

curl --location --request PUT '<OAAService>/oaa-kba/runtime/kba/v1/questions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '{
    "user": {
        "userid": "user1",
        "group": "financeapp",
        "uniqueUserId": "22a29071-16f2-4b69-a94c-73be672e34eb"
    },
    "choices": [
        {
            "questions": [
                {
                    "questionId": 2,
                    "question": "What was your father'\''s profession when you were born?",
                    "active": true,
                    "answer": "born"
                }
            ]
        },
        {
            "questions": [
                {
                    "questionId": 87,
                    "question": "What was the name of your favorite childhood musical group?",
                    "active": true,
                    "answer": "group"
                }
            ]
        },
        {
            "questions": [
                {
                    "questionId": 60,
                    "question": "What is your best friend'\''s birthday?",
                    "active": true,
                    "answer": "birthday"
                }
            ]
        }
    ]
}'

Sample Response in JSON Format

204 No Content

cURL Command to Verify a User's Identity in XML Format

curl --location --request PUT '<OAAService>/oaa-kba/runtime/kba/v1/questions' \
--header 'Content-Type: application/xml' \
--header 'Accept: application/xml' \
--header 'Authorization: Basic <Base64Encoded(<username>:<password>)>' \
--data '<?xml version="1.0" encoding="UTF-8" ?>
<UserQuestion>
<user>
  <userid>user1</userid>
  <group>financeapp</group>
  <uniqueUserId>22a29071-16f2-4b69-a94c-73be672e34eb</uniqueUserId>
</user>
<choices>
    <questions>
            <questionId>2</questionId>
            <question>What was your father's profession when you were born?</question>
            <answer>born</answer>
            <active>true</active>
    </questions>
	<questions>
            <questionId>87</questionId>
            <question>What was the name of your favorite childhood musical group?</question>
            <answer>born</answer>
            <active>true</active>
    </questions>
	<questions>
            <questionId>60</questionId>
            <question>What is your best friend's birthday?</question>
            <answer>birthday</answer>
            <active>true</active>
    </questions>
</choices>
</UserQuestion>

Sample Response in XML Format

204 No Content