IBM MFA web API request/response formats

General information

• If there are multiple instances of the IBM MFA web server within a sysplex, it is reasonable to spread authentication requests between them. However, when an IBM MFA authentication request is begun, an affinity must be established to the selected host by the client and all subsequent related requests containing a resumeID must be sent to the same host that generated the resumeID.
  Important: Do not start an authentication request on system A, receive a response with a resumeID, and then continue the authentication request on system B with a resumeID returned by system A.
• All requests must be received by the IBM MFA web server through a secure TLS connection.
• Requests to the mutual authentication port must provide a valid client certificate when the secure TLS connection is established.
• The contents of JSON objects sent and received for some IBM MFA requests are dependent on the installation-specific IBM MFA policy definition that is used for the request. To see installation-specific examples, you can enable web browser tracing of network requests, perform an IBM MFA web authentication using the installation-specific IBM MFA policy, and then view the JSON objects that were sent and received for the authentication based on that policy.
• All JSON objects are encoded in UTF-8. However, the encoding of specific request and prompt field values may be further constrained to ISO-646, which is a proper single-byte subset of UTF-8.
• The URL path specification that follows the port value in the URL is case sensitive and must be specified as shown.
• Percent encoding values are not supported in the URL path specification.
• The following HTTP status response codes apply to all service requests:
  • 200 – “Request completed”
  • 400 – “Bad request”
  • 403 – “Forbidden”
  • 404 – “Not found”
  • 405 – “Method Not Allowed”
  • 413 – “Payload Too Large”
  • 500 – “Internal server error”

Type and Attribute Values