Cookie認証・動的アクセストークン認証の自動ログイン

概要

自動ログインは、通常のログイン状態が失効した後も、ユーザーにメールアドレスやパスワードを再入力させずにログイン状態を復元する仕組みです。

Kuroco APIでは、APIセキュリティによって自動ログインの実装方法が異なります。

項目	動的アクセストークン	Cookie
保存するもの	Login::tokenのレスポンスで取得したアクセストークンとリフレッシュトークンをアプリケーションで保持します。	ログインセッション用Cookieと自動ログイン用Cookieをブラウザが保持します。
認証リクエスト	アクセストークンをX-RCMS-API-ACCESS-TOKENリクエストヘッダーに指定します。	credentials: "include"を指定し、ブラウザからCookieを送信します。
通常のログイン状態	アクセストークンはaccess_token_lifespanで設定した期間まで使用できます。	ログインセッション用Cookieが現在のログインセッションで使用されます。
自動ログイン	フロントエンドからLogin::tokenへリフレッシュトークンを送信し、新しいアクセストークンを取得します。	ブラウザが自動ログイン用Cookieを送信すると、Kurocoがログイン状態を復元します。
自動ログインの有効期間	refresh_token_lifespanを秒単位で設定します。	[環境設定] -> [管理画面]の[オートログイン有効期間]を日単位で設定します。
有効期間の更新	アクセストークンを再発行しても、リフレッシュトークンの有効期間は更新されません。	ログイン状態が復元されても、オートログイン有効期間は更新されません。
ブラウザの制限	Cookieを自動ログインに使用しません。	Cookieの削除、サードパーティCookieの制限、Safariの制限の影響を受けます。

動的アクセストークン認証の場合

動的アクセストークン認証では、アクセストークンとリフレッシュトークンをフロントエンドで保持します。アクセストークンが失効したときは、有効なリフレッシュトークンを使用して新しいアクセストークンを取得します。

エンドポイントを設定する

APIのセキュリティに[動的アクセストークン]を設定します。

ログイン用のエンドポイントとトークン発行用のエンドポイントを作成します。

ログイン用エンドポイント

項目	設定内容
パス	login
カテゴリー	認証
モデル	Login(v1)
オペレーション	login_challenge

トークン発行用エンドポイント

項目	設定内容
パス	token
カテゴリー	認証
モデル	Login(v1)
オペレーション	token
use_refresh_token	チェックあり
access_token_lifespan	アクセストークンが有効である秒数
refresh_token_lifespan	リフレッシュトークンが有効である秒数

アクセストークンとリフレッシュトークンを取得する

Login::login_challengeへログイン情報を送信します。

動的アクセストークン認証では、login_saveは0のままでリフレッシュトークンを取得できます。Login::tokenのuse_refresh_tokenを有効にすると、grant_tokenとの交換時にリフレッシュトークンが発行されます。login_save: 1が必要なのは、Cookie認証の自動ログイン用Cookieを発行する場合です。

リクエスト例

{
  "email": "member@example.com",
  "password": "PASSWORD",
  "login_save": 0
}

grant_tokenを含むレスポンスが返ります。

レスポンス例

{
  "grant_token": "GRANT_TOKEN",
  "status": 0,
  "member_id": 123,
  "info": {
    "validUntil": 1700000000
  },
  "messages": [],
  "errors": []
}

レスポンスのgrant_tokenをLogin::tokenへ送信します。

リクエスト例

{
  "grant_token": "GRANT_TOKEN"
}

use_refresh_tokenを有効にしたLogin::tokenでは、アクセストークンとリフレッシュトークンが返ります。

レスポンス例

{
  "access_token": {
    "value": "ACCESS_TOKEN",
    "expiresAt": 1700000000
  },
  "refresh_token": {
    "value": "REFRESH_TOKEN",
    "expiresAt": 1700604800
  }
}

認証が必要なAPIへアクセスするときは、アクセストークンをX-RCMS-API-ACCESS-TOKENリクエストヘッダーに指定します。

動的アクセストークン認証の自動ログインは、Login::tokenのレスポンスで取得したリフレッシュトークンを使用します。

リフレッシュトークンでアクセストークンを再発行する

アクセストークンが失効したときは、リフレッシュトークンをLogin::tokenへ送信します。

リクエスト例

{
  "grant_token": "",
  "refresh_token": "REFRESH_TOKEN"
}

新しいアクセストークンが返ります。

レスポンス例

{
  "access_token": {
    "value": "NEW_ACCESS_TOKEN",
    "expiresAt": 1700100000
  }
}

リフレッシュトークンを使用した再発行では、新しいリフレッシュトークンは返りません。最初に発行されたリフレッシュトークンを、そのexpiresAtまで使用します。リフレッシュトークンが失効した場合は、Login::login_challengeからログインをやり直す必要があります。

注意

動的アクセストークン認証では、Kurocoがブラウザのログイン状態を自動で復元するのではありません。フロントエンドでトークンを保持し、アクセストークンの失効時に再発行する処理が必要です。

アクセストークンとリフレッシュトークンは認証情報です。保存方法を設計し、ログや公開ファイルへ出力しないでください。

Cookie認証の場合

Cookie認証では、Login::login_challengeのlogin_saveに1を指定すると、自動ログインが有効になります。エンドポイントの後処理や[ログイン後処理]の追加は不要です。

APIと有効期間を設定する

APIのセキュリティに[Cookie]を設定します。

ログイン用エンドポイントを作成します。

項目	設定内容
パス	login
カテゴリー	認証
モデル	Login(v1)
オペレーション	login_challenge

次に、[環境設定] -> [管理画面]をクリックし、[オートログイン有効期間]へ日数を入力して[更新する]をクリックします。この設定は、管理画面とAPIのオートログイン有効期間に適用されます。

ブラウザからAPIへアクセスする場合は、CORSを次のように設定して[保存する]をクリックします。

• CORS_ALLOW_ORIGINSにフロントエンドのOriginを追加します。
• CORS_ALLOW_METHODSにGET、POST、OPTIONSを追加します。
• CORS_ALLOW_CREDENTIALSの[Allow Credentials]を有効にします。

資格情報を含むCORSリクエストでは、CORS_ALLOW_ORIGINSに*を使用せず、フロントエンドのOriginを指定します。また、サードパーティCookieの制限を避けるため、www.example.comとapi.example.comのようにフロントエンドとKurocoのドメインを合わせます。

login_saveを指定してログインする

login_saveは0または1で指定します。

値	動作
0	通常のログインセッションを開始します。セッション失効後は再ログインが必要です。
1	通常のログインセッションに加えて、自動ログイントークンを発行します。

ブラウザからのリクエスト例

const response = await fetch(
  "https://api.example.com/rcms-api/1/login",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    credentials: "include",
    body: JSON.stringify({
      email: "member@example.com",
      password: "PASSWORD",
      login_save: 1,
    }),
  }
);

ログイン後にCookie認証が必要なAPIへアクセスする場合も、credentials: "include"を指定します。

ログインユーザーを取得する例

const profile = await fetch(
  "https://api.example.com/rcms-api/1/profile",
  {
    credentials: "include",
  }
);

login_save: 1でログインすると、通常のログインセッション用Cookieに加えて、自動ログイン用Cookieが保存されます。

Cookie	用途
rcms_api_access_token	現在のログインセッションで使用します。
rcms_api_refresh_token	通常のログインセッションが失効したときに、ログイン状態を復元するために使用します。

環境によって、Cookie名に__Host-が付く場合があります。フロントエンドではCookieの値を直接扱わず、credentials: "include"を指定してブラウザに送信を委ねます。

発行された自動ログイントークンは、[メンバー管理] -> [メンバー] -> [自動ログイントークン管理]で確認できます。一覧で対象のトークンを選択して[削除する]をクリックすると、そのトークンを無効化できます。削除したトークンではログイン状態を復元できません。

Cookie認証の自動ログインを確認する

次の内容を確認します。

1. ブラウザの開発者ツールでログインリクエストを開き、レスポンスのSet-Cookieを確認します。
2. ブラウザのApplicationまたはStorageで、ログインセッション用Cookieと自動ログイン用Cookieを確認します。
3. [自動ログイントークン管理]で、対象メンバーの自動ログイントークンを確認します。
4. 通常のログインセッションが失効した後、credentials: "include"を指定した認証必須APIへアクセスし、ログイン状態が復元されることを確認します。

有効期間と注意事項

• Cookie認証の自動ログイン有効期間は、login_save: 1でログインした日時から計算されます。自動ログインによってログイン状態が復元されても、有効期間は延長されません。
• 動的アクセストークン認証のリフレッシュトークンは、最初に発行されたときのexpiresAtまで有効です。アクセストークンを再発行しても、新しいリフレッシュトークンは発行されません。
• Cookie認証では、ブラウザによるCookie削除やサードパーティCookieの制限によって、Kurocoで設定した期間よりも早くログイン状態を失う場合があります。
• Safariで7日を超える長期セッションが必要な場合は、Cookie認証ではなく動的アクセストークン認証を利用します。

関連ドキュメント

• APIセキュリティ
• ログイン画面を構築する
• エンドポイント 基本設定/詳細設定一覧
• オートログインの有効期間について教えてください
• 自動ログイントークン管理
• iPhoneやSafariでAPIと連携できないです。