トラブルシューティング

症状から原因を切り分ける

このページでは、Push! Passkeyの導入・実装・運用時に発生しやすい問題と、その確認手順を説明します。

調査は、利用者画面だけで判断せず、ブラウザの開発者ツール、顧客サイトのバックエンドログ、HTTPステータス、Push! Passkey APIのJSONレスポンス、request_idを組み合わせて行います。

APIキー、Cookie、セッションID、パスワード、APIの生レスポンスを利用者画面へ表示しないでください。

問い合わせや障害調査では、少なくとも次の情報を確認します。

• 発生日時
• 対象環境
• 対象ドメイン
• 処理種別
• request_id
• HTTPステータス
• error_code
• ブラウザとOS
• 再現手順

1. 最初に確認する項目

どの段階で失敗しているかを切り分ける

開発者ツールで確認する

• ConsoleにJavaScriptエラーがない
• NetworkでバックエンドエンドポイントへPOSTされている
• バックエンドエンドポイントの応答がJSONである
• HTTPステータスが想定どおりである
• 同じ処理が複数回送信されていない

2. JavaScriptが読み込まれない

確認するURL

https://auth.jintec.com/js/passkey.js

確認項目

• scriptタグのURLが正しい
• NetworkでHTTP 200が返っている
• 同じJavaScriptを複数回読み込んでいない
• Content Security Policyでブロックされていない
• ブラウザ拡張機能やプロキシで遮断されていない
• ページがHTTPSで表示されている

確認例

<script
	src="https://auth.jintec.com/js/passkey.js"
	defer></script>

CSPを使用している場合

script-srcにPush! PasskeyのJavaScript配信元が許可されているか確認します。

必要以上に広いワイルドカードを許可せず、使用する接続先だけを追加してください。

3. ボタンを押しても反応しない

ボタン属性を確認する

<button
	type="button"
	class="push_btn auth"
	data-pushpasskey="auth"
	data-endpoint="/pushpasskey/endpoint"
	data-success-url="/login/callback">
	パスキー認証
</button>

確認する症状

• クリックイベントが他のJavaScriptで停止されていない
• ボタンにdisabledが残っていない
• 透明な要素がボタンの上に重なっていない
• フォーム送信によりページが先に遷移していない

4. バックエンドエンドポイントへ接続できない

Networkで確認する

• 要求先URL
• HTTPメソッド
• Content-Type
• リクエストJSON
• HTTPステータス
• レスポンス本文

404の場合

data-endpointのパスと、実際の公開ディレクトリを確認します。

data-endpoint="/pushpasskey/endpoint"

405の場合

顧客バックエンドエンドポイントがPOSTだけを許可しているか、WebサーバがPOSTを拒否していないか確認します。以下はPHPでの確認例です。

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
	http_response_code(405);
	header('Allow: POST');
	exit;
}

500の場合

アプリケーションログ、設定ファイルの読込パス、構文・実行時エラー、権限、環境変数を確認します。

本番画面へバックエンドのエラー詳細を表示しないでください。

5. バックエンドエンドポイントの応答がJSONではない

主な原因

• バックエンドの警告やデバッグ出力がJSONの前に出力されている
• Webサーバの404、405、500ページがHTMLで返っている
• 接続先URLがAPIではなく通常ページになっている
• 認証やWAFによりHTMLのエラーページへ転送されている
• 文字コードやBOMがレスポンス先頭に含まれている

正しいレスポンスヘッダー

header('Content-Type: application/json; charset=UTF-8');
header('Cache-Control: no-store');

JSON変換を厳密に行う

try {
	$response = json_decode(
		$response_body,
		true,
		512,
		JSON_THROW_ON_ERROR
	);
} catch (JsonException $e) {
	throw new RuntimeException(
		'APIの応答がJSONではありません。'
	);
}

調査時はHTTPステータスと生レスポンスを内部ログへ一時的に記録できますが、APIキーや個人情報を除外してください。

6. HTTP 405が返る

確認項目

• Push! Passkey APIへPOSTしている
• APIパスが正しい
• 末尾に誤った拡張子やスラッシュを付けていない
• リバースプロキシやnginxでPOSTが許可されている
• 別の仮想ホストへ接続していない

正式なAPIパス

https://auth.jintec.com/regist_url
https://auth.jintec.com/auth_url
https://auth.jintec.com/regist_result
https://auth.jintec.com/auth_result

HTTPクライアント設定例（PHP cURL）

curl_setopt_array($curl, [
	CURLOPT_POST => true,
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_HTTPHEADER => [
		'Content-Type: application/json',
		'Accept: application/json',
	],
	CURLOPT_POSTFIELDS => $json_body,
]);

7. APIキーエラーになる

関連するerror_code

• api_key_required
• invalid_api_key

確認項目

• JSON本文の項目名がapi_keyである
• APIキーが空文字ではない
• 前後に空白や改行が含まれていない
• 開発環境と本番環境を取り違えていない
• 対象ドメイン用に発行されたAPIキーである
• 管理ツールで対象ドメインが有効である
• 古いAPIキーや無効化済みAPIキーを使用していない

送信方法

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"user_key": "customer_user_123",
	"return_page_url": "https://example.com/login/callback"
}

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

8. user_key_requiredが返る

登録処理

登録対象ユーザーは、顧客サイトのログインセッションから取得します。

current_user = server_session.get_authenticated_user()
if current_user is not authenticated:
    return login_required
user_key = current_user.external_authentication_key

認証処理

ログイン前にメールアドレスなどを入力する構成では、顧客サイトのDBから対象ユーザーを検索し、Push! Passkey連携用のuser_keyへ変換します。

確認項目

• user_keyがnullや空文字ではない
• 別ユーザーへ再利用されない識別子である
• DB検索結果が1件に確定している
• ブラウザのdata属性だけで決定していない

9. 登録URL・認証URLが発行されない

正式な要求項目

{
	"api_key": "xxxxxxxxxxxxxxxx",
	"user_key": "customer_user_123",
	"return_page_url": "https://example.com/callback"
}

確認項目

• API URLが正しい
• POSTで送信している
• JSON本文がUTF-8である
• api_keyとuser_keyが設定されている
• return_page_urlがHTTPSである
• HTTPステータスが2xxである
• レスポンスにrequest_idがある
• 登録時はregist_url、認証時はauth_urlがある

DBエラー

次のエラーはPush! Passkey側の内部処理に関係します。

• DB_DOMAIN_SELECT_ERROR
• DB_REQUEST_INSERT_ERROR

発生日時と可能であればrequest_idを記録し、連続再送を避けて管理者へ連絡してください。

10. 認証画面へ遷移しない

レスポンス項目を確認する

登録URL発行ではregist_url、認証URL発行ではauth_urlが返されます。

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

確認項目

• レスポンスJSONのURL項目名を取り違えていない
• redirect_urlへ変換する顧客endpoint処理が正しい
• URLのホストがauth.jintec.comである
• ポップアップブロックの影響を受けていない
• JavaScriptエラーで遷移処理が停止していない
• URLの有効期限が切れていない

11. 認証画面から顧客サイトへ戻らない

return_page_urlを確認する

• https://から始まる
• 顧客サイトの正しいドメインである
• URLに入力ミスがない
• 外部公開されたURLである
• 認証やIP制限で遮断されていない

戻り先で使用されるパラメータ

• pp_kind
• pp_request_id
• pp_status
• pp_error_code

戻り先ページでは、これらの値を画面表示だけに使わず、バックエンドの結果照会開始に使用します。

12. 結果照会でrequest_not_foundが返る

確認項目

• URL発行APIから返されたrequest_idを保存している
• request_idの一部が欠落していない
• pp_request_idが保存値と一致する
• 別環境のrequest_idを使用していない
• 手動入力した値を使用していない

保存例

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

13. request_domain_mismatchが返る

主な原因

• URL発行時と結果照会時でAPIキーが異なる
• 別顧客のAPIキーを使用している
• 開発環境と本番環境の設定が混在している
• 複数ドメインの設定選択に誤りがある

対応

request_idと一緒に、顧客サイト側のテナント、環境、対象ドメインを保存してください。

結果照会時は、URL発行時と同じ設定からAPIキーを取得します。

14. request_kind_mismatchが返る

正しい対応関係

ブラウザのpp_kindだけで照会先を決めず、顧客サイト側で保存したkindを使用してください。

15. REQUEST_EXPIREDが返る

有効期限

登録URLと認証URLの有効期限は、発行から10分間です。

対応

• 古いURLを再利用しない
• 同じrequest_idで結果照会を繰り返さない
• ポーリングを停止する
• 新しい登録URLまたは認証URLを発行する

利用者向け表示例

「認証の有効時間が終了しました。最初からやり直してください。」

16. statusがissuedのまま変わらない

意味

issuedは、URL発行済みで、利用者による登録・認証処理がまだ開始されていない状態です。

確認項目

• 利用者が正しい認証URLを開いている
• URLの有効期限内である
• 別タブや別端末で古いURLを開いていない
• 認証画面が途中で閉じられていない
• 別のrequest_idを照会していない

17. statusがin_progressのまま変わらない

意味

in_progressは、利用者が登録・認証処理を開始したものの、まだ完了していない状態です。

確認項目

• 端末の本人確認画面が表示されたままになっていない
• 利用者がキャンセルしていない
• ブラウザやOSのパスキー画面が応答している
• ネットワークが途中で切断されていない
• 期限切れになっていない

一定時間後も変化しない場合は、利用者へ再試行を案内し、新しいURLを発行してください。

18. 認証成功後もログインできない

認証結果の確認

if (
	$response['status'] === 'success'
	&& $response['is_completed'] === true
	&& $response['is_success'] === true
) {
	// 顧客サイト側のログイン処理
}

照合する項目

• request_idが保存値と一致する
• kindがauthである
• user_keyが対象ユーザーと一致する
• 結果が未使用である
• ユーザーが利用停止・退会・期限切れではない
• 対象サービスの権限を持っている

セッション発行

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

Push! Passkeyの認証成功だけでは、顧客サイトのログインセッションは自動発行されません。

19. セッションが維持されない

Cookie設定を確認する

• SecureがHTTPS環境で使用されている
• HttpOnlyが設定されている
• SameSiteが遷移構成に合っている
• DomainとPathが狭すぎない
• Cookieの有効期限が短すぎない
• サブドメイン間でセッションを共有する要件が整理されている

確認項目

• リダイレクト先で同じアプリケーションセッションを参照できる
• ロードバランサ配下でセッション共有ができている
• セッションストアの接続・権限・共有設定に問題がない
• セッションID再生成後のCookieがブラウザへ返っている

20. 同じ処理が複数回実行される

主な原因

• ボタンの連続クリック
• JavaScriptの二重読込
• 複数タブからの同時操作
• タイムアウト時の無条件再送
• Webhookの重複受信
• 戻る・再読み込みによる再処理

対策

• 処理中はボタンを無効化する
• request_idへ一意制約を設定する
• usedフラグを条件付きUPDATEする
• 同じ結果を一度だけ使用する
• Webhook処理を冪等にする

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

21. TLS・証明書エラーが発生する

確認項目

• サーバ時刻が正しい
• CA証明書が更新されている
• auth.jintec.comを正しく名前解決できる
• プロキシが独自証明書へ置き換えていない
• 接続先ホスト名が正しい

無効化しない

CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,

TLS検証を無効にして問題を回避しないでください。

22. timeoutが発生する

設定例

CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,

確認項目

• DNS応答時間
• FWやプロキシの接続制限
• サーバの外向きHTTPS通信
• Push! Passkey APIの応答時間
• 同時接続数

再試行

URL発行APIがタイムアウトした場合、Push! Passkey側で処理が完了している可能性があります。

無条件に即時再送せず、二重処理を防止し、回数と間隔を制限してください。

23. ログに必要な情報がない

記録する情報

• timestamp
• request_id
• kindまたはaction
• 接続したAPI
• HTTPステータス
• error_code
• 処理段階
• 再試行回数

記録しない情報

• APIキー
• Cookie
• セッションID
• パスワード
• 秘密鍵

顧客サイトとPush! Passkeyの調査を対応付けるため、request_idを必ず記録してください。

24. 問い合わせ時に伝える情報

技術担当者が整理する項目

APIキー、Cookie、パスワード、個人情報は問い合わせ本文へ記載しないでください。

25. 動作確認チェックリスト

• passkey.jsがHTTP 200で読み込まれる
• ボタン属性が正しい
• バックエンドエンドポイントへPOSTされる
• バックエンドエンドポイントがJSONを返す
• api_keyとuser_keyがJSON本文へ設定される
• 正式なAPIパスへ接続している
• request_idを保存している
• kindと結果照会先が一致している
• statusと判定フラグを確認している
• user_keyを照合している
• 認証成功後にセッションを発行している
• 成功結果を再利用できない
• APIキーやCookieをログへ記録していない

26. 次に確認するページ

エラーコード

各error_codeの発生条件、確認項目、利用者向け表示を確認します。

エラーコードを読む

APIリファレンス

正式なAPI URL、JSON項目、レスポンス項目を確認します。

APIリファレンスを読む

認証結果の受け取り

request_id、kind、user_key、statusの照合とセッション発行を確認します。

認証結果の受け取りを読む

まとめ

画面、endpoint、API、結果、セッションの順に切り分ける

Push! Passkeyの問題調査では、利用者画面だけを確認するのではなく、ブラウザ、顧客バックエンドエンドポイント、Push! Passkey API、結果照会、顧客サイトのセッション発行を順番に切り分けます。

HTTPステータス、JSON、error_code、request_idを確認すると、原因を特定しやすくなります。

期限切れや整合性エラーでは、古い処理を再利用せず、新しいURLを発行してください。

認証成功後も、顧客サイト側でuser_key、ユーザー状態、権限を確認し、セッションIDを再生成してログインを完了します。