Multiple Secret Question Enrollment

Users can set multiple user-defined questions for authentication, or you can force them to use admin defined questions.

This document provides an overview of the APIs necessary to programmatically create multiple security questions.

Preparing Admin-defined Questions on the Admin Portal

When setting questions as an admin for a user, you should be using admin-defined questions, which can be set up in the Admin Portal.

This document provides information on configuring the policies required for setting up security questions. The key steps are as follows:

Determine if you want to supply the questions as an admin (and give the user a list of options), or let the user define their own.
Edit your user's security policy by navigating to Policies > Edit Policy > User Security Policies > User Account settings and define what questions are required and how many. For example, two user defined and one admin defined, or three admin defined and two user defined, etc.
Set the policy to force a specific number of questions that must be satisfied for login in the login's authentication profile.

Setting Admin-defined Questions Programmatically for a Tenant

This section describes the API workflow for setting admin-defined questions programmatically for a tenant.

Before continuing, ensure you are familiar with:

Adding a Question

Invoke the /TenantConfig/SetAdminSecurityQuestion endpoint to add a security question:

POST /TenantConfig/SetAdminSecurityQuestion

{
	"Question" : "Question1"
}

This endpoint simply adds the text for an individual, admin-defined question.

The success field in the response indicates whether the question was successfully added:

{  
   "success":true,
   "Result":null,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Repeat the above call to add additional questions.

Getting the User-Defined Questions for the Tenant

Once you've added all of the questions you can then get the list of admin-defined questions available for the tenant by invoking the /TenantConfig/GetAdminSecurityQuestions endpoint:

POST /TenantConfig/GetAdminSecurityQuestions

{  
   "Args":{  
      "PageNumber":1,
      "PageSize":100000,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

The response contains the list of questions and the UUID assigned to each:

{
   "success":true,
   "Result":[
      {
         "Culture":"all",
         "_encryptkeyid":"AAA3021",
         "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
         "Question":"Question2"
      },
      {
         "Culture":"all",
         "_encryptkeyid":"AAA3021",
         "Uuid":"a_5167af91-5cdc-4923-9d87-4cbc1938ca59",
         "Question":"Question3"
      },
      {
         "Culture":"all",
         "_encryptkeyid":"AAA3021",
         "Uuid":"a_e4c5d12e-ae0e-4691-953f-27cdfde66efd",
         "Question":"Question1"
      }
   ],
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Setting Answers to Admin-Defined Questions for a User

Getting the Questions

Before setting the answers to the admin-defined questions for a user, get the questions using the /UserMgmt/GetSecurityQuestions endpoint and set the path parameter AdminQuestions to true:

GET /UserMgmt/GetSecurityQuestions?addAdminQuestions=true

The response contains the UUID and text for each admin-defined question in the 'AdminQuestions' array:

{  
   "success":true,
   "Result":{  
      "MinAdminQuestions":2,
      "MinUserQuestions":0,
      "MaxQuestions":20,
      "AdminQuestions":[  
         {  
            "Culture":"all",
            "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
            "Question":"Question2"
         },
         {  
            "Culture":"all",
            "Uuid":"a_5167af91-5cdc-4923-9d87-4cbc1938ca59",
            "Question":"Question3"
         },
         {  
            "Culture":"all",
            "Uuid":"a_e4c5d12e-ae0e-4691-953f-27cdfde66efd",
            "Question":"Question1"
         }
      ],
      "Questions":[  

      ],
      "AnswerMinLength":3
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Setting the Answer to a Question

To set the answer to one or more questions, invoke the /UserMgmt/UpdateSecurityQuestions endpoint and create an element in the Added array for each answer. Some of the key fields to include for each element are:

Type: set to "admin" to indicate that the question was defined by the admin.
Uuid: the unique ID of the question to provide the answer for.
Answer: the answer to assign.

The following example sets the answer for questions one and two:

POST /UserMgmt/UpdateSecurityQuestions

{  
   "Deleted":[  

   ],
   "Added":[  
      {  
         "id":"13",
         "Type":"Admin",
         "IsValid-generated-field":"/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/green_check.png?_ver=1516396962",
         "QuestionText":"Question1",
         "Uuid":"a_e4c5d12e-ae0e-4691-953f-27cdfde66efd",
         "Modified":true,
         "HasAnswer":false,
         "Answer":"Dog"
      },
      {  
         "id":"14",
         "Type":"Admin",
         "IsValid-generated-field":"/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/green_check.png?_ver=1516396962",
         "QuestionText":"Question2",
         "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
         "Modified":true,
         "HasAnswer":false,
         "Answer":"Cat"
      }
   ]
}

The success field in the response indicates whether the questions were successfully updated.

{  
   "success":true,
   "Result":null,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

If you now get the questions again by invoking the /UserMgmt/GetSecurityQuestions endpoint, the Questions field in the response lists the questions for which answers have been provided:

GET /UserMgmt/GetSecurityQuestions?addAdminQuestions=true

{  
   "success":true,
   "Result":{  
      "MinAdminQuestions":2,
      "MinUserQuestions":0,
      "MaxQuestions":20,
      "AdminQuestions":[  
         {  
            "Culture":"all",
            "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
            "Question":"Question2"
         },
         {  
            "Culture":"all",
            "Uuid":"a_5167af91-5cdc-4923-9d87-4cbc1938ca59",
            "Question":"Question3"
         },
         {  
            "Culture":"all",
            "Uuid":"a_e4c5d12e-ae0e-4691-953f-27cdfde66efd",
            "Question":"Question1"
         }
      ],
      "Questions":[  
         {  
            "QuestionText":"Question1",
            "Uuid":"a_e4c5d12e-ae0e-4691-953f-27cdfde66efd"
         },
         {  
            "QuestionText":"Question2",
            "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5"
         }
      ],
      "AnswerMinLength":3
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Deleting or Updating a Question for a User

To delete a question, invoke the /UserMgmt/UpdateSecurityQuestions endpoint and pass in the UUID of the question to delete in the Deleted field. If you want to update the answer to a question, then you must also pass in the necessary information to the Added field.

The following example shows the answer being updated for a question. In this case, the UUID for question two is specified in Deleted, and then new information is specified in Added:

POST /UserMgmt/UpdateSecurityQuetions

{  
   "Deleted":[  
      "a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5"
   ],
   "Added":[  
      {  
         "id":"14",
         "QuestionText":"Question2",
         "Uuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
         "HasAnswer":false,
         "Type":"Admin",
         "OriginalUuid":"a_2d3dc1e9-e2ec-4af3-b929-1e7413f945f5",
         "IsValid-generated-field":"/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/green_check.png?_ver=1516396962",
         "Answer":"Cats",
         "Modified":true
      }
   ]
}

The success field in the response indicates whether the operation was successful:

{  
   "success":true,
   "Result":null,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Setting User-Defined Questions

If you have allowed users to define their own questions, you can programmatically add a user-defined question by invoking the /UserMgmt/UpdateSecurityQuestions endpoint. This is the same as adding admin-defined questions except that the Type field must be set to User to indicate that the question is user defined, as shown in the following example:

POST /UserMgmt/UpdateSecurityQuestions

{
   "Deleted":[

   ],
   "Added":[
      {
         "id":"15",
         "Type":"User",
         "IsValid-generated-field":"/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/green_check.png?_ver=1516396962",
         "QuestionText":"Dog",
         "Modified":true,
         "HasAnswer":false,
         "Answer":"Doggie"
      },
      {
         "id":"16",
         "Type":"User",
         "IsValid-generated-field":"/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/green_check.png?_ver=1516396962",
         "QuestionText":"Cat",
         "Modified":true,
         "HasAnswer":false,
         "Answer":"Kitty"
      }
   ]
}

The success field in the response indicates whether the user-defined questions were successfully added:

{  
   "success":true,
   "Result":null,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}