SMS認証

このドキュメントは、sms-authentication 方式による認証処理の 概要・設定・利用方法 について説明します。

概要

SMS認証は、ユーザーの電話番号にワンタイムコード（OTP）を送信し、それを使って本人確認を行う多要素認証方式の一つです。

idp-server ではSMS認証機能を2つのパターンで提供します。

外部SMS認証サービスを利用したTOTP
idp-serverで認証コード生成・検証 + 外部SMS送信サービスを利用したTOTP

SMS認証は以下の複数のインタラクションを連続的に実行することで成立します：

sms-authentication-challenge: 認証用ワンタイムコードの送信
sms-authentication: ワンタイムコードの検証

設定

設定には type = "sms" の AuthenticationConfiguration をテナントごとに登録する必要があります。

SMS認証は interactions ベースの設定構造を持ち、以下の2つのインタラクションを定義します：

sms-authentication-challenge: SMS送信処理
sms-authentication: コード検証処理

トップレベル設定項目

項目	内容
`id`	設定ID（UUID形式）
`type`	`sms` 固定
`metadata`	メタデータ（型、パラメータ名など）
`interactions`	インタラクション定義（challenge/verify）

メタデータ設定項目

項目	内容
`type`	`external`: 外部SMS認証サービス / `internal`: 内部OTP生成
`verification_code_param`	検証コードのパラメータ名（デフォルト: `verification_code`）
`transaction_id_param`	トランザクションIDのパラメータ名（外部サービス利用時）

`$.user.*` — 認証済みユーザー属性

execution.http_request のマッピングルールから、認証済みユーザーの属性を参照できます（Issue #1862）。外部システムの照会キーをサーバ側で組み立てられるため、クライアントに再送させる必要がありません。

"body_mapping_rules": [
  { "from": "$.user.sub", "to": "user_id" },
  { "from": "$.user.custom_properties.member_number", "to": "member_id" }
]

値を持つ条件と、外部送信できる属性の allow-list は External API認証の「マッピングソースで参照できるパス」と共通です。

設定パターン

パターン1: 外部SMS認証サービスを利用したTOTP

外部のSMS認証APIサービスを利用し、OTP生成・検証を外部に委譲するパターンです。

challenge インタラクション設定

項目	説明
`execution.function`	`http_request` 固定
`execution.http_request`	外部API設定（URL、メソッド、認証、マッピングルール）
`execution.http_request_store`	外部APIレスポンスの保存設定（`transaction_id`などを保存）
`response.body_mapping_rules`	レスポンスマッピング

verify インタラクション設定

項目	説明
`execution.function`	`http_request` 固定
`execution.previous_interaction`	challenge時に保存したデータの参照キー
`execution.http_request`	外部検証API設定
`execution.http_request.body_mapping_rules`	`verification_code` と `transaction_id` のマッピング
`response.body_mapping_rules`	レスポンスマッピング

設定例

{
  "id": "0f12803e-37b6-437e-8ca9-5822bd852b74",
  "type": "sms",
  "metadata": {
    "type": "external",
    "verification_code_param": "verification_code"
  },
  "interactions": {
    "sms-authentication-challenge": {
      "execution": {
        "function": "http_request",
        "http_request": {
          "url": "https://external-sms-service.com/challenge",
          "method": "POST",
          "oauth_authorization": {
            "type": "password",
            "token_endpoint": "https://external-sms-service.com/token",
            "client_id": "your-client-id",
            "username": "username",
            "password": "password"
          },
          "header_mapping_rules": [
            {
              "static_value": "application/json",
              "to": "Content-Type"
            }
          ],
          "body_mapping_rules": [
            {
              "from": "$.request_body",
              "to": "*"
            }
          ]
        },
        "http_request_store": {
          "key": "sms-authentication-challenge",
          "interaction_mapping_rules": [
            {
              "from": "$.response_body.transaction_id",
              "to": "transaction_id"
            }
          ]
        }
      },
      "response": {
        "body_mapping_rules": [
          {
            "from": "$.execution_http_request.response_body",
            "to": "*"
          }
        ]
      }
    },
    "sms-authentication": {
      "execution": {
        "function": "http_request",
        "previous_interaction": {
          "key": "sms-authentication-challenge"
        },
        "http_request": {
          "url": "https://external-sms-service.com/verify",
          "method": "POST",
          "oauth_authorization": {
            "type": "password",
            "token_endpoint": "https://external-sms-service.com/token",
            "client_id": "your-client-id",
            "username": "username",
            "password": "password"
          },
          "body_mapping_rules": [
            {
              "from": "$.request_body.verification_code",
              "to": "verification_code"
            },
            {
              "from": "$.interaction.transaction_id",
              "to": "transaction_id"
            }
          ]
        }
      },
      "response": {
        "body_mapping_rules": [
          {
            "from": "$.execution_http_request.response_body",
            "to": "*"
          }
        ]
      }
    }
  }
}

パターン2: idp-server内部でOTP生成・検証

idp-server内部でワンタイムパスワードを生成・検証し、外部SMSサービスは送信のみを担当するパターンです。

challenge インタラクション設定

項目	説明
`execution.function`	`sms_authentication_challenge` 固定
`execution.details.sender_type`	SMSサービスタイプ（`http_request`, `twilio`, `no_action`など）
`execution.details.settings`	送信プロバイダ固有の設定。`sender_type` が `http_request` の場合は `http_request` キーに外部API設定を記述（後述）
`execution.details.templates`	テンプレート定義（`{VERIFICATION_CODE}`プレースホルダー使用）
`execution.details.retry_count_limitation`	検証リトライ上限回数（デフォルト: 5）
`execution.details.expire_seconds`	OTP有効期限（秒）（デフォルト: 300）
`execution.details.resend_cooldown_seconds`	同一ユーザー・同一用途での再送を拒否する間隔（秒、未設定時: 60）。現状はセルフサービス連絡先の確認・変更のみが参照
`execution.details.templates.*_notice`	変更通知の文面（`phone_change_notice`）。`{CHANGED_AT}` / `{NEW_VALUE_MASKED}` を使う。確認コード用とはプレースホルダが異なる

テンプレート設定項目

項目	内容
`subject`	SMSタイトル（サービスによっては使用されない場合あり）
`body`	SMS本文。`{VERIFICATION_CODE}` と `{EXPIRE_SECONDS}` のプレースホルダーが使用可能

verify インタラクション設定

項目	説明
`execution.function`	`sms_authentication` 固定
`execution.details`	検証設定（リトライ上限、有効期限）

設定例

{
  "id": "0f12803e-37b6-437e-8ca9-5822bd852b74",
  "type": "sms",
  "metadata": {
    "type": "internal",
    "verification_code_param": "verification_code"
  },
  "interactions": {
    "sms-authentication-challenge": {
      "execution": {
        "function": "sms_authentication_challenge",
        "details": {
          "sender_type": "no_action",
          "templates": {
            "registration": {
              "subject": "[ID Verification] Your signup SMS confirmation code",
              "body": "Hello,\n\nPlease enter the following verification code:\n\n【{VERIFICATION_CODE}】\n\nThis code will expire in {EXPIRE_SECONDS} seconds.\n\n– IDP Support"
            },
            "authentication": {
              "subject": "[ID Verification] Your login SMS confirmation code",
              "body": "Hello,\n\nPlease enter the following verification code:\n\n【{VERIFICATION_CODE}】\n\nThis code will expire in {EXPIRE_SECONDS} seconds.\n\n– IDP Support"
            }
          },
          "retry_count_limitation": 5,
          "expire_seconds": 300
        }
      },
      "response": {
        "body_mapping_rules": [
          { "from": "$.response_body", "to": "*" }
        ]
      }
    },
    "sms-authentication": {
      "execution": {
        "function": "sms_authentication",
        "details": {
          "retry_count_limitation": 5,
          "expire_seconds": 300
        }
      }
    }
  }
}

sender_type `http_request`: 任意の外部HTTP APIへ送信を委譲

OTPの生成・検証は idp-server 内部で行いつつ、SMS送信のみを任意の外部HTTP API（Twilio等のSMS配信API）へ委譲する場合は、sender_type に http_request を指定します。送信先APIの設定は execution.details.settings.http_request に HttpRequestExecutionConfig 形式で記述します（外部サービス連携の HTTP Request Executor と同じ設定構造）。

`settings.http_request` 設定項目

項目	説明
`url`	SMS送信APIのエンドポイントURL
`method`	HTTPメソッド（通常 `POST`）
`oauth_authorization`	OAuth認証設定（外部APIがOAuthを要求する場合）
`header_mapping_rules`	リクエストヘッダーのマッピングルール
`body_mapping_rules`	リクエストボディのマッピングルール

body_mapping_rules の from で参照できる送信データは以下の2つです（idp-serverが組み立てた送信内容）：

パス	内容
`$.request_body.to`	送信先電話番号
`$.request_body.body`	送信本文（テンプレートに `{VERIFICATION_CODE}` 等を埋め込んだ後の文字列）

送信先APIが2xxを返せば送信成功（challenge成功）、4xx/5xxを返すと送信失敗として扱われます。OTPはレスポンスに含まれず idp-server 内部に保持され、sms-authentication で検証されます。

設定例

{
  "id": "0f12803e-37b6-437e-8ca9-5822bd852b74",
  "type": "sms",
  "metadata": {
    "type": "internal",
    "verification_code_param": "verification_code"
  },
  "interactions": {
    "sms-authentication-challenge": {
      "execution": {
        "function": "sms_authentication_challenge",
        "details": {
          "sender_type": "http_request",
          "settings": {
            "http_request": {
              "url": "https://external-sms-service.com/send",
              "method": "POST",
              "oauth_authorization": {
                "type": "password",
                "token_endpoint": "https://external-sms-service.com/token",
                "client_id": "your-client-id",
                "username": "username",
                "password": "password",
                "scope": "application"
              },
              "header_mapping_rules": [
                {
                  "static_value": "application/json",
                  "to": "Content-Type"
                }
              ],
              "body_mapping_rules": [
                {
                  "from": "$.request_body.to",
                  "to": "phone_number"
                },
                {
                  "from": "$.request_body.body",
                  "to": "message"
                }
              ]
            }
          },
          "templates": {
            "registration": {
              "subject": "[ID Verification] Your signup SMS confirmation code",
              "body": "Hello,\n\nPlease enter the following verification code:\n\n【{VERIFICATION_CODE}】\n\nThis code will expire in {EXPIRE_SECONDS} seconds.\n\n– IDP Support"
            },
            "authentication": {
              "subject": "[ID Verification] Your login SMS confirmation code",
              "body": "Hello,\n\nPlease enter the following verification code:\n\n【{VERIFICATION_CODE}】\n\nThis code will expire in {EXPIRE_SECONDS} seconds.\n\n– IDP Support"
            }
          },
          "retry_count_limitation": 5,
          "expire_seconds": 300
        }
      },
      "response": {
        "body_mapping_rules": [
          { "from": "$.response_body", "to": "*" }
        ]
      }
    },
    "sms-authentication": {
      "execution": {
        "function": "sms_authentication",
        "details": {
          "retry_count_limitation": 5,
          "expire_seconds": 300
        }
      }
    }
  }
}

利用方法

事前準備

テナントに type = "sms" の設定（AuthenticationConfiguration）を登録する

認証時

認可フロー中に prompt=login または acr_values によってSMS認証が要求される
/v1/authorizations/{id}/sms-authentication-challenge によって認証コードがSMS送信
SMS送信後に、/v1/authorizations/{id}/sms-authentication 、で認証コードを検証する

セルフサービス: 電話番号の確認・変更

認証済みユーザーが自分の電話番号を確認・変更する POST /{tenant-id}/v1/me/phone/... は、ここで定義した sms-authentication-challenge の送信設定(sender / templates / retry / expire)をそのまま流用する。templates に phone_verify / phone_change を追加しておくと、それぞれ専用の文面になる(未定義ならデフォルトにフォールバック)。

フロー・必要スコープ・管理APIはセルフサービス連絡先の確認・変更を参照。

外部サービスにコード生成・検証を委譲するパターンでも動きます。 どちらで動くかは execution.function が決めます（sms_authentication_challenge ならローカル生成、 http_request / http_requests なら委譲）。委譲時は idp-server はコードを持たず、外部の識別子だけを保持します（管理APIは delivery: external を返す）。宛先は phone_number という項目名で渡されるので、ログイン側の sms-authentication-challenge と同じ外部APIをそのまま向けられます。ただし phone_change_notice の文面が委譲設定には無いため、変更通知は送られません。別チャネルで知らせたい場合はセキュリティイベントフック（Email 型）を使う手があります（宛先・文面の制約はセルフサービス連絡先の確認・変更を参照）。

phone_change_notice を定義していない場合、変更通知はスキップされます（確認コード用のデフォルト文面にはフォールバックしません）。

備考

この処理は sms-authentication-challenge によって事前に送信されたワンタイムコードの確認に使用されます。
成功時は、SMS認証が完了した Authentication 情報が返却され、認可処理が進行します。
複数のSMS認証方式を SmsAuthenticationExecutors によって拡張可能です。

概要​

設定​

トップレベル設定項目​

メタデータ設定項目​

$.user.* — 認証済みユーザー属性​

設定パターン​

パターン1: 外部SMS認証サービスを利用したTOTP​

challenge インタラクション設定​

verify インタラクション設定​

設定例​

パターン2: idp-server内部でOTP生成・検証​

challenge インタラクション設定​

テンプレート設定項目​

verify インタラクション設定​

設定例​

sender_type http_request: 任意の外部HTTP APIへ送信を委譲​

settings.http_request 設定項目​

設定例​

利用方法​

事前準備​

認証時​

セルフサービス: 電話番号の確認・変更​

備考​

概要

設定

トップレベル設定項目

メタデータ設定項目

`$.user.*` — 認証済みユーザー属性

設定パターン

パターン1: 外部SMS認証サービスを利用したTOTP

challenge インタラクション設定

verify インタラクション設定

設定例

パターン2: idp-server内部でOTP生成・検証

challenge インタラクション設定

テンプレート設定項目

verify インタラクション設定

設定例

sender_type `http_request`: 任意の外部HTTP APIへ送信を委譲

`settings.http_request` 設定項目

設定例

利用方法

事前準備

認証時

セルフサービス: 電話番号の確認・変更

備考