Facial IDリファレンスガイド
FACEIO Facial ID（Index IDとも呼ばれます）の仕組みを説明します。 fio.jsが返すFacial IDの扱い、登録ユーザーとの対応付け、Webhookイベントでの扱い、REST APIでの削除方法を確認できます。
FACEIO Facial IDとは
FACEIOに登録されたユーザーに返される、アプリケーション単位の識別子です。
Facial ID（ Index ID）は、FACEIOでの enroll() が成功した後に割り当てられる一意の識別子です。アプリケーションはこの値を facialId として受け取り、FACEIOの登録をローカルアカウントに対応付けられます。
Facial IDはユーザーのメールアドレス、パスワード、ユーザー名、データベースの主キーではありません。FACEIOが返す識別子であり、同じ登録ユーザーを今後の authenticate() 呼び出しや関連するWebhookイベントで識別できます。
FACEIO を初めて実装する場合は、はじめにガイドに沿ってアプリケーションを作成し、Public ID を取得してください。次に統合ガイドを使って、enroll()、authenticate()、Facial ID の処理を Web アプリケーションに組み込みます。
登録時に作成
返される値は enroll() の実行後に返されます。
ログイン時に返される
返される値は authenticate() を使って、認証された登録ユーザーをアプリケーションが識別できるようにします。
依頼時に削除
削除には /deletefacialid REST APIを使用します。ユーザーが顔認証を無効にするか削除を依頼した場合です。
Facial ID はアカウントセキュリティデータとして扱ってください。FACEIO 認証をローカルアカウントに関連付ける必要がある場合はサーバー側に保存し、公開ログや分析に露出させないでください。プライバシー上の責任については、FACEIO プライバシーのベストプラクティスを参照してください。
fio.js がFacial IDを返す仕組み
FACEIO は、fio.js のクライアント側メソッドが返す Promise の解決値として Facial ID を提供します。返されるオブジェクトには複数のフィールドが含まれますが、アカウント連携に使用する主要な値は facialId です。
userInfo.facialIduserData.facialIdfacialIdpayload の実行時に enroll()、FACEIOは今後の認証でそのpayloadを返せます。payloadはアプリケーションに必要な値だけに限定し、クライアント側のpayloadを唯一の認可チェックに使わないでください。
Facial IDのライフサイクル
- 1. FACEIOアプリケーションを作成します。 はじめにガイド と FACEIO Console ↗ を使って、アプリケーション、ウィジェット設定、セキュリティオプションを構成します。
-
2. ユーザーを登録します。 統合ガイド に従い、ユーザーが顔認証を有効にして必要なブラウザ権限を許可した後に
enroll()を呼び出します。 -
3. 返された
facialIdを保存します。 FACEIO 認証をローカルのアカウントモデルに対応付ける場合は、バックエンドに保存します。 -
4. 再訪ユーザーを認証します。
authenticate()を呼び出し、返されたfacialIdをアプリケーションが想定するアカウントまたはセッションと比較します。 - 5. バックエンドを同期します。 Webhooks を使用して、登録、認証、Facial ID削除イベントでアカウント状態、監査ログ、リスク制御を更新します。
-
6. 必要なときに削除します。
/deletefacialidは、ユーザーが同意を撤回し、アカウントを削除し、生体認証ログインを無効化、または削除を依頼した場合に使用します。
顔認識エンジン
選択した顔認識エンジンは、登録ユーザーの顔を将来の照合に使う数学的な特徴ベクトルへ変換します。FACEIOはアプリケーションが独自のアカウントフローで登録レコードを参照できるようFacial IDを返します。
FACEIO 自体は、fio.js、埋め込みウィジェット、REST API、FACEIO Console を含め、生体認証ハッシュを保存、処理、または参照しません。アプリケーション所有者が選択した顔認識エンジンが、エンジンの選択、地域、同意フロー、削除ポリシーに従ってハッシュを管理します。
利用可能な認識エンジン
新しいアプリケーション ↗、FACEIOではそのアプリケーションの認識エンジンを選択できます。エンジンの選択は、FACEIOウィジェットの背後で登録と照合が処理される方法に影響します。
PixLab Insight
デフォルトデフォルトエンジンは PixLab ↗ がFACEIOアプリケーション向けに開発したものです。
AWS Rekognition
Amazon Web Servicesのインフラストラクチャを利用する代替エンジンです。
FACEIO Console ↗ でテストアプリケーションを作成し、ユーザー体験、アカウントフロー、デプロイ要件に適したエンジンとセキュリティ設定を確認してください。
顔ベクトルと生体認証ハッシュ
顔ベクトル（生体認証ハッシュとも呼ばれます）は、登録時に選択した認識エンジンが生成する浮動小数点値の配列です。FACEIO はこの生体認証ハッシュを fio.js で公開せず、アプリケーションには Facial ID と関連するレスポンスフィールドを返します。
Facial IDを公開プロフィールの識別子として扱ったり、ブラウザログ、分析イベント、公開サポートスレッド、URLに露出させたりしないでください。ローカルに保持する場合も、認証関連のアカウントデータと同じ注意を払いサーバー側に保存します。
プライバシーを設計する際は、このリファレンスに加えて、プライバシーのベストプラクティス、セキュリティのベストプラクティス、トラストセンターを確認してください。
開発者がFacial IDを扱う方法
- アカウントデータと一緒に保存 返された
facialIdをローカルユーザーレコードに関連付ける必要がある場合はバックエンドに保存します。 - サーバー側でチェック 返されたFacial IDを認可ロジックの入力として使い、単独でセッションを許可する値にはしないでください。
- payloadを最小限に保つ
payload登録時には、認証フローに実際に必要なデータだけを含めてください。 - Webhookと同期 Webhookイベント 登録または削除状態の変更をバックエンドへ伝える必要がある場合に使用します。
- ユーザー制御を提供 登録ユーザーが生体認証ログインを無効化したりFacial IDの削除を依頼したりできる手段を用意します。
- 保持期間を文書化 製品とプライバシー通知でFacial IDを保持、削除、紐付け解除する条件を定義します。
REST APIによるFacial IDの削除
Facial ID を削除するには、FACEIO REST API の /deletefacialid エンドポイントを使用します。対象アプリケーションから削除する Facial ID を、REST API リクエストで指定します。詳しくは、REST API リファレンスを参照してください。
削除が成功すると、そのFacial IDでユーザーを認証できなくなります。同じユーザーが後で再登録を選択した場合、FACEIOは新しい登録レコードと新しいFacial IDを作成します。
Facial IDを削除するタイミング
- ユーザーが生体認証ログインを無効化する、または顔認証への同意を撤回した場合。
- ユーザーがアカウントを削除する、または登録レコードの削除を依頼した場合。
- 保持ポリシーで登録が不要になった場合。
- サポートまたはセキュリティチームが現在のFacial IDとの紐付けを解除し、再登録を求める場合。
ユーザー削除、同意の撤回、保持に関する製品とプライバシーの指針は、プライバシーのベストプラクティスガイドを参照してください。バックエンドのイベント処理については、FACEIO Webhooks リファレンスを確認してください。削除とアカウント復旧のセキュリティ制御については、セキュリティのベストプラクティスで説明しています。
プライバシーとセキュリティに関する注意
Facial ID は認証、プライバシー、アカウント復旧、ユーザー同意に関わる識別子です。生体認証ハッシュではありませんが、セキュリティ上重要な識別子として扱ってください。FACEIO は生体認証ハッシュを保存、処理、または参照せず、選択した認識エンジンが管理します。アプリケーションはアカウント対応付けのために返された facialId を受け取ります。
5分で顔認証の統合を始める
FACEIOアプリケーションを作成し、 fio.jsを実装し、返された facialId を安全に扱い、バックエンドで必要になったら削除またはWebhookのフローを接続します。