Kuroco Auth Design

Kuroco 認証・会員設計

位置づけ

本スキルは設計判断を行う。関連スキルとの境界:

• /kuroco-frontend-integration — ここで決めた認証方式・フローを実装するコード（Cookie/トークンの送受信等）
• /kuroco-security-audit — 既存サイトの設定をチェックリストに照らして読み取り専用で監査する。本スキルの成果物は、この監査を通る設定になっていることが望ましい
• /kuroco-admin-mcp — 対象が異なる。 そちらはAIエージェント自身がKurocoの管理操作を行うためのOAuthスコープ（mcp:admin等）であり、本スキルが扱う「サイトの会員」の認証とは無関係。混同しない
• /kuroco-app-builder — フェーズ0「認証方式の決定」がAPI認証方式（Cookie/DynamicToken/StaticToken/なし）の4択までは決める。会員グループ・登録フロー・アクセス制限スコープ・パスワードポリシーなど、それより踏み込んだ設計が必要なら本スキルを使う

決めること

1. API認証方式
2. 会員グループ設計
3. 登録フロー
4. コンテンツアクセス制限のスコープ
5. パスワードポリシー・2要素認証
6. 代理ログインの要否
7. エンタープライズSSO・SCIM連携

1. API認証方式

認証方式を決めただけでは会員機能は動かない。 認証（誰がログインしているか）と認可（そのグループが何を見て・書けるか）は別の設定で、 両方を設定して初めて通る。トークン発行やログインが成功しているのに 403 になるのはこの片側漏れが原因で、 Cookie認証でも動的アクセストークンでも同じ。決めるべき権限の中身は4. コンテンツアクセス制限のスコープで、 認証方式の決定とセットで決める（後回しにすると実装が権限エラーで止まる）。

判断根拠と実装詳細は /kuroco-api-content・/kuroco-frontend-integration を参照。静的アクセストークンのうちprivileged_static_token（無期限ログイン済み資格情報相当）は特に取り扱いに注意——発行自体にmcp:adminスコープが必要で、漏洩時の影響が通常のトークンより大きい。

2. 会員グループ設計

会員の権限は、モジュール（member / group / topics 等）ごとのgroup_kbn（作成・更新・削除の可否）の組み合わせで決まる。

権限昇格経路に注意: super_flg=0の非管理者グループに、memberとgroupの両方への更新・作成権限を与えると、そのグループのメンバーは自分を管理者グループへ追加したり強い権限の新グループを作ったりでき、実質スーパーユーザーと同等になる（super_flgだけを見ても検出できない）。会員管理を本当に担うグループにのみ、この組み合わせを与える。

初期グループはフロントエンドから指定できない（Member::insertのdefault_group_idはセキュリティ上、フロント発のリクエストでは設定不可）。ドメインなど条件によって登録時の所属グループを変えたい場合、フロントから直接は制御できない——各グループ固定の内部エンドポイントを複数用意し、公開エンドポイント側のカスタム処理（Smarty）が条件で振り分けてapi_internalで内部エンドポイントを呼ぶ、という構成が必要。実装は/kuroco-server-processingを参照。

IPアドレス範囲でのみスーパーユーザー権限を有効にするグループ設定も存在する（社内ネットワークからのみ強い権限を許可したい場合）。詳細は/kuroco-docsの会員認証チュートリアルを参照。

3. 登録フロー

同じMemberモデルに対する操作の組み合わせで、UXの異なる3パターンを作れる。

仮登録は別の操作ではなく、Member::inviteを一般公開しているだけという点を成果物に明記する。「即時登録」と「仮登録」は同じinsert/inviteの使い分けで両方同時に用意することも可能（/kuroco-docsの会員認証チュートリアルに実例あり）。

即時登録を選ぶ場合、login_ok_flgの状態次第で登録直後にログイン可能かが変わる点を確認する。

4. コンテンツアクセス制限のスコープ

認証方式と権限はセットで設定する（片方だけでは通らない）

会員向けAPIが通るには、次の3層がすべてそのグループを許していなければならない。 どれか1つでも欠けると 403 になり、症状は「トークンは取れているのに読めない／書けない」という同じ形で出る。

• 参照と書き込みは別の設定。 一覧・詳細が見えるからといって登録・更新できるとは限らない（逆も同じ）。 会員が投稿するアプリでは secure_level と writer_groups の両方に対象グループを入れる
• どちらも空＝制限なし（secure_level が空配列なら誰でも参照可）。「まだ設定していない」と「全体公開」が同じ状態になるので、 会員限定にする定義では明示的に設定する
• non_public_flg: 1（公開APIに出さない内部向け定義）にする場合は secure_level の設定が必須
• 認証方式によって必要な権限設定は変わらない。Cookie認証から動的アクセストークンへ切り替えても、 コンテンツ定義側の権限はそのまま必要
• フィールド名と設定方法は /kuroco-content-structure、403 の切り分け手順は /kuroco-api-content を参照

「誰に見せる/編集させるか」の3つの仕組み

会員限定コンテンツの絞り方には3つの独立した仕組みがある。

self_onlyは本スキルと/kuroco-content-structureで役割が分かれる: 「個別所有で絞る」という設計判断自体は本スキルが決め、relationフィールドのself_onlyプロパティとしてどう実装するかは/kuroco-content-structureが担当する。

「同じグループのメンバーの投稿だけ見せる」は標準機能ではない。 管理画面表示トリガー等のカスタム処理が必要で、実装は/kuroco-server-processingを参照。会員が複数グループに所属できる設計だと、この種のカスタム制限は意図せず対象外グループの情報まで見せてしまう漏れが起きやすいので、複数グループ所属を許可するかどうかを先に決めておく。

5. パスワードポリシー・2要素認証

いずれも[環境設定]→[サイト管理]→ログインで個別に設定するフラグ。「パスワードポリシーを設定した」を1つの判断で済ませず、以下を1つずつ確認する:

2要素認証は管理画面向けと会員ログイン向けで別物、混同しない:

• 管理画面2FA（スタッフ・管理者向け）: USE_LOGIN_ONETIME_PASSWORD（TOTP）、USE_PASSKEY/USE_PASSKEY_PASSWORDLESS、LOGIN_FORCE_ALL_TFA。「必須」にいきなり切り替えると未登録の既存ユーザーがログインできなくなる——「任意」で全員に登録させてから「必須」にする、という2段階のロールアウトを設計に含める
• 会員ログイン向け2段階認証: LoginエンドポイントにEmail/認証アプリ(TOTP)/SMSの2段階認証パラメータが用意されている。ログイン画面・登録画面双方に組み込み可能。管理画面2FAとは設定面が別なので、要件が「会員に2段階認証させたい」なのか「管理画面担当者に2段階認証させたい」なのかを最初に切り分ける

パスワード再設定はLogin::reminder（仮パスワード・トークンをメール送信）とLogin::reset_password（現在＋新パスワードで更新）の2エンドポイント。公開フォーム・パスワードリマインダーにはreCAPTCHAの設定を推奨（総当たり・自動送信の悪用対策）。

6. 代理ログインの要否

サポート・運営担当者が会員になり代わってログインする機能（代理ログイン）が必要かを確認する。

• 用途: 問い合わせ対応時に会員の画面を運営側から再現・操作したい場合
• 設定: 対象会員の編集画面で権限を付与する必要があるが、利用時（実際に代理ログインする時点）は管理画面へのアクセス権がなくてもフロントエンドのLogin::alias_login系APIから利用できる
• 注意: 権限は信頼できるメンバーにのみ付与し、不要になったら剥奪する。操作はログに残る

7. エンタープライズSSO・SCIM連携

法人向け・社内向けサイトでは、初期リリース時点でSSO/SCIMを実装しなくても、「後で他システムと連結する」ことを前提に設計しておくケースが多い。今すぐ作るかどうかに関わらず、この節は毎回確認する。

何が用意されているか

Kurocoは[外部システム連携]→[ID連携]配下に4種類の仕組みを持つ。SSOログインとSCIMプロビジョニングは別物——混同しない。

同時に有効にできるSCIM SPは1サイトにつき1つだけ。 複数のIdPからのプロビジョニングを両立させたい場合は事前に伝える。

SSOのトークンは、既存の動的アクセストークン認証と同じ仕組みに乗る

SSO認証成功後の流れは、grant_token（1回限り・短命）→ tokenエンドポイントでaccess_token/refresh_tokenに交換 → X-RCMS-API-ACCESS-TOKENヘッダーでAPIを呼ぶ、という動的アクセストークン認証と全く同じtoken/profileエンドポイントを使う。

設計上の含意: 「今回はCookie認証で作るが、将来SSOを足すかもしれない」という場合、動的アクセストークン認証を選んでおく方がSSOの後付けと相性がよい（ドキュメント化されたSSOフローは動的アクセストークンの仕組みの上に成り立っている）。Cookie認証でのSSO対応は一次資料で確認できていない——Cookie認証のまま進めるなら、その旨と後で認証方式ごと切り替えが必要になりうる可能性を成果物に明記する。1.のAPI認証方式の選択に、この理由を持ち込んでよい。

また、動的アクセストークン認証ではログインセッションはAPI（api_id）単位でスコープされる。SSO対応が必要なエンドポイントは、後から分割すると手戻りになるため、最初から同一のapi_idにまとめておく。

「後で連結する」場合に今のうちにやっておくこと

判断が必要なとき

「今は使わないが後で連携する可能性がある」という要件が出たら、上記5点を成果物の「確認事項」または「今後の拡張ポイント」として明記し、今すぐ実装するかどうかをユーザーに確認する。実装する場合の具体的な手順（管理画面操作、フロントのgrant_token交換コード等）は/kuroco-frontend-integrationおよび/kuroco-docsの該当チュートリアルに委譲する——本スキルは「どの方式を選ぶか」「今の設計にどう影響するか」までを扱う。

成果物テンプレート

## 認証・会員設計
- API認証方式: （1.の選択と理由）
- 会員グループ: （階層・初期グループの決め方・昇格経路チェック済みか）
- 登録フロー: 即時登録 / 招待 / 仮登録（選択と理由）
- コンテンツアクセス制限: GroupAuth / MemberCustomSearchAuth / self_only（対象コンテンツごとに明記）
- パスワードポリシー: USE_HASHED_PASSWORD＝有効/無効、その他フラグの設定値
- 2要素認証: 管理画面（対象・ロールアウト計画）／会員ログイン（要否）
- 代理ログイン: 要否、必要なら付与対象
- SSO/SCIM: 今すぐ実装するか／将来のための布石か（動的アクセストークンの選択理由・外部ID拡張項目の有無・対象api_idのまとめ方）

アンチパターン

関連スキル