policyPrompt – Policy information prompt service

The policy information prompt service returns a JSON document that describes the text and fields to use when prompting an end-user for a specified policy. It identifies the factors in the policy, and for each factor describes the output text, prompt fields, and field names associated with the prompt fields in a subsequent initial policyAuth service request. The request URL must specify a defined IBM® MFA policy name.

Important: The policy name in the URL is not case sensitive.

policyPrompt Request

Table 1. policyPrompt request
Method: GET
URL: https://host:port/policy_name
Version: HTTP/1.1
Headers required: none
Body: none

policyPrompt successful response

Table 2. policyPrompt successful response
Status: 200 – Normal completion
Headers returned: Content-Type:application/json
Body: JSON policyPromptResponse object

policyPrompt JSON response objects

Note: See Table 1 for the type and attribute values for the IBM MFA web API JSON request and response objects.
Table 3. policyPrompt JSON response objects
Key Name Type Attr Description
policyPromptResponse object
resptype I Deprecated – not intended for application use.
type S

The response type. The possible values are as follows:

prompt
Prompting information has been returned.
error
Prompting information can not be returned.
When type is “prompt”
payload O C A policyPromptPolicyResponse object.
When type is “error”
rc I C Request return code.
rsn I C Request reason code.
sts I Deprecated – not intended for application use.
output A Deprecated – not intended for application use.
policyPromptPolicyResponse object
policyName S The name of the policy being described. This will match the policy name specified in the request URL. The length is from 1 to 20 characters.
policyFactor AO An array of policyPromptFactorResponse objects, one for each factor defined in the policy.
submitURL S The URL to use when performing a subsequent policyAuth service request based on the policyPrompt response.
policyPromptFactorResponse object
factorName S The name of the factor being described. The length is from 1 to 20 characters. The value to use in a factorResponse object for this factor when performing a subsequent policyAuth service request.
factorDescription S A short description of the factor. The length is from 1 to 128 characters.
promptSpec O A promptFactorFieldsResponse object which describes the text and prompt fields for the factor.

Shared policyPrompt and policyAuth JSON response objects

Note: See Table 1 for the type and attribute values for the IBM MFA web API JSON request and response objects.
Table 4. Shared policyPrompt and policyAuth JSON response objects
Key Name Type Attr Description
promptFactorFieldsResponse object
factorName S Deprecated – not intended for application use. When composing a factorResponse object use the factorName value specified in the policyPromptFactorResponse object to identify the factor the response object is for.
promptType S

The type of prompt to perform. The possible values are as follows:

submitURL
No prompt data is required for this factor. The digital certificate associated with the secure TLS connection is used to perform the authentication.
Interactive
The prompt fields must be returned to perform the authentication for this factor.
promptHeading S Text to use as a heading for the prompt fields for the factor. The length is from 1 to 512 characters. This may be a response string generated by an external server which can contain formatting control characters such as a new-line.
promptFields AO An array of promptFactorFieldResponse objects for the factor.
promptFactorFieldResponse object
fieldLabel S Text to use as a label for the field. The length is from 1 to 64 characters.
fieldType S

The field type. The possible values are as follows:

textField
Text entered by the user in the prompt field should appear as clear text.
secureTextField
Text entered by the user in the prompt field should appear masked.
fieldname S The value to use in a factorResponseFieldRequest object for this factor when performing a subsequent policyAuth service request.
maxLength I The maximum character length of the prompt field.
isOptional I O

The possible values are as follows:

0
Data in the field is required.
1
Data in the field is optional.

The default if the key name not specified is 0, data in the field is required.

policyPromptResponse return/reason codes

Table 5. policyPromptResponse return/reason codes
Rc Rsn Description
40 2 Some factors in the policy are not usable or no factors are defined in the policy.
40 5 The policy does not exist.
48 n An internal error occurred. The reason codes are not documented.

Request/Response examples

Example – Single factor policy with prompt type submitURL
Request
https://host:port/policyPrompt/CERTONLY/
Response
{
  "resptype": 10,
  "type": "prompt",
  "payload": {
    "policyName": "CERTONLY",
    "policyFactors": [
      {
        "factorName": "AZFCERT1",
        "factorDescription": "Certificate-based Authentication",
        "promptSpec": {
          "factorName": "AZFCERT1",
          "promptType": "submitURL",
          "promptHeading": "Policy Authentication will require mutual TLS
        authentication with your enrolled certificate."
        }
      }
    ],
    "submitURL": "https://host:port/policyAuth/"
  }

        }
Example – Single factor policy with prompt type Interactive
Request
https://host:port/policyPrompt/SIDPONLY/
Response
{
  "resptype": 10,
  "type": "prompt",
  "payload": {
    "policyName": "SIDPONLY",
    "policyFactors": [
      {
        "factorName": "AZFSIDP1",
        "factorDescription": "RSA SecurID",
        "promptSpec": {
          "factorName": "AZFSIDP1",
          "promptType": "Interactive",
          "promptHeading": "Enter your
        SecurID passcode",
          "promptFields": [
            {
              "fieldLabel": "Passcode",
              "fieldType": "secureTextField",
              "fieldName": "passCode",
              "maxLength": 16
            }
          ]
        }
      }
    ],
    "submitURL":
          "https://host:port/policyAuth/"
  }
 }
Example – Two factor policy
Request
https://host:port/policyPrompt/passsidp/
Response
{
  "resptype": 10,
  "type": "prompt",
  "payload": {
    "policyName": "PASSSIDP",
    "policyFactors": [
      {
        "factorName": "AZFPASS1",
        "factorDescription": "Password Authentication",
        "promptSpec": {
          "factorName": "AZFPASS1",
          "promptType": "Interactive",
          "promptHeading": "To
        authenticate, enter your SAF password or passphrase. If you want to change it, also enter
        and confirm a valid replacement.",
          "promptFields": [
            {
              "fieldLabel": "Password",
              "fieldType": "secureTextField",
              "fieldName": "password",
              "maxLength": 100
            },
            {
              "fieldLabel": "New Password",
              "fieldType": "secureTextField",
              "fieldName": "newPassword",
              "maxLength": 100
            },
            {
              "fieldLabel": "Confirm
        New Password",
              "fieldType": "secureTextField",
              "fieldName": "newPass2",
              "maxLength": 100
            }
          ]
        }
      },
      {
        "factorName": "AZFSIDP1",
        "factorDescription": "RSA SecurID",
        "promptSpec": {
          "factorName": "AZFSIDP1",
          "promptType": "Interactive",
          "promptHeading": "Enter your SecurID passcode",
          "promptFields": [
            {
              "fieldLabel": "Passcode",
              "fieldType": "secureTextField",
              "fieldName": "passCode",
              "maxLength": 16
            }
          ]
        }
      }
    ],
    "submitURL": "https://host:port/policyAuth/"
  }

        }
Example – Invalid policy
Request
https://host:port/policyPrompt/INVALIDPOLICY/
Response
{
  "resptype": 4,
  "type": "error",
  "sts": 1200054,
  "rc": 40,
  "rsn": 5,
  "output": [
    {
      "outputType": 1,
      "msg": "Error processing specified policy name."
    }
  ]

        }