はじめに
IBM Verify の Developer Guides にはチャットボット連携ガイド（Chat bot integration patterns）があります。チャットで「パスワードをリセット」と入力すると、OTP（ワンタイムパスワード）をメールか SMS で受け取り、入力して本人確認が取れたらパスワードをリセットしてくれるというものです。
このガイドに従って設定をすれば、チャットボットからMFA(多要素認証)を使ってパスワードリセットすることができるのですが、手順が多く、時間が掛かってしまいます。
そこで、IBM Bob を使って設定してみることにしました。
設定を進めるとガイドの通りには進まないところもありましたが、IBM Bob と進めることで、そのような問題を１つ１つ解決することができました。
本記事では、ガイドどおりに進めたら動かなかった箇所と、その解決方法を中心にまとめます。同じ構成を試みる方の参考になれば幸いです。
💡 IBM Bob と一緒に作りました
実装の大部分と、この記事の執筆には IBM Bobを活用しました。エラーログを貼り付けて原因を聞いたり、修正案をもらってすぐ試したりというサイクルを繰り返すことで、一人で作業するより格段にスムーズに進められました。後述する「方式の選び直し」も Bob との相談で決めました。
どんな構成にしたか
チャットのフロー
- ログインページ右下のチャットアイコンをクリック
- 「パスワードをリセット」と入力
- ユーザー名を入力
- OTP の受け取り方法を選択（メール / SMS）
- 届いた 6 桁のコードを入力
- 確認できたらパスワードをリセット → 新パスワードがメールで届く
3 つの統合方式と、なぜ方式 C にしたか
Developer Guides （Chat bot integration patterns）には Watson Assistant と IBM Verify を繋ぐ方式として 方式 A（IBM Cloud Functions） が紹介されています。
しかし、試してみると早くも問題にぶつかりました。
IBM Cloud Functions はすでにサービスが終了しており 利用できないのです。
💡 ここで IBM Bob が役立ちました
「Cloud Functions が使えないのですが、別の方法はありますか？」と Bob に相談したところ、 3 つの選択肢 を提示してもらいました。それぞれの方式についてメリット・デメリットもつけて解説してくれました。
Bob が提案した 3 案を比較した結果、方式 C（Custom Extensions） を採用しました。
| A. Cloud Functions + Webhook（公式ガイド） | B. ローカル Flask + ngrok（Bob 提案） | C. Custom Extensions（Bob 提案） | |
|---|---|---|---|
| 仕組み | Python を Cloud Functions にデプロイして Webhook として使う | ローカル PC の Flask サーバーを ngrok で公開して使う | Watson Assistant に OpenAPI を直接インポートして IBM Verify API を呼び出す |
| 中間サーバー | 必要 | 必要 | 不要 |
| 向いている場面 | 現在は利用不可 | 開発・検証用 | 本番利用 |
方式 C は Watson Assistant が IBM Verify API を直接呼び出すためサーバー管理が不要です。OAuth 2.0 のトークン取得も Watson Assistant が自動でやってくれます。そのため方式Cを採用しました。
Watson Assistant
│ Custom Extensions（直接 API 呼び出し）
▼
IBM Verify API
設定の流れ
以下の設定は、基本的にBobに実施してもらいました。ただし、設定の中でIBM Verify の管理画面へのログインが必要になった箇所や、API Client のクライアントシークレットを取得・設定する箇所等は、人が実施するようにしました。
また、設定画面によってはBob の操作することが難しいところなど、人が操作する方が良い場面もありましたので、そのような際には人が操作をして、結果をBobに確認してもらうようにしています。
1. IBM Verify で API クライアントを作る
IBM Verify の管理コンソール → セキュリティー(Security) → APIアクセスAPI access) → APIクライアントの追加(Add API client) で API クライアントを作成します。
2. Watson Assistant に Custom Extension を追加する
- Watson Assistant → Integrations → Build custom extension
- Extension 名：
IBM Verify API -
ibm-verify-openapi.yamlをアップロード - 認証設定で OAuth 2.0（Client Credentials）を選び、Client ID と Secret を入力
これだけで Watson Assistant が自動でアクセストークンを取得・管理してくれます。
3. アクションを作ってフローを組む
Watson Assistant の Actions 画面でパスワードリセットのフローを 12 ステップで作ります（後述）。
4. ログインページにチャットを埋め込む
- IBM Verify 管理コンソール → ユーザー・エクスペリエンス → ブランド設定 → マスター・テンプレートのダウンロード でログインテンプレートをダウンロード
- Watson Assistant の Integrations → Web Chat → Embed からスクリプトコードをコピー
- テンプレートの
</body>直前にスクリプトを貼り付けて IBM Verify にアップロード (実際は authentication > login > cloud_directory > user_login > cloud_directory_login.html を選択して直接編集しました)
⚠️ テンプレートはスクリプトの追記だけに留める
IBM Verify のテンプレートには {{stateId}} などの変数が含まれています。フォーム部分を触らず、Watson Assistant のスクリプトタグだけを追記してください。
つまずいたポイント（重要）
ガイドのとおりに進めると動かない箇所がいくつかありました。
① Accept ヘッダーが違うと 406 エラーになる
Watson Assistant の Custom Extensions はデフォルトで Accept: application/json を送りますが、IBM Verify のユーザー検索やパスワードリセットのエンドポイントは application/scim+json でないと HTTP 406 を返して失敗します。
| エンドポイント | 正しい Accept |
|---|---|
GET /v2.0/Users（ユーザー検索） |
application/scim+json |
PATCH /v2.0/Users/{id}/passwordResetter |
application/scim+json |
| OTP 系のエンドポイント |
application/json（そのままで OK） |
📖 IBM Verify の API リファレンスに書いてあります
GET /v2.0/Users の API リファレンスのサンプルには --header 'accept: application/scim+json' と明記されています。IBM Bob に、APIリファレンスのURLを共有することで、Bobが修正箇所の特定を行い問題が解消しました。
直し方：OpenAPI 定義で該当エンドポイントに Accept ヘッダーを明示します。
parameters:
- in: header
name: Accept
required: true
schema:
type: string
default: "application/scim+json"
② OTP 送信は 2 ステップ必要
ガイドのサンプルでは POST /v2.0/factors/emailotp/verifications を直接呼び出していますが、実際には 先に enrollment ID を取ってから OTP を送る 2 ステップが正しい仕様です。
-
GET /v2.0/factors/emailotp?search=userId="..."→ enrollment ID を取得 -
POST /v2.0/factors/emailotp/{enrollmentId}/verifications→ OTP を送信
⚠️ 2 種類の ID を混同しない
enrollment 取得で得る id（enrollmentId）と、OTP 送信後に返ってくる id（trxnId）は別物です。OTP 検証では両方が必要です。
③ OTP 検証のパスにも enrollmentId が必要
| ガイドのパス | 正しいパス | |
|---|---|---|
| Email OTP 検証 | .../emailotp/verifications/{txnid} |
.../emailotp/{enrollmentId}/verifications/{trxnId} |
| SMS OTP 検証 | .../smsotp/verifications/{txnid} |
.../smsotp/{enrollmentId}/verifications/{trxnId} |
④ OTP を登録していないユーザーは Transient フローを使う
IBM Verify で Email OTP を使うには事前に OTP の登録（enrollment）が必要です。登録がないユーザーには /v2.0/factors/emailotp/transient/verifications を使う Transient フローで対応することもできます。Transientの場合、事前にメールアドレスを登録せずに任意のメールアドレスに OTP を送付できるのですが、その分、事前設定していないアドレスにメールを送付するため本人確認としての意味合いが弱くなる点に留意してください。
⑤ OpenAPI を再インポートしたらアクションの設定をやり直す
OpenAPI 定義を Watson Assistant に再インポートすると内部 ID（spec_hash_id）が変わります。各アクションステップの Extension 設定を 「Edit extension」→ Apply → Save で再設定する必要があります。
⑥ スペル自動補正がユーザー名を書き換える
Watson Assistant はデフォルトでスペル修正が有効です。ユーザー名として demouser と入力すると mouser に変換されてしまい、ユーザーが見つからないという問題が起きました。
直し方：Watson Assistant の設定で spelling_auto_correct を false にします。
⑦ 画面ショットを数多く取得してしまう
GUIでの操作をBobが実施しようとする場合や、人が操作した結果を確認してもらう際には、画面ショットを取得しています。この画面ショットの数が多くなりがちです。Bobに操作を要求する際、画面ショットは適宜削除することをリクエストするようにしました。
アクションの全体像（12 ステップ）
IBM bob と対話しながら進めるうちに、エラーケース、例外ケースへの対応が必要であることも見つかり、徐々にステップが増え、12ステップまで増えました、これもIBM Bobが柔軟に対応しました。
ステップを増やしたり、処理順を入れ替えたりした場合は、Planモードでステップをもう一度、最初から見直すようにしました。こうすることで修正した箇所が他のステップに影響していることも対応できます。
自分が作業をするときには面倒な作業ですが、IBM Bobであれば、「もう一度、最初から見直して」と依頼するだけで実施してくれます。これはとても助かりました。
| ステップ | 内容 |
|---|---|
| 1 | ユーザー名を入力してもらう |
| 2 | IBM Verify でユーザーを検索 |
| 3 | 見つからない場合は「アカウントが見つかりません」と返す |
| 4 | メールか SMS かを選んでもらう |
| 5 | メール OTP を送信（Transient フロー） |
| 6 | SMS OTP を送信（通常フロー） |
| 7 | 6 桁のコードを入力してもらう |
| 8 | メール OTP を検証 |
| 9 | 失敗したら「コードが違います」→ 再入力 |
| 10 | SMS OTP を検証 |
| 11 | 失敗したら「コードが違います」→ 再入力 |
| 12 | パスワードをリセットして完了メッセージを返す |
動作確認結果
| テスト内容 | 結果 |
|---|---|
| 有効なユーザーで検索 | ✅ OTP 選択画面に進む |
| 存在しないユーザーで検索 | ✅「アカウントが見つかりません」と表示 |
| メール OTP → 正しいコード入力 | ✅ パスワードリセット完了 |
| メール OTP → 間違ったコード入力 | ✅「コードが違います」→ 再入力できる |
| SMS OTP 送信 | ✅ SMS が届く |
| ログインページにチャットが表示 | ✅ 右下にチャットアイコンが出る |
IBM Bob の活用について
今回の実装全体を通じて IBM Bob をフル活用しました。
- 方式選択：Cloud Functions が使えないと伝えたら Custom Extensions を提案してくれた
- Watoson Assistant の設定の確認：Watson Assistant は今まで使ったことがなかったが、IBM Bob がほとんど設定してくれた
- 設定の確認：Watson Assistant アクションの Expression の書き方を一緒に確認した
- この記事の執筆：作業ログをもとに記事の構成と文章を提案してもらった
💡 使い方のコツ
「エラーログをそのまま貼り付けて聞く」→「提案をもらって試す」→「結果を共有する」を繰り返すだけで、フローも精緻化することができました。
ときどき、Bobが原因を行い、見つけた問題解決にそのまま取り掛かることがあるため、一旦、修正計画の作成までとして処理を止め、修正計画策定後、修正計画の全体を再度見直すことで、解決も早くできました。
まとめ
- Cloud Functions は現在では利用できないので別方式を採用
- ユーザー検索・パスワードリセットは
Accept: application/scim+jsonが必要 - OTP 送信は enrollment ID を取ってから送る 2 ステップ
- OTP 検証のパスには enrollmentId と trxnId の両方が必要
- OpenAPI 再インポート後はアクション設定の再適用を忘れずに
- スペル自動補正は無効にしておく
Custom Extensions 方式は設定がシンプルで管理も楽ですが、IBM Verify API の仕様を OpenAPI 定義に正確に書く必要があります。IBM Bob を活用することで、そのようなことを半自動で実施することができました。この記事がみなさまの参考になれば幸いです。