メインコンテンツまでスキップ

iPhoneやSafariでAPIと連携できないです。

症状​

Safari（macOS / iOS / iPadOS）でCookie認証が断続的に失敗します。ログイン直後にAPIが 401 / 403 を返す、ユーザーが何度もログアウトされる、同じフローがChromeでは動作する、といった事象が起きます。これは Kuroco API が発行する認証CookieがサードパーティCookieとして扱われているためです。

なぜ発生するのか​

Cookieがファーストパーティとして扱われるのは、Cookieのホストとページが同じ**登録可能ドメイン（eTLD+1）**を共有している場合のみです。クロスサイトCookieに対するブラウザの既定動作は次の通りです。

ブラウザクロスサイトCookieの既定動作
Safariデフォルトでブロック（SameSite=None; Secure を付けても、「サイト越えトラッキングを防ぐ」が既定で有効なため拒否）
FirefoxTotal Cookie Protectionによりトップレベルサイトごとに分離
Chrome / EdgeSameSite=None; Secure で許可

Kurocoのデフォルト構成では登録可能ドメインが異なります — www.example.com（eTLD+1: example.com）と example.a.kuroco.app（eTLD+1: kuroco.app）— このため Safari は認証Cookieを破棄します。

推奨構成​

カスタム APIドメインを設定し、フロントエンドとAPIで同じ登録可能ドメインを共有します。次のどちらでも構いません。

  • https://www.example.com + https://api.example.com
  • https://example.com + https://api.example.com

これによりCookieはファーストパーティ扱いとなり、デフォルトの SameSite=Lax で十分、Safari / Firefox の制限も対象外になります。

設定手順:

  1. 独自ドメイン/TLS証明書で api.example.com を登録し、Kuroco環境に紐づける
  2. アカウント設定からAPIベースURLを更新する

⚠️ 注意：Safariの7日間Cookie上限​

親ドメインを揃えても、SafariはCookieの Max-Age / Expires を7日に制限する場合があります。KurocoのカスタムAPIドメインは <sitekey>.g.kuroco.app へのCNAMEで構成されており、WebKitのCNAMEクローキング対策（Safari 14で導入、Safari 16.4でページのサーバーとIPレンジが大きく異なる A/AAAA レコードにも拡張）がこの種のホストのCookieを7日に丸めるためです。CNAMEからAレコードに切り替えても回避できません — KurocoのAPI配信IPはフロントの配信IPとは別レンジになるため、Safari 16.4 以降は同じ扱いになります。

Cookie自体はブロックされず、アクティブなセッション中は正常に動作します。ただし7日以上アクセスのないユーザーは再ログインが必要になります。

ユースケース影響
毎日利用される社内ツール / ダッシュボード✅ 実質的に問題なし
マーケティングサイト / 短期セッション用途✅ 実質的に問題なし
ログイン頻度が低い一般公開サイト⚠️ Safariユーザーが予期せずログアウトされる可能性あり
Safariで長期の「ログイン状態を保持」❌ Cookieでは不可。トークン認証を利用

回避策：トークン認証​

トークン認証に切り替えてください。アクセストークンはCookieではなく X-RCMS-API-ACCESS-TOKEN リクエストヘッダーで送られるため、ITPのCookie制限の対象外です。リフレッシュトークンを使えば、ユーザーに再ログインを強いることなくアクセストークンを更新できます。

設定例​

❌ API連携ができない例（Safariがクロスサイト Cookie をブロック）​

  • フロントエンド：https://www.example.com
  • API：https://example.a.kuroco.app

✅ 推奨構成​

  • フロントエンド：https://www.example.com（または https://example.com）
  • API：https://api.example.com

※Cookie認証を利用していない場合は、ドメインを変更する必要はありません。 トークン認証は本問題の影響を受けません。

開発時のヒント​

本事象は Chrome のデフォルト設定では発生しないため、開発時は Chrome が便利です。本番リリース前には Safari（macOS / iOS）でログインフロー、セッション継続、（長期セッションが要件であれば）7日以上アクセスしなかった後の挙動を確認してください。

備考

APIドメインの設定手順の詳細は、KurocoFrontで独自APIドメインを利用する手順をご確認ください。

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする
Slackコミュニティに参加する