パスキーを知る
パスキーの基礎
パスキーの登録方法
パスキーの削除方法
開発者向け解説
Push! Passkeyを知る
Push! Passkeyとは
システム構成・責任分界
利用を開始する
管理ツールの使い方
実装する
実装ガイド
フロントエンド実装
PHPでの実装
Rubyでの実装
Node.jsでの実装
Pythonでの実装
Javaでの実装
C#での実装
結果を連携する
認証結果の受け取り
調べる
APIリファレンス
エラーコード
対応環境
セキュリティ上の注意
トラブルシューティング
よくある質問

認証結果の受け取り

Push! Passkeyの処理結果を確認し、顧客サイトの後続処理へ連携する

このページでは、Push! Passkeyで実行されたパスキー登録・認証の結果を、顧客サイト側で安全に受け取る方法を説明します。

登録URLまたは認証URLが発行された時点では、パスキー処理はまだ完了していません。

利用者がPush! Passkey認証画面で操作し、WebAuthnの検証が完了した後に、登録・認証結果が確定します。

顧客サイトは、URL発行時に取得したrequest_idを保存し、登録結果照会APIまたは認証結果照会APIへ送信して処理結果を確認します。

認証成功後のログインセッションは、Push! Passkeyではなく顧客サイト側で発行します。

  • URL発行時にrequest_idを保存する方法
  • 認証画面から戻る際のURLパラメータ
  • 登録結果照会APIと認証結果照会API
  • statusと判定用フラグ
  • request_id、kind、user_keyの照合
  • 認証成功後のユーザー状態確認
  • ログインセッション発行
  • 結果の再利用防止
  • リダイレクト、ポーリング、Webhookの使い分け
  • エラー、期限切れ、キャンセル時の処理

1. 処理開始と処理完了を分けて考える

URL発行APIの成功は認証成功ではない

顧客サイトが次のAPIへ要求し、登録URLまたは認証URLを取得できた時点では、利用者によるパスキー操作はまだ開始または完了していません。

用途 API
登録URL発行 https://auth.jintec.com/regist_url
認証URL発行 https://auth.jintec.com/auth_url

URL発行APIのレスポンスに含まれるrequest_idは、後で処理結果を照会するための識別子です。

結果確定までの流れ

  1. 顧客サイトが登録URLまたは認証URLを発行する
  2. 顧客サイトがrequest_idを保存する
  3. 利用者をPush! Passkey認証画面へ遷移させる
  4. 利用者がパスキー登録または認証を実行する
  5. Push! PasskeyがWebAuthn結果を検証する
  6. Push! Passkeyがトランザクション状態を更新する
  7. 顧客サイトが結果照会APIを呼び出す
  8. 顧客サイトが結果を照合する
  9. 認証成功時は顧客サイトがログインセッションを発行する
登録URLまたは認証URL発行、request_id保存、Push! Passkey認証画面、利用者端末でのパスキー操作、WebAuthn検証、結果照会、顧客サイトのセッション発行までを左から右へ示す横長ワイドの処理フロー図。URL発行と認証成功、認証成功とセッション発行が別処理であることを境界線で強調する。白背景、青緑系、法人向け。画像内のテキストはURL発行、request_id、認証画面、検証、結果照会、セッションなど必要最低限の短い用語だけとし、説明文章はできるだけ排除する。

2. request_idを保存する

URL発行APIのレスポンス

認証URL発行APIのレスポンス例は次のとおりです。

{
	"ok": true,
	"kind": "auth",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"auth_url": "https://auth.jintec.com/auth?u=u_1234567890abcdef1234567890abcdef",
	"expire_at": "2026-07-17T08:30:00+09:00"
}

登録URL発行の場合は、kindがregistとなり、URL項目名はregist_urlになります。

保存する項目

顧客サイトでは、少なくとも次の項目を保存します。

項目 用途
request_id 結果照会APIへ送信し、開始した処理と結果を対応付ける
kind 登録または認証の処理種別を照合する
expire_at URLとトランザクションの有効期限を確認する
使用済み状態 同じ成功結果を複数回使用しないようにする

サーバー側セッションへ保存する例

session.set("pushpasskey_transaction", {
    "request_id": request_id,
    "kind": "auth",
    "expire_at": expire_at,
    "used": false
})

DBへ保存する場合

Webhook、複数サーバ、監査ログ、長時間の結果確認が必要な場合は、セッションではなくDBへ保存します。

request_idには一意制約を設定し、同じ結果の重複処理を防止してください。

認証開始時点ではユーザーは未確定です。認証結果が成功したときに返るuser_keyを使って顧客サイトのユーザーDBを検索し、状態と権限を確認してからセッションを発行します。

登録URLと認証URLの有効期限は、現在の正式仕様では発行から10分間です。

3. 認証画面から戻る際のパラメータ

顧客ページへ付加される情報

Push! Passkey認証画面から顧客サイトへ戻る際、次のURLパラメータが使用されます。

パラメータ 内容
pp_kind 登録または認証の処理種別
pp_request_id 結果照会に使用するrequest_id
pp_status 認証画面側での処理状態
pp_error_code 失敗時のエラーコード

URL例は次のとおりです。

https://example.com/login/callback
?pp_kind=auth
&pp_request_id=u_1234567890abcdef1234567890abcdef
&pp_status=success
&pp_error_code=

URLパラメータだけで成功判定しない

pp_status=successが付いていても、それだけを根拠にログインセッションを発行してはいけません。

URLパラメータは、顧客サイトが結果照会を開始するための情報として使用します。

顧客サイトのバックエンドから、pp_request_idを使って認証結果照会APIを呼び出し、正式な結果を確認してください。

request_idの書き換えを想定する

URLパラメータは利用者が変更できます。

pp_request_idが、顧客サイト側で保存したrequest_idと一致することを確認してください。

4. 結果照会API

正式な接続先

用途 API
登録結果照会 https://auth.jintec.com/regist_result
認証結果照会 https://auth.jintec.com/auth_result

リクエストJSON

結果照会APIには、URL発行時と同じドメイン用APIキーとrequest_idを送信します。

{
	"api_key": "管理ツールで発行したAPIキー",
	"request_id": "u_1234567890abcdef1234567890abcdef"
}

項目 必須 内容
api_key 必須 URL発行時に使用した対象ドメイン用APIキー
request_id 必須 URL発行APIから返された識別子

APIキーの取り扱い

APIキーはHTTPヘッダーではなく、現在の正式仕様ではJSON本文のapi_keyへ設定します。

APIキーを設定するのは顧客サイトのバックエンドです。ブラウザから受け取った値をAPIキーとして使用してはいけません。

顧客サイトのバックエンドから登録結果照会APIまたは認証結果照会APIへ、JSON本文のapi_keyとrequest_idを送信し、status、user_key、error_code、判定フラグを受け取る通信構成図。横長ワイド、白背景、青緑系、法人向け。画像内のテキストはbackend、api_key、request_id、regist_result、auth_result、status、user_key、errorなど必要最低限の短い用語だけとし、説明文章はできるだけ排除する。

5. 結果照会レスポンス

正式なレスポンス例

{
	"ok": true,
	"kind": "auth",
	"request_id": "u_1234567890abcdef1234567890abcdef",
	"status": "success",
	"user_key": "customer_user_123",
	"tenant_id": 1,
	"domain_id": 10,
	"personal_id": 100,
	"issued_at": "2026-07-17 08:10:00",
	"started_at": "2026-07-17 08:10:05",
	"completed_at": "2026-07-17 08:10:12",
	"expire_at": "2026-07-17 08:20:00",
	"return_page_url": "https://example.com/login",
	"return_to": {
		"regist_success": "",
		"regist_failed": "",
		"auth_success": "",
		"auth_failed": ""
	},
	"fallback_url": "/passkey_callback.html",
	"error_code": "",
	"error_message": "",
	"is_completed": true,
	"is_success": true,
	"is_failed": false,
	"is_expired": false
}

主なレスポンス項目

項目 内容
ok 結果照会API自体が正常に処理されたか
kind 登録または認証の処理種別
request_id 対象トランザクションの識別子
status 現在の処理状態
user_key 顧客サイトから連携されたユーザー識別子
issued_at 登録・認証URLを発行した日時
started_at 利用者が処理を開始した日時
completed_at 処理が完了した日時
expire_at 処理の有効期限
error_code 失敗時のエラーコード
error_message 失敗時のエラー内容
is_completed 処理が完了状態か
is_success 処理が成功したか
is_failed 処理が失敗したか
is_expired 処理が期限切れか

6. statusを判定する

5種類のstatus

status 内容 顧客サイト側の主な処理
issued URL発行済み、利用者による処理開始前 処理中として待機または再照会する
in_progress 登録・認証処理中 完了するまで待機または再照会する
success 登録・認証が正常終了 照合後に登録完了処理またはセッション発行を行う
failed 登録・認証が失敗 error_codeを記録し、利用者へ再試行を案内する
expired 有効期限切れ 古い処理を使用せず、新しいURLを発行する

判定用フラグも確認する

処理完了と成功を確認するときは、次の条件を確認します。

if (
	$response['status'] === 'success'
	&& $response['is_completed'] === true
	&& $response['is_success'] === true
) {
	// 成功時の処理
}

ok=trueは、結果照会APIが正常に応答したことを示します。パスキー登録・認証の成功は、statusと判定用フラグで確認してください。

issued、in_progress、success、failed、expiredの5種類のstatusを横方向に配置し、待機、完了、再試行、再発行の分岐をアイコンで示す横長ワイドのステータス遷移図。白背景、青緑系、法人向け。successは緑、failedとexpiredは警告色を控えめに使い、画像内のテキストはstatus名と短い処理名だけに限定し、説明文章はできるだけ排除する。

7. 結果を照合する

レスポンスをそのまま信用しない

認証結果が成功していても、顧客サイトが開始した処理と一致することを確認してから後続処理を行います。

照合する項目

  • request_idが顧客サイトで保存した値と一致する
  • kindが開始した登録・認証の種別と一致する
  • 登録結果ではuser_keyが登録開始時の対象ユーザーと一致する
  • 認証結果では返されたuser_keyに対応する有効なユーザーが顧客DBに存在する
  • statusが期待する状態である
  • is_completedが正しい
  • 成功時はis_successがtrueである
  • 期限切れではない
  • 同じ結果が未使用である

トランザクション照合の例

transaction = session.get("pushpasskey_transaction")

if (!is_array($transaction)) {
	throw new RuntimeException(
		'開始した認証情報が見つかりません。'
	);
}

if (
	!hash_equals(
		$transaction['request_id'],
		$response['request_id']
	)
) {
	throw new RuntimeException(
		'request_idが一致しません。'
	);
}

if ($response['kind'] !== $transaction['kind']) {
	throw new RuntimeException(
		'処理種別が一致しません。'
	);
}

if ($response['kind'] === 'regist' && !hash_equals(
	$transaction['user_key'],
	$response['user_key']
)) {
	throw new RuntimeException('登録対象のuser_keyが一致しません。');
}

if ($response['kind'] === 'auth' && empty($response['user_key'])) {
	throw new RuntimeException('認証ユーザーを確認できません。');
}

if ($transaction['used'] === true) {
	throw new RuntimeException(
		'この認証結果は使用済みです。'
	);
}

文字列比較

request_idや登録時のuser_keyなど、保存値との比較には必要に応じてhash_equals()を使用します。認証時のuser_keyは事前値と比較するのではなく、顧客DBのユーザー検索キーとして扱います。

8. パスキー登録結果を処理する

登録成功時

登録結果が成功した場合は、顧客サイト側で必要に応じて次の処理を行います。

  • パスキー登録済み状態を更新する
  • 登録完了日時を記録する
  • 登録完了画面を表示する
  • 利用者へ登録完了通知を送る
  • 監査ログへrequest_idを記録する

Credential IDと公開鍵そのものはPush! Passkey側で管理されます。

登録失敗時

status=failedの場合は、error_codeを内部ログへ記録し、利用者には分かりやすい日本語メッセージを表示します。

登録結果でログインセッションを発行しない

登録成功は、新しいパスキーの登録が完了したことを示します。

登録成功だけを根拠に、新しいログインセッションを発行する設計にする場合は、登録前の本人確認と現在のセッション状態を慎重に確認してください。

9. 認証成功後のユーザー状態確認

パスキー認証成功とサービス利用可否は別の判断

Push! Passkeyの認証結果が成功しても、顧客サイトのユーザーが現在ログイン可能とは限りません。

セッション発行前に、顧客サイトのDBで次の状態を確認します。

  • ユーザーが存在する
  • 退会済みではない
  • 利用停止中ではない
  • 契約期限切れではない
  • 管理者によるロック中ではない
  • 対象サービスを利用する権限がある
  • user_keyが別ユーザーへ再利用されていない

認証と認可を分ける

  • 認証：Push! Passkeyが登録済みパスキーによる署名を確認する
  • 認可：顧客サイトが利用可能な機能や権限を判断する

管理者権限や有料機能の利用可否は、顧客サイト側で判断します。

10. ログインセッションを発行する

顧客サイト側で発行する

結果照会とユーザー状態確認が完了した後に、顧客サイトのログインセッションを発行します。

セッションIDを再生成する

session.rotate_id()
session.set("user_id", internal_user_id)
session.set("authenticated_at", current_time)
session.set("auth_method", "pushpasskey")
session.set("pushpasskey_transaction.used", true)

Cookieの設定

セッションCookieには、利用環境に応じて次の属性を設定します。

  • Secure
  • HttpOnly
  • SameSite
  • 適切な有効期限
  • 必要最小限のDomainとPath

成功結果を使用済みにする

セッション発行と同時に、対象request_idを使用済みへ更新します。

ブラウザの再読み込み、戻る操作、同じURLへの再アクセスによって、同じ認証結果から複数のセッションを発行しないようにしてください。

Push! Passkeyの認証成功後に、request_id照合、user_key照合、ユーザー状態確認、権限確認、セッションID再生成、Cookie発行、使用済み更新、ログイン完了へ進む横長ワイドのフロー図。白背景、青緑系、法人向け。画像内のテキストはresult、request_id、user_key、status、権限、session、Cookie、used、loginなど必要最低限の短い用語だけとし、説明文章はできるだけ排除する。

11. 結果の再利用を防止する

同じrequest_idを一度だけ使用する

認証成功結果を複数回使用できると、ブラウザの再読み込みやURL共有によって、意図しないセッション発行が行われる可能性があります。

顧客サイト側で、各request_idの使用状態を管理してください。

DBで管理する例

UPDATE pushpasskey_requests
SET
	used = 1,
	used_at = CURRENT_TIMESTAMP
WHERE
	request_id = :request_id
	AND used = 0;

更新件数が0件の場合は、すでに使用済みである可能性があります。

同時実行を考慮する

複数リクエストが同時に同じ結果を処理する可能性がある場合は、DBトランザクション、一意制約、条件付きUPDATEなどで排他制御します。

12. リダイレクトによる結果連携

利用者を顧客サイトへ戻す

return_page_urlを指定すると、Push! Passkeyでの処理後に利用者を顧客サイトへ戻せます。

リダイレクト方式は、利用者のブラウザ操作と連続して結果確認を行う場合に適しています。

リダイレクト後の処理

  1. URLパラメータからpp_request_idを取得する
  2. 顧客サイトで保存したrequest_idと一致するか確認する
  3. 顧客バックエンドから結果照会APIを呼び出す
  4. kind、status、判定フラグを確認し、認証成功時のuser_keyから顧客DBのユーザーを取得する
  5. ユーザー状態を確認する
  6. セッションを発行する
  7. URLから一時パラメータを除去した画面へ遷移する

URLから一時パラメータを残さない

処理完了後は、pp_request_idなどがブラウザのアドレス欄へ残り続けないように、通常のログイン後URLへリダイレクトする方法を推奨します。

Refererへの露出を抑える

一時パラメータを含むページから外部サイトへ遷移する前に、パラメータを除去してください。

13. ポーリングによる結果照会

一定間隔で結果を確認する

利用者が別端末で認証する場合や、同じ画面で完了を待つ場合は、結果照会APIを一定間隔で呼び出す方法があります。

過剰な照会を避ける

短すぎる間隔で照会すると、顧客サイトとPush! Passkey双方へ不要な負荷がかかります。

数秒間隔など、利用者体験と負荷のバランスを考慮した間隔を設定してください。

終了条件

  • is_completed=trueになった
  • status=successになった
  • status=failedになった
  • status=expiredになった
  • 顧客サイト側の待機時間を超過した

完了後はポーリングを停止してください。

14. Webhookによる結果連携

サーバ間で結果通知を受ける

Webhookを利用すると、利用者のブラウザ操作とは別に、Push! Passkeyから顧客サイトのバックエンドへ結果通知を受け取る構成にできます。

Webhookは、次のような構成に適しています。

  • 利用者がブラウザを閉じる可能性がある
  • 別端末で認証を行う
  • バックグラウンドで結果を記録したい
  • 業務処理や通知を非同期で実行したい
  • 結果をDBへ確実に保存したい

Webhook受信時も結果照合する

Webhookの内容だけを無条件に信用せず、送信元検証、署名検証、request_id照合、重複受信対策を行います。

現在の実装で使用するWebhookの正式な通知項目、署名形式、再送仕様は、APIリファレンスで定義します。

冪等性を確保する

同じWebhookが複数回届いても、同じ登録完了処理やセッション関連処理を重複実行しないようにします。

ブラウザに対するログインセッション発行は、通常は利用者のリダイレクト後処理で行います。Webhookだけで利用者ブラウザのCookieを発行することはできません。

リダイレクト、ポーリング、Webhookの3つの結果連携方式を横並びで比較する横長ワイドの法人向けインフォグラフィック。リダイレクトはbrowser、ポーリングはrepeat、Webhookはserver to serverのアイコンで示す。白背景、青緑系。画像内のテキストはredirect、polling、Webhook、browser、serverなど必要最低限の短い用語だけとし、説明文章はできるだけ排除する。

15. 連携方式の選び方

方式 適した用途 注意点
リダイレクト 同じブラウザで認証し、そのままログインを完了する URLパラメータだけで成功判定しない
ポーリング 別端末認証や完了待ち画面を表示する 照会間隔、停止条件、タイムアウトを設定する
Webhook 非同期処理、DB更新、通知、監査ログ 送信元検証、重複受信、再送を考慮する

複数方式を併用することもできます。

例えば、Webhookで結果をDBへ保存し、利用者が戻った際に顧客サイトのDBと結果照会APIを確認してセッションを発行する構成があります。

16. エラーと期限切れを処理する

結果照会APIのエラー

結果照会APIでは、少なくとも次のエラーコードを処理します。

error_code 内容
api_key_required APIキーが指定されていない
request_id_required request_idが指定されていない
invalid_api_key APIキーが不正または無効
request_not_found 対象request_idが存在しない
request_domain_mismatch APIキーのドメインとリクエストのドメインが一致しない
request_kind_mismatch 登録・認証の処理種別が一致しない
REQUEST_EXPIRED リクエストの有効期限切れ
DB_REQUEST_SELECT_ERROR リクエスト情報の取得に失敗

利用者向け表示

状態 表示例
失敗 「認証を完了できませんでした。もう一度お試しください。」
期限切れ 「認証の有効時間が終了しました。最初からやり直してください。」
結果不一致 「認証結果を確認できませんでした。」
通信エラー 「通信に失敗しました。時間をおいて再度お試しください。」

内部のerror_code、APIの生レスポンス、APIキー、ファイルパスは、利用者向け画面へ表示しないでください。

17. ログを記録する

記録する情報

  • 処理日時
  • request_id
  • kind
  • status
  • error_code
  • 顧客サイト内部で追跡できるユーザー識別子
  • 結果照会のHTTPステータス
  • セッション発行の成否
  • 結果を使用済みにした日時

記録しない情報

  • APIキー
  • セッションCookie
  • パスワード
  • 秘密鍵
  • 不要な個人情報

顧客サイトとPush! Passkeyのログを対応付ける

request_idを共通の追跡値として使用すると、顧客サイト側のログとPush! Passkeyのトランザクションを照合しやすくなります。

18. 言語別の実装例

結果照会、トランザクション照合、ユーザー状態・権限確認、セッション発行は、利用するバックエンド言語の実装ページを参照してください。

19. 動作確認

request_id

  • URL発行時にrequest_idを保存できる
  • リダイレクト後のpp_request_idと照合できる
  • 存在しないrequest_idを拒否できる
  • 別ユーザーのrequest_idを拒否できる

結果照会

  • regist_resultへ正しいJSONを送信できる
  • auth_resultへ正しいJSONを送信できる
  • JSON本文へapi_keyとrequest_idを設定している
  • HTTP 2xx以外を成功として扱わない
  • JSON以外の応答を拒否できる

status

  • issuedを処理中として扱える
  • in_progressを処理中として扱える
  • success時だけ成功処理を行う
  • failed時にエラー案内を表示する
  • expired時に新しい処理を開始できる

照合

  • kind不一致を拒否できる
  • user_key不一致を拒否できる
  • 期限切れを拒否できる
  • 使用済み結果を拒否できる

セッション

  • 利用停止ユーザーへセッションを発行しない
  • 認証成功後にセッションIDを再生成する
  • Cookieへ適切な属性を設定する
  • 同じ結果から複数回セッションを発行しない
認証結果連携の動作確認項目をrequest_id、redirect、API、status、kind、user_key、expired、used、session、logの10項目に分けた2段構成のチェックリスト型インフォグラフィック。横長ワイド、白背景、青緑系、法人向け。画像内のテキストは各項目名だけに限定し、説明文章はできるだけ排除する。

20. 次に確認するページ

APIリファレンス

URL発行APIと結果照会APIの正式なリクエスト項目、レスポンス項目、HTTPステータスを確認します。

APIリファレンスを読む

エラーコード

URL発行、登録、認証、結果照会で返されるエラーコードを確認します。

エラーコードを読む

トラブルシューティング

結果を取得できない、statusが変化しない、セッションを発行できない場合の確認方法を案内します。

トラブルシューティングを読む

まとめ

結果照会とセッション発行を顧客サイトのバックエンドで行う

Push! Passkeyの登録・認証結果を安全に利用するためには、URL発行時に取得したrequest_idを保存し、顧客サイトのバックエンドから結果照会APIを呼び出します。

結果処理で重要となる点は次のとおりです。

  • URL発行成功を登録・認証成功として扱わない
  • URLパラメータだけで成功判定しない
  • APIキーとrequest_idをJSON本文へ設定して結果照会する
  • request_id、kind、user_keyを保存値と照合する
  • statusと判定用フラグを確認する
  • 認証成功後も顧客サイトのユーザー状態と権限を確認する
  • 認証後にセッションIDを再生成する
  • 同じ成功結果を複数回使用しない
  • エラーコードと内部ログを利用者向け表示から分離する
  • リダイレクト、ポーリング、Webhookを要件に応じて使い分ける

Push! Passkeyはパスキー認証結果を提供し、顧客サイトはその結果を確認して、自社サービスのログイン状態と権限を確定します。