spring-security-configuration

Imported from Juliodvp29/odentix-backend (.agents/skills/spring-security-configuration/SKILL.md). Install upstream with npx skills add Juliodvp29/odentix-backend --skill spring-security-configuration. Copyright stays with the author.

Preflight: Spring MCP

This skill is part of the Spring Agent Toolkit and is designed to work with the Spring MCP server (provided by the Amplicode IntelliJ plugin). Before doing anything else, check your tool list for any Spring MCP tool — they are exposed under the amplicode MCP server (e.g. get_project_summary, list_module_dependencies, get_entity_details); harnesses that flatten MCP tools into the tool list use the mcp__amplicode__ prefix on the same names.

• If at least one Amplicode tool is available — MCP is connected. Proceed with the skill below.
• If none are available — stop and invoke the amplicode-install skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the MCP tools become available — resume this skill.
• If amplicode-install is not registered in your skill list, tell the user (in their language): "This skill needs the Amplicode IntelliJ plugin and its MCP server. Install it from https://amplicode.ru/marketplace into IntelliJ IDEA Ultimate/Community or GigaIDE, open any project, click «Настроить Spring Agent» on the Amplicode welcome screen, then restart your MCP client."

Spring Security Configuration

Generates a @Configuration @EnableWebSecurity class with a filterChain() method, DSL chains for authentication and authorization, beans, dependencies, and properties in application.properties.

CRITICAL: Code ONLY from examples/ files. If no matching example -- STOP and ask user. CRITICAL: For questions with a fixed set of choices, prefer AskUserQuestion > its analogue > plain text list. Plain numbered text lists are the last resort when no interactive tool is available. CRITICAL: Read the conversation context BEFORE running Step 1. Half the questions in Steps 2–3 may already be answered by the user's prompt and prior turns. Re-asking what was already said is the #1 reason this skill feels slow.

Defaults

Smart defaults: If user says "use defaults", "all defaults", "default settings", or similar -- skip ALL questions where "Always ask?" = NO. Only ask mandatory questions.

Smart answer recognition: When user provides a value instead of choosing from a numbered list, accept it directly. Examples:

• Question "Authentication type?" -> user answers "jwt" -> this IS the choice, don't show options
• Question "Client ID?" -> user answers "my-app" -> this IS the value, don't re-ask
• If user provides multiple answers in one message -> accept all, skip answered questions
• NEVER ask a question that the user already answered (even implicitly)

Batch questions: Group closely related questions into a single AskUserQuestion call (up to 4 questions per call) when they:

• Belong to the same logical section (e.g. both are connection settings)
• Don't depend on each other's answers
• Have obvious defaults that the user can skip

Rules:

• Maximum 3-4 questions per AskUserQuestion call
• Mark the recommended option with (Recommended) and place it first
• Never batch questions from DIFFERENT decision branches
• The primary branching question (authentication type) is always asked ALONE
• Prefer AskUserQuestion for choices; fall back to plain text lists only if the tool is unavailable

Decision-making principle — context first, then ask

Before asking the user any question, attempt to derive the answer from the context already gathered: project summary, module dependencies, existing security configurations, prior turns of this conversation, and the user's original prompt. Only ask when the context yields no clear default or when the choice is genuinely user-specific (e.g. authentication type, authorization rules).

Hierarchy of decisions:

1. Context is unambiguous → decide silently, do NOT ask. Examples: language and Boot version from get_project_summary; existing dependencies from list_module_dependencies; packageName from existing @Configuration classes; className = SecurityConfiguration; appPrefix from existing @Value annotations.

2. Context gives a strong signal → state the decision + alternatives in one line, let the user override or stay silent. Format:

   Will create SecurityConfiguration with JWT (spring-boot-starter-oauth2-resource-server found in dependencies).
   Alternatives: Form Login, OIDC, LDAP, Custom. OK?
   

   The user can answer "ok" / "yes" / silence → accept; or name an alternative → switch.

3. Context yields no clear default → ask with AskUserQuestion (preferred), with the recommended option first. Mark the recommended option with (Recommended) in its label and place it first. If no interactive choice tool is available, fall back to a plain text list.

4. Context is fully empty for a critical input → ask plainly. This applies to: authentication type (when no deps hint at it), authorization rules, variant-specific settings.

How to ask — prefer AskUserQuestion

When a question must be asked, prefer the AskUserQuestion tool over writing a numbered list in the response body. Fall back to plain text only if no interactive choice tool is available.

Rules for AskUserQuestion calls in this skill:

• Each call may contain up to 4 questions that are independent of each other. Use this to batch related decisions in one round-trip.
• Each question has 2–4 options. The tool auto-adds an "Other" choice for free-form input — never include it manually.
• Mark the recommended option by putting it first with (Recommended) appended to the label.
• header is a 12-char chip label (e.g. "Auth Type", "CSRF", "Headers").

When AskUserQuestion is not the right tool:

• Free-form input with no enumerable set of options (e.g. URL, client ID, DN, patterns) — ask in plain text.
• The "single confirmation line" from principle 2 — that is a plain yes/no, not an enumerated choice.

NEVER ask the user for credentials of any kind (client secret, manager password, API key, token, etc.) — not via AskUserQuestion, not in plain text, not in any form. Secret values must not enter the conversation. For every credential field, the skill emits an env-var placeholder (${OAUTH_*_CLIENT_SECRET}, ${LDAP_MANAGER_PASSWORD}, ${AUTHSERVER_*_CLIENT_SECRET}) into application.properties and reports the placeholder name to the user after generation — see the per-variant references and _properties/*/properties.md "secret handling" sections.

The question lists in Steps 2–3 and in reference files are a fallback for case 4. They are NOT a script to execute top-to-bottom. If a question's answer is already determined by principles 1–3, skip the question.

Step 0 -- Conversation context first (REQUIRED, no tool calls)

Before any MCP call, before any question, re-read the user's prompt and the prior turns of this conversation and extract whatever is already stated. This step costs nothing and prevents the most common failure mode of this skill — asking the user something they already said.

Build a mental checklist of inputs and tick off everything the user has already provided, explicitly or implicitly:

For every input that is explicitly or strongly implicitly answered: mark it as decided and skip the corresponding question in Steps 2–3. Do NOT ask "Authentication type?" if the user wrote "configure JWT" — JWT is the answer. Do NOT ask language if the user wrote "in Kotlin".

For every input that is not answered: defer to the Decision-making principle above — try to derive it from project context first (Step 1), and only then ask.

Step 0 is mental, not a tool call. Do not announce it to the user. Do not write "Step 0 done". Just internalize what the user already said before proceeding to Step 1.

Step 1 -- Gather context (automatic, no questions)

Call Spring MCP tools (in parallel where possible).

If multi-module project (multiple modules in get_project_summary): Ask which module to use. Then re-call module-specific MCP tools with that module.

If existingConfigs is not empty:

• Warn user: "Project already has security configuration(s): {list}. Create an additional one?"
• If user confirms — suggest a {className} that does not collide with existing names
• If user declines — STOP

Determine appPrefix: scan existing @Value annotations in the project for a common custom prefix (e.g. @Value("${myapp.something}") → appPrefix = myapp). If none found, default to app.

Step 2 -- Authentication type

Ask:

Authentication type?
1. Form Login (HTTP Session) -- form login with session
2. JWT (OAuth2 Resource Server) -- stateless JWT
3. OAuth2/OIDC Login -- login via external provider (Keycloak, Google, GitHub...)
4. Authorization Server -- own authorization server (Spring Boot >= 3.1)
5. LDAP -- LDAP authentication
6. Custom -- empty filterChain, only common DSL blocks

Map answer to reference file:

• 1 -> references/http-session.md
• 2 -> references/jwt.md
• 3 -> references/oidc.md
• 4 -> references/authorization-server.md (requires bootMajor >= 3.1 — if lower, warn user and ask to choose another type)
• 5 -> references/ldap.md
• 6 -> references/custom.md

Step 3 -- Variant-specific questions (inline)

Read the mapped reference file and follow its questions flow. Only asked if user did NOT say "all defaults".

Each reference file specifies:

• Which fragments to include
• Which beans to generate
• Which dependencies to add
• Which properties to write
• Variant-specific questions

Step 4 -- Generate code

1. Read skeleton from examples/_skeletons/{lang}.md where {lang} = java or kotlin (from Step 1)

2. Create the configuration class file using the skeleton, substituting {packageName} and {className}

3. Read the reference file for the chosen variant. For each fragment listed:

   • Read the fragment file from examples/_fragments/{feature}/{lang}.md
   • Insert the appropriate code variant into the filterChain method body, before return http.build();
   • Select the correct version variant based on bootMajor from Step 1 (some fragments have Boot < 3.1 / Boot >= 3.1 sections — use the matching one)
   • Apply variable substitutions (ONLY variables declared in the Variables section)
   • Include ONLY the lines that match the user's chosen options (skip commented-out conditional lines)

4. DSL ordering inside filterChain method (IMPORTANT — order is VARIANT-DEPENDENT):

   See references/common-dsl.md → "Generation Order" for the exact ordering per variant. Always end with return http.build();

5. For each bean listed in the reference:

   • Read the bean file from examples/_beans/{bean-type}/{lang}.md
   • Add the bean method to the configuration class body
   • CRITICAL: Every bean method MUST be referenced from the filterChain DSL. Do NOT create methods that are unused.
   • If the bean requires autowired fields (e.g. clientRegistrationRepository), add them to the class

6. Variable substitution rules:

   • {packageName} -> from Step 1 context
   • {className} -> from user or default
   • Other variables -> from user answers or defaults
   • NEVER substitute anything not listed in Variables
   • NEVER add imports, methods, or code not in the example
   • FQN only in imports, clean code in body. Examples may contain fully qualified names inline (e.g. new org.springframework.security.web.SecurityFilterChain(...)). When generating code, extract FQNs into import statements and use short class names in the code body. The generated file must look like normal hand-written code.

Step 5 -- Dependencies & properties (automatic)

1. Read _dependencies/base.md (always)
2. Read variant-specific dependency file (from the reference file)
3. Select the correct version variant based on bootMajor from Step 1:
   • Dependency files contain Boot 3.x / Boot 4.x sections — use the one matching bootMajor
   • Boot 4.x changed OAuth2 artifact names: spring-boot-starter-oauth2-* → spring-boot-starter-security-oauth2-*
   • Authorization Server on Boot 3.0: requires manual spring-security-oauth2-authorization-server:1.1.0 (no starter)
4. For each artifact NOT in presentDeps:
   • Use buildFile from Step 1
   • Edit the build file to add the dependency
5. Call refresh_build_system_model
6. Read the variant-specific properties file from _properties/{variant}/properties.md
7. Write/append to the application properties file
8. Report: "Added dependencies: [list]. Wrote to application.properties: [keys]"
9. If the generated properties contain any ${...} env-var placeholders for credentials (OAUTH_*_CLIENT_SECRET, LDAP_MANAGER_PASSWORD, AUTHSERVER_*_CLIENT_SECRET), list every placeholder explicitly and instruct the user to set these env vars before running the app (shell export, IDE run configuration, or deployment secret store). Never ask the user for the secret value itself — secrets must not enter the conversation history.

Anti-hallucination checklist

Before writing ANY code, verify:

• The code comes from an examples/ file (cite which one)
• Only declared variables were substituted
• No framework API calls were added "from knowledge"
• Imports are derived from FQNs used in the example (no extra, no missing)
• Method signatures match the example exactly
• No comments or convenience methods were added
• FQNs from examples are extracted into imports; code body uses short class names only
• DSL ordering inside filterChain follows the VARIANT-SPECIFIC order defined in Step 4 (HTTP Session/JWT: authorizeHttpRequests first; OIDC: oauth2Login first, then logout, then authorizeHttpRequests)
• Helper methods (jwtAuthenticationConverter, oidcClientInitiatedLogoutSuccessHandler) are NOT @Bean — they are public methods called directly from filterChain. Note: userAuthoritiesMapper is @Bean for generic providers, but NOT @Bean for Keycloak (see role-mapper bean file)
• Every bean method generated is actually referenced from the filterChain DSL or from another bean — no orphan methods
• For HTTP Session: if User Storage is configured, http.userDetailsService(...) call is present in filterChain
• For HTTP Session: logout DSL is only generated when non-default logout options are set (Spring Security enables default logout automatically)
• Version-specific code/dependencies match bootMajor: Boot 4.x uses spring-boot-starter-security-oauth2-* (not spring-boot-starter-oauth2-*); session-management concurrent sessions API changed in Boot 3.1