kuroco-auth-design

Kuroco Authentication and Member Design

Positioning

This skillmakes design decisions. Boundaries with related skills:

• /kuroco-frontend-integration — Code that implements the authentication method and flow decided here (sending/receiving cookies/tokens, etc.)
• /kuroco-security-audit — Check an existing site's configuration against a checklist andaudit it read-only. The deliverables of this skill should be configured to pass this audit
• /kuroco-admin-mcp — The targets differ. That one concerns the OAuth scopes (mcp:admin, etc.) for the AI agent itself to perform Kuroco administrative operations, and is unrelated to the authentication of "site members" handled by this skill. Do not confuse them
• /kuroco-app-builder — Phase 0 "Determining the authentication method" decides up to the four choices of API authentication method (Cookie/DynamicToken/StaticToken/none). If you need deeper design such as member groups, registration flows, access restriction scopes, or password policies, use this skill

What to decide

1. API authentication method
2. Member group design
3. Registration flow
4. Scope of content access restrictions
5. Password policy and two-factor authentication
6. Whether proxy login is required
7. Enterprise SSO and SCIM integration

1. API Authentication Method

Condition	Authentication method
Public content only (no member features)	No authentication + cache
Member features present + front end and API can be placed under the same parent domain	Cookie authentication
Member features present + cross-domain SPA	Dynamic access token authentication (X-RCMS-API-ACCESS-TOKENHeader)
Server-to-server communication and provision of public information only	Static access token. Do not use it for non-public data such as member information

Deciding the authentication method alone does not make member features work. Authentication (who is logged in) and authorization (what that group can see and write) are separate settings, and it only works once both are configured. Even when token issuance or login succeeds, 403 occurs because one side is missing, and this is the same for both cookie authentication and dynamic access tokens. The content of the permissions to decide is4. Scope of content access restrictionsで、 Decide it together with the authentication method(if postponed, implementation will stop due to permission errors).

The rationale and implementation details are in /kuroco-api-content・/kuroco-frontend-integration SeeAmong static access tokens,privileged_static_token(equivalent to non-expiring logged-in credentials) requires particular care in handling—— issuing one itself requires themcp:adminscope, and the impact of a leak is greater than that of a normal token.

2. Member Group Design

A member's permissions are determined by the combination ofmember / group / topics (create/update/delete allowed or not) per module (group_kbn, etc.).

Watch out for privilege escalation paths: super_flg=0If you give a non-administrator group update and create permissions on bothmemberとgroupのboth, members of that group can add themselves to an administrator group or create a new group with strong permissions,effectively equivalent to a superuserbecomes (super_flgcannot be detected by looking at that alone). Give this combination only to groups that truly handle member management.

The initial group cannot be specified from the frontend（Member::insertのdefault_group_idcannot be set in requests originating from the frontend for security reasons). If you want to change the group a user belongs to at registration time based on conditions such as domain, you cannot control it directly from the frontend—— you need a setup in which multiple internal endpoints, one fixed per group, are prepared, and custom processing (Smarty) on the public endpoint side sorts by condition and calls the internal endpoint withapi_internalusing/kuroco-server-processing. For the implementation, see

There is also a group setting that enables superuser privileges only for IP address ranges (when you want to allow strong privileges only from the internal network). For details, see the member authentication tutorial in/kuroco-docs.

3. Registration Flow

By combining operations on the sameMembermodel, you can create three patterns with different UX.

Flow	Operation	Suitable cases
Immediate registration (no confirmation)	Member::insert	You want to lower the barrier to members-only content, and identity verification is not required
Invitation (administrator-led)	Member::invite(executed from the admin screen)	The operator wants to know and manage who is invited (internal-facing sites, etc.)
Provisional registration (self-service + email confirmation)	Member::inviteをPublished as a public endpoint(the user themselves sends the email and completes registration via the confirmation link)	For consumer member registration where you want to verify that the email address actually exists

Clearly state in the deliverables that provisional registration is not a separate operation, but simplyMember::invitebeing made publicly available. "Immediate registration" and "provisional registration" are the sameinsert/inviteand can both be provided at the same time through different uses (/kuroco-docsthere are examples in the member authentication tutorial).

If you choose immediate registration, check that whether login is possible immediately after registration changes depending on the state oflogin_ok_flg.

4. Scope of content access restrictions

Authentication method and permissions are configured as a set (one alone will not pass)

For the member-facing API to pass, the following three layers mustallallow that group. If even one is missing, it becomes 403 , and the symptom appears in the same form: "the token is obtained but it cannot be read/written."

Layer	What to configure	What it determines
API	Authentication method (cookie / dynamic_token etc.)	Who is logged inis established. Even if only this is configured, permissions to handle data are not granted
Endpoint	API request restrictions (GroupAuth / MemberCustomSearchAuth)	That endpointcan be calledGroup
Content definition (Topics Group)	secure_level（referencegroups that can)/ writer_groups（add/update/deletegroups that can)	That groupcan handle that dataか

• Reference and write are separate settings. Just because the list/details are visible does not necessarily mean registration/update is possible (and vice versa). In an app where members post, put the target group in secure_level と writer_groups のbothput the target group in
• Both empty = no restriction（secure_level is an empty array, anyone can reference). "Not yet configured" and "public to everyone" become the same state, so for definitions limited to members, configure explicitly
• non_public_flg: 1(internal-facing definition not exposed in the public API), the secure_level setting is required
• The required permission settings do notchangedepending on the authentication method. Even if you switch from Cookie authentication to a dynamic access token, the permissions on the content definition side are still required
• Field names and configuration methods are /kuroco-content-structure、403 The procedure for isolating /kuroco-api-content see

Three mechanisms for "who to show/edit it to"

There are three independent mechanisms for narrowing down member-only content.

Mechanism	Content	Suitable cases
GroupAuth	Static group membership check. Can be configured at each level: API, endpoint, content definition, category, and individual content, and is prioritized in this order	A fixed restriction such as "show only to members of this group"
MemberCustomSearchAuth	Dynamic restriction based on saved member custom search conditions	When you want to narrow down by conditions more flexible than groups (attribute-based, etc.)
self_only(individual ownership)	Narrow to only records created by the currently logged-in user. As an endpoint parameter, orrelationexists as a property of the type field	"show/edit only one's own posts/data"

self_onlyis divided in role between this skill and/kuroco-content-structureroles are divided by: the design decision itself of "narrowing by individual ownership" is made by this skill, andrelationof the fieldself_onlyhow to implement it as a property is handled by/kuroco-content-structureis in charge of.

"show only posts by members of the same group" is not a standard feature. Custom processing such as admin screen display triggers is required, and for implementation refer to/kuroco-server-processing. If the design allows members to belong to multiple groups, this kind of custom restriction is prone to leaks that unintentionally expose information from out-of-scope groups, so decide in advance whether to allow multiple group membership.

5. Password policy / two-factor authentication

Both are flags set individually in [Environment Settings] -> [Site Administration] -> Login.Do not settle "password policy configured" as a single decision; check the following one by one:

Setting	Content	Default value	Remarks
PASSWORD_MIN_LEN	Minimum character count	8
Strength requirements (3 types, individual flags)	Requirement for a combination of alphanumeric characters and symbols	Disabled	The three are independent flags. Do not be satisfied with setting just one
CHK_PWD_HISTORY / CHK_PWD_LAST_CHANGE	Prohibition of reuse of past passwords / expiration	Disabled
PASSWORD_BLACKLIST	Weak password rejection list	Disabled
ChangePWDAtFirstLogin	Force change at first login	Disabled
USE_PASSWORD_CHANGED_MAIL	Password change notification email	Disabled
REMINDER_EXPIRE	Expiration of password reset link	60 minutes

Two-factor authentication isfor the admin screenとfor member loginand are different things; do not confuse them:

• Admin screen 2FA(for staff/administrators): USE_LOGIN_ONETIME_PASSWORD（TOTP）、USE_PASSKEY/USE_PASSKEY_PASSWORDLESS、LOGIN_FORCE_ALL_TFA。Switching suddenly to "required" will prevent existing unregistered users from logging in— include in the design a two-stage rollout: have everyone register while set to "optional," then switch to "required"
• Two-step authentication for member login: LoginThe endpoint provides two-step authentication parameters for Email/authenticator app (TOTP)/SMS. It can be incorporated into both the login screen and the registration screen. Since the settings are separate from admin screen 2FA, first determine whether the requirement is "want members to use two-factor authentication" or "want admin screen operators to use two-factor authentication"

Password reset isLogin::reminder(send temporary password/token by email) andLogin::reset_password(update with current + new password) two endpoints.Recommended to set up reCAPTCHA for public forms and password reminders(measures against brute-force and automated submission abuse).

6. Necessity of proxy login

Confirm whether support/operations staff need a feature to log in on behalf of a member (proxy login).

• Use case: When you want to reproduce/operate a member's screen from the operations side during inquiry handling
• Settings: It is necessary to grant permissions on the target member's edit screen, butAt the time of use (when actually performing proxy login), even without access rights to the admin screen, the frontend'sLogin::alias_logincan be used from the family API
• Note: Grant permissions only to trusted members, and revoke them when they are no longer needed. Operations are recorded in logs

7. Enterprise SSO/SCIM integration

For corporate/internal sites, even if SSO/SCIM is not implemented at the initial release,design with the premise of "connecting with other systems later"there are many cases. Regardless of whether you build it now, check this section every time.

What is available

Kuroco has 4 types of mechanisms under [External System Integration] -> [ID Integration].SSO login and SCIM provisioning are different things— do not confuse them.

Mechanism	Role	Examples of main counterparties
OAuth SP	Kuroco acts as the client and performs SSO login via OAuth authentication with an external IdP	GitHub、Microsoft
SAML SP	Kuroco acts as the service provider and performs SSO login via SAML authentication with an external IdP	Auth0, Google Workspace, GMO Trust Login
IDaaS SP	Performs SSO login by integrating with a CIAM (consumer identity management) service	Microsoft Entra External ID (formerly Azure AD B2C)
SCIM SP	Not login, but automatic synchronization of member information from an external IdP (creation, update, deactivation)	Microsoft Entra ID

Only one SCIM SP can be enabled at a time per site. If you want to enable provisioning from multiple IdPs simultaneously, tell us in advance.

SSO tokens ride on the same mechanism as existing dynamic access token authentication

After successful SSO authentication, the flow isgrant_token(one-time, short-lived) -> at the token endpointaccess_token/refresh_tokenexchange for -> X-RCMS-API-ACCESS-TOKENcall the API with the header, which isexactly the same as dynamic access token authenticationtoken/profileendpointuse.

Design implications: If you are thinking "we will build with Cookie authentication this time, but may add SSO in the future,"choosing dynamic access token authentication is more compatible with adding SSO later(The documented SSO flow is built on top of the dynamic access token mechanism.) SSO support with Cookie authentication has not been confirmed in primary sources—if you proceed with Cookie authentication, state that fact and the possibility that the authentication method may need to be switched entirely later in the deliverable. This reason may be brought into the selection of the API authentication method in 1.

Also, with dynamic access token authentication,the login session is scoped per API (api_id). Endpoints that require SSO support will cause rework if split later, so from the start keep them together in the sameapi_id.

What to do now in case you "link them later"

What to do	Reason
Set the authentication method to dynamic access token (above)	With Cookie authentication, there is a possibility that the authentication method itself will need to be reviewed when adding SSO
Keep the SSO target endpoints together in oneapi_idkeep summarized	Dynamic access token sessions are per API. Splitting later causes rework
If you are looking ahead to SCIM, prepare one member extension field (text type) for storing external IDs in advance	SCIM member linking follows the priority order of "① member ID → ② extension field for storing external ID → ③ email address → ④ create new". Without the item in ②, initial provisioning will have to rely on email address matching. The upper limit on the number of member extension fields iswhoamiのsite.limits.member_max_extension（maxis 999) to confirm
Share in advance the operational rule that attributes synced via SCIM/SAML (name, email address, etc.) are not to be edited directly from the admin screen after introduction	Because they will be overwritten by the IdP-side values on the next sync
Make it clear that the group permission design remains Kuroco's responsibility	SCIM syncs up to group creation and member assignment, butgroup permission settings must be done individually on the Kuroco side(continues from the member group design in 2.)

When a decision is needed

If a requirement comes up that "we won't use it now but may link it later", state the above 5 points in the deliverable as "Confirmation items" or "Future extension points", andwhether to implement it nowconfirm with the user. The specific procedures for implementation (admin screen operations, frontend grant_token exchange code, etc.) are delegated to the relevant tutorials in/kuroco-frontend-integrationand/kuroco-docs—this skill covers up to "which method to choose" and "how it affects the current design".

Deliverable template

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

Anti-pattern

Things you must not do	Reason
Without noticing the group for editing,member＋groupgive write permissions to both	becomes a privilege escalation path (see 2.).super_flgcannot be detected by checking only
want to separate initial groups by domain, but from the front enddefault_group_idassume that it can be passed	For security reasons, it cannot be specified from the front end. An internal endpoint + distribution process is required
Suddenly making admin panel 2FA "mandatory"	Existing unregistered users become unable to log in. Proceed in the order optional → registration period → mandatory
Assuming admin panel 2FA and member login two-factor authentication are the same setting	The settings are completely separate. Configure after clarifying which of the two the requirement applies to
Not adding reCAPTCHA to public forms and password reminders	Likely to become a target for brute-force and automated submissions
Even if told "we might add SSO in the future," proceed with the design using Cookie authentication as is	The documented SSO flow relies on the dynamic access token authentication mechanism. This may lead to having to review the entire authentication method later
Proceed without preparing member extension fields for storing external IDs, without keeping SCIM integration in mind	Initial provisioning ends up relying only on email address matching
Assuming SSO login and SCIM provisioning are the same thing	Separate functions. SCIM is automatic synchronization of member information, not a login method

Related skills

Skill	Role
/kuroco-frontend-integration	Implementation code for the authentication method and flow decided here
/kuroco-api-content	Authentication method configuration details, priority order of viewing/editing restrictions
/kuroco-content-structure	self_onlyField design when making scope individually owned, etc.
/kuroco-server-processing	Custom processes such as per-domain group distribution and same-group-only display
/kuroco-security-audit	Audit whether the settings decided in this skill actually pass the checklist (read-only)
/kuroco-admin-mcp	(Out of scope) The AI agent's own Admin MCP OAuth scope. Separate from member authentication
/kuroco-app-builder	Use when digging deeper into the authentication method decision in Phase 0