Automated commit 'Merge pull request #1647 from sailpoint/saurabh/ISCARP-13782

ISCARP-13782 / Add documentation for CC challenge APIs replacements in MFA' by github action: 8742380269

idn/beta/paths/mfa-kba-authenticate.yaml

@@ -12,20 +12,20 @@ post:
     content:
       application/json:
         schema:
-              $ref: "../schemas/KbaAnswerRequest.yaml"
+          type: array
+          items:
+            $ref: "../schemas/KbaAnswerRequestItem.yaml"
         example:
-              {"answers": [
+          [
             {
-                  "questionId": "089899f13a8f4da7824996191587bab9",
-                  "answer": "Your answer"
+              "id": "173423",
+              "answer": "822cd15d6c15aa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a0859a2fea34"
             },
             {
-                  "questionId": "067899f13a8f4da7824996191587bab9",
-                  "answer": "Your answer1"
+              "id": "c54fee53-2d63-4fc5-9259-3e93b9994135",
+              "answer": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
             }
           ]
-              }
-
   responses:
     "200":
       description: KBA authenticated status.

idn/beta/paths/mfa-kba-config-answers.yaml

@@ -0,0 +1,69 @@
+post:
+  operationId: setMFAKBAConfig
+  tags:
+    - MFA Configuration
+  summary: Set MFA KBA configuration
+  description: >-
+    This API sets answers to challenge questions. 
+    Any configured questions omitted from the request are removed from user KBA configuration.
+    
+    A token with USER authority is required to call this API.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: "../schemas/KbaAnswerRequestItem.yaml"
+        example:
+          [
+            {
+              "id": "173423",
+              "answer": "822cd15d6c15aa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a0859a2fea34"
+            },
+            {
+              "id": "c54fee53-2d63-4fc5-9259-3e93b9994135",
+              "answer": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
+            }
+          ]
+  security:
+    - UserContextAuth: [idn:mfa-kba:authenticate]
+  responses:
+    "200":
+      description: The new KBA configuration for the user.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "../schemas/KbaAnswerResponseItem.yaml"
+          example:
+            [
+              {
+                "id": "143cfd3b-c23f-426b-ae5f-d3db06fa5919",
+                "question": "[{\"text\":\"Nouvelle question MFA -1 ?\",\"locale\":\"fr\"},{\"text\":\"MFA new question -1 ?\",\"locale\":\"\"}]",
+                "hasAnswer": false
+              },
+              {
+                "id": "173421",
+                "question": "[{\"text\":\"What is your alphanumeric PIN?\",\"locale\":\"\"}]",
+                "hasAnswer": true
+              },
+              {
+                "id": "c54fee53-2d63-4fc5-9259-3e93b9994135",
+                "question": "[{\"text\":\"Nouvelle question MFA - 2 ?\",\"locale\":\"fr\"},{\"text\":\"MFA new question - 2 ?\",\"locale\":\"\"}]",
+                "hasAnswer": true
+              }
+            ]
+    "400":
+      $ref: "../../v3/responses/400.yaml"
+    "401":
+      $ref: "../../v3/responses/401.yaml"
+    "403":
+      $ref: "../../v3/responses/403.yaml"
+    "429":
+      $ref: "../../v3/responses/429.yaml"
+    "500":
+      $ref: "../../v3/responses/500.yaml"
+

idn/beta/paths/mfa-kba-config.yaml

@@ -0,0 +1,56 @@
+get:
+  operationId: getMFAKbaConfig
+  tags:
+    - MFA Configuration
+  summary: Configuration of KBA MFA method
+  description: >-
+    This API returns the KBA configuration for MFA.
+    A token with USER or ORG_ADMIN authority is required to call this API.
+  parameters:
+    - in: query
+      name: allLanguages
+      required: false
+      schema:
+        type: boolean
+      description: >-
+        Indicator whether the question text should be returned in all configured languages
+           * If true, the question text is returned in all languages that it is configured in.
+           * If false, the question text is returned in the user locale if available, else for the default locale. 
+           * If not passed, it behaves the same way as passing this parameter as false
+      example: allLanguages=true
+  security:
+    - UserContextAuth: [idn:mfa-kba:read]
+  responses:
+    "200":
+      description: The configuration for KBA MFA method.
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: "../schemas/KbaQuestion.yaml"
+          example:
+            [
+              {
+                "id": "143cfd3b-c23f-426b-ae5f-d3db06fa5919",
+                "text": "MFA new question -1 ?",
+                "hasAnswer": false,
+                "numAnswers": 0
+              },
+              {
+                "id": "173421",
+                "text": "What is your alphanumeric PIN?",
+                "hasAnswer": false,
+                "numAnswers": 3
+              }
+            ]
+    "400":
+      $ref: "../../v3/responses/400.yaml"
+    "401":
+      $ref: "../../v3/responses/401.yaml"
+    "403":
+      $ref: "../../v3/responses/403.yaml"
+    "429":
+      $ref: "../../v3/responses/429.yaml"
+    "500":
+      $ref: "../../v3/responses/500.yaml"

idn/beta/schemas/KbaAnswerRequest.yaml

@@ -1,18 +0,0 @@
-type: object
-properties:
-  answers:
-    nullable: false
-    type: array
-    items:
-        $ref: "../schemas/KbaAnswerRequestItem.yaml"
-
-    description: Kba answers
-    example:
-      - questionId: 089899f13a8f4da7824996191587bab9
-        answer: Your answer
-      - questionId: 067899f13a8f4da7824996191587bab9
-        answer: Your answer1
-required:
-  - answers
-
-

idn/beta/schemas/KbaAnswerRequestItem.yaml

@@ -1,15 +1,15 @@
 type: object
 properties:
-  questionId:
+  id:
     type: string
     nullable: false
     description: Question Id
-    example: 089899f13a8f4da7824996191587bab9
+    example: c54fee53-2d63-4fc5-9259-3e93b9994135
   answer:
     type: string
     nullable: false
     description: An answer for the KBA question
     example: Your answer
 required:
-  - questionId
+  - id
   - answer

idn/beta/schemas/KbaAnswerResponseItem.yaml

@@ -0,0 +1,21 @@
+type: object
+properties:
+  id:
+    type: string
+    nullable: false
+    description: Question Id
+    example: c54fee53-2d63-4fc5-9259-3e93b9994135
+  question:
+    type: string
+    nullable: false
+    description: Question description
+    example: "[{\"text\":\"Nouvelle question MFA -1 ?\",\"locale\":\"fr\"},{\"text\":\"MFA new question -1 ?\",\"locale\":\"\"}]"
+  hasAnswer:
+    type: boolean
+    nullable: false
+    description: Denotes whether the KBA question has an answer configured for the current user
+    example: true
+required:
+  - id
+  - question
+  - hasAnswer

idn/beta/schemas/KbaQuestion.yaml

@@ -0,0 +1,29 @@
+description: KBA Configuration
+type: object
+properties:
+  id:
+    type: string
+    nullable: false
+    description: KBA Question Id
+    example: 143cfd3b-c23f-426b-ae5f-d3db06fa5919
+  text:
+    type: string
+    nullable: false
+    description: KBA Question description
+    example: "[{\"text\":\"Nouvelle question MFA -1 ?\",\"locale\":\"fr\"},{\"text\":\"MFA new question -1 ?\",\"locale\":\"\"}]"
+  hasAnswer:
+    type: boolean
+    nullable: false
+    description: Denotes whether the KBA question has an answer configured for any user in the tenant
+    example: true
+  numAnswers:
+    type: integer
+    format: int32
+    nullable: false
+    description: Denotes the number of KBA configurations for this question
+    example: 5
+required:
+  - id
+  - text
+  - hasAnswer
+  - numAnswers

idn/sailpoint-api.beta.yaml

@@ -1364,6 +1364,10 @@ paths:
     $ref: './beta/paths/mfa-okta-config.yaml'
   /mfa/duo-web/config:
     $ref: './beta/paths/mfa-duo-config.yaml'
+  /mfa/kba/config:
+    $ref: './beta/paths/mfa-kba-config.yaml'
+  /mfa/kba/config/answers:
+    $ref: './beta/paths/mfa-kba-config-answers.yaml'
   /mfa/{method}/test:
     $ref: './beta/paths/mfa-config-test.yaml'
   /mfa/{method}/delete: