针对 initiate+validate 和 initiate+wait 模式启动 API 合同

在线编辑

所使用因子支持 "initiate+validate" 或 "initiate+wait" 集成模式时，在运行时 MFA 质询期间由内部 Verify 组件启动 initiate 资源。

例如，smsotp 或 push。 Verify 期望响应包含 status（指示 MFA 启动成功或失败）及事务标识（在后续 "validate" 或 "wait for result" 请求上包含）。 下例展示了由 Verify 发送到实时 webhook 的 资源的 initiate 请求示例。 根据 Webhook 配置，此相同有效内容可直接发送至目标 MFA 提供程序，也可以转换为目标提供程序可接受的 API 客户机请求。
POST '/initiate' \
'Content-Type: application/json' \
'Accept: application/json' \

{
  "capability":  "<<factor capability name, e.g. totp>>",
  "id": "<<factor or device identifier from external provider>>",
  "attributes":
    {
      "username": "<<external MFA username>>"
    }
}
注意： 本示例中的 HTTP/initiate 路径会根据 webhook 的配置而有所不同。

启动请求详细信息

Element 描述
HTTP 请求 POST
HTTP 标头 - Content-Type 请求有效内容的内容类型始终为 application/json。
HTTP 标头 - 接受 期望的响应有效内容的内容类型始终为 application/json。
有效内容 表示要验证的令牌或传递值的 JSON 对象。 有效内容还标识用户及其关联 MFA 注册。
id

必填。 用户已注册 MFA 因子功能的唯一标识。
capability

必填。 该值是有效字符串。 它必须与为与 Webhook 关联的 MFA 提供程序配置的某个功能相匹配。
attributes

必填。 特定于请求的其他属性。
attributes.username 必填。 外部提供程序系统中对其请求 MFA 启动的用户的名称。
以下代码样本是 initiate 响应有效内容的示例。
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

启动响应详细信息

元素 描述
有效内容类型 表示 MFA 启动尝试状态的 JSON 对象。
HTTP 状态码 请参阅 HTTP Status。
status 必填。 验证完成状态。 有效值包括：SUCCESS、PENDING、TIMEOUT、CANCELED 和 FAILED
注： 返回状态为SUCCESS向 Initiate 发起呼叫会导致最终用户收到错误提示。 “SUCCESS”不是“Initiate”调用的有效状态

如果 MFA 提供商支持 OTP 重试，则“状态”必须返回为“待处理”。
transactionId

必填。 事务或其他 MFA 提供程序认证质询状态句柄。 由提供程序用来关联任何后续“验证”或“结果轮询”调用。
attributes

可选。 返回到触发了 MFA 质询的公共 Verify 客户机的附加属性。 可能存在任何属性和值。