セキュリティ

API キー

• API キー(st_ で始まる文字列)はサーバー側だけに置きます。ブラウザ・スマートフォンアプリ・公開リポジトリに入れないでください
• Authorization: Bearer <API キー> ヘッダで送ります
• キーは発行時に一度だけ表示されます。環境変数やシークレット管理の仕組みに保存してください
• 漏れた疑いがあれば、管理画面で新しいキーを発行して入れ替え、古いキーを無効にしてください
• 無効なキーはすべて同じ 401 になり、理由(存在しない・無効化済みなど)は返りません

IP 許可リスト

API を呼べる送信元の IP アドレスを制限できます。設定すると、それ以外のアドレスからの呼び出しは 403(IpNotAllowed)になります。設定・変更は担当者に依頼してください。

戻り先(callback URL)

callbackUrl は、管理画面の許可リストに登録した URL だけが使えます。

• 許可リストに登録できるのは https の URL だけです。クエリ(?)とフラグメント(#)は付けられません
• 作成時の callbackUrl は、スキームとホストが登録した URL と完全に一致し、パスが登録した URL のパスで始まる必要があります
• callbackUrl にもクエリとフラグメントは付けられません。自社側の相関には state を使います

手続きが終わると、利用者は次の形の URL に戻ってきます。

{callbackUrl}?sessionId={セッション ID}&state={state}

• このクエリを結果として使わないでください。クエリは利用者のブラウザを通るので、書き換えられます。本人確認の結果は webhook か取得 API で受け取ります
• 戻ってくるのは判定が確定したとき(completed)だけです。審査待ち・エラー・期限切れのときは戻ってきません。戻ってこなくても webhook は届きます
• 同じ戻り先に複数回戻ってくることがあります(completed の間は、利用者が検証の画面を開き直すたびに戻ってきます)。1 回目で保存値を消さず、何度来ても同じように扱ってください
• state は SupaTrust では検証しません。作成時に推測できない値を作り、セッション ID と一緒に、ログイン中の利用者のサーバー側(ログインセッションや DB の利用者の行)に保存してください。戻ってきたら state をその利用者の保存値と照合し、結果はクエリの sessionId ではなく保存したセッション ID で引きます。クエリの値で引くと、攻撃者が自分の手続きの戻り URL を別の利用者に開かせたとき、その利用者の画面に攻撃者の結果が出てしまいます

検証 URL

• 作成の応答の verificationUrl は 1 回だけ使える秘密の URL です。その利用者にだけ渡し、ログや分析ツールに記録しないでください
• 取得 API では返りません。利用者に渡し直す必要があるときは、管理画面で再発行します

webhook

• 受け取った通知は、必ず署名を検証してから使います(webhook)
• シークレット(whsec_ で始まる文字列)もサーバー側だけに置きます

個人情報

• webhook の通知には氏名・住所などの本人情報を載せていません。本人情報は取得 API だけが返します。ただし、通知の data.review.note(審査のメモ・自由記述)と metadata は、本文をそのままログに出さないでください
• 取得 API の応答(利用者の入力・券面から読み取った項目)を、ログ・エラー通知・分析基盤にそのまま流さないでください
• metadata には個人情報を入れないでください。webhook の通知にそのまま載ります
• 取得 API による個人情報の取得は、SupaTrust 側で記録されます