initiate+validate および initiate+wait パターンの API 規約の開始

オンラインで編集

initiate リソースは、使用される要素が "initiate+validate" または "initiate+wait" 統合パターンをサポートする場合に、ランタイム MFA チャレンジ中に内部 Verify コンポーネントによって起動されます。

例えば、smsotp または push などです。 Verify は、MFA 開始の成功または失敗を示す status と、後続の "validate" 要求または "wait for result" 要求に含まれるトランザクション ID が応答に含まれることを予期します。 以下に、が 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の設定によって異なります。

開始要求の詳細

エレメント 説明
HTTP 要求 POST
HTTP ヘッダー - Content-Type 要求ペイロードのコンテンツ・タイプは、常に application/json です。
HTTP ヘッダー - Accept 応答ペイロードの予期されるコンテンツ・タイプは、常に application/json です。
Payload 検証されるトークンまたはパス値を表す JSON オブジェクト。 ペイロードは、ユーザーとその関連する MFA 登録も識別します。
id

必須。 MFA 要素機能に登録済みユーザーの固有 ID。
capability

必須。 値は有効な文字ストリングです。 これは、Webhook に関連付けられている MFA プロバイダー用に構成されている機能の 1 つと一致している必要があります。
attributes

必須。 要求固有の追加属性。
attributes.username 必須。 MFA 開始が要求される外部プロバイダー・システム内のユーザーの名前。
以下のコード・サンプルは、initiate 応答ペイロードの例です。
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

開始応答の詳細

エレメント 説明
ペイロード・タイプ MFA 開始試行状況を表す JSON オブジェクト。
HTTP 状況コード 「 HTTP 」のステータスを参照してください。
status 必須。 検証の完了状況。 有効な値は、SUCCESS、PENDING、TIMEOUT、CANCELED、および FAILED です。
注： ステータスとしてSUCCESS「Initiate」呼び出しを行うと、エンドユーザーにエラーが発生します。 「SUCCESS」は、Initiate呼び出しの有効なステータスではありません

MFAプロバイダーがOTPの再試行をサポートしている場合、「status」は「PENDING」として返される必要があります。
transactionId

必須。 トランザクションまたはその他の MFA プロバイダー認証チャレンジ状態ハンドル。 プロバイダーが後続の「検証」呼び出しまたは「結果ポーリング」呼び出しと相関させるために使用します。
attributes

オプション。 MFA チャレンジをトリガーしたパブリック Verify クライアントに返される追加の属性。 いずれの属性および値でも存在する場合があります。