How to Configure CORS and Security Headers for the ContiNew Admin API

ContiNew Admin uses a starter-based configuration model where CORS settings are controlled via YAML properties under continew-starter.web.cors, while security headers are managed by Spring Security auto-configuration that you can override by defining a custom SecurityFilterChain bean.

The ContiNew Admin API (continew-org/continew-admin) implements cross-origin resource sharing and HTTP security headers through its modular starter architecture. This design centralizes web security settings in YAML configuration files while allowing programmatic customization through Spring Security filters. Understanding how to configure CORS and security headers for the API ensures your endpoints remain accessible to legitimate front-end clients while maintaining protection against common web vulnerabilities.

CORS Configuration via YAML

All CORS policies in ContiNew Admin are driven by the continew-starter.web.cors property block in your environment-specific YAML files. The primary configuration files are located at continew-server/src/main/resources/config/application-dev.yml (development) and application-prod.yml (production), with CORS settings typically starting at line 96 in the development configuration.

Basic CORS Setup

Enable and configure CORS by modifying the continew-starter.web.cors section:

# continew-server/src/main/resources/config/application-dev.yml

continew-starter:
  web:
    cors:
      enabled: true
      allowed-origins:
        - ${application.url}      # References your front-end URL

      allowed-methods: '*'
      allowed-headers: '*'
      exposed-headers: '*'

Setting allowed-origins to * grants wildcard access, while specifying ${application.url} restricts requests to your configured front-end domain.

Restrictive CORS Policies

For production environments, replace wildcards with explicit allowlists to minimize attack surface:

continew-starter:
  web:
    cors:
      enabled: true
      allowed-origins:
        - https://admin.continew.top
        - https://app.continew.top
      allowed-methods:
        - GET
        - POST
        - PUT
      allowed-headers:
        - Authorization
        - Content-Type
      exposed-headers:
        - X-Trace-Id

The starter automatically registers these values as a CorsConfigurationSource bean that Spring MVC applies to all incoming requests.

Security Headers and Spring Security Integration

ContiNew Admin leverages Spring Security’s default SecurityFilterChain (auto-configured by the continew-starter.auth.satoken module) to inject standard security headers automatically. This includes X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, and Content-Security-Policy headers without requiring explicit YAML configuration.

The starter’s auto-configuration creates a filter chain that applies these headers globally. You can verify this behavior by inspecting the response headers on any authenticated endpoint.

Customizing Security Headers Programmatically

When you need to modify default headers or add custom ones, declare a SecurityFilterChain bean in your configuration class. This overrides the starter’s default chain while preserving CORS configuration.

Create a configuration class at continew-server/src/main/java/top/continew/admin/config/security/SecurityHeaderConfig.java:

package top.continew.admin.config.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityHeaderConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .cors(Customizer.withDefaults())
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .headers(headers -> headers
                .contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'self'"))
                .frameOptions(frame -> frame.sameOrigin())
                .addHeaderWriter((request, response) -> 
                    response.addHeader("X-Custom-Header", "continew-admin"))
            )
            .csrf(csrf -> csrf.disable());
        return http.build();
    }
}

This configuration maintains the starter’s CORS setup via Customizer.withDefaults() while adding a strict Content Security Policy and custom headers.

Excluding Endpoints from Authentication

The SaTokenConfiguration class at continew-server/src/main/java/top/continew/admin/config/satoken/SaTokenConfiguration.java (line 82) reads exclusion patterns from your YAML to bypass authentication for specific paths. This is distinct from CORS configuration but critical for public endpoints like health checks or documentation.

Add exclusion patterns in your YAML:

continew-starter:
  auth:
    satoken:
      security:
        excludes:
          - /actuator/**          # Health and metrics endpoints

          - /public/**            # Public API routes

          - /swagger-ui/**        # API documentation

The SaTokenConfiguration merges these patterns with any routes annotated with @SaIgnore in your controller classes.

Configuring the Trace ID Header

ContiNew Admin uses a trace ID header for distributed logging, configured under continew-starter.trace in your YAML (default location around line 88 in application-dev.yml). By default, the header name is X-Trace-Id.

To customize the header name:

continew-starter:
  trace:
    enabled: true
    trace-id-name: X-Correlation-Id

All logging components will automatically read and propagate this custom header name in request/response cycles.

Summary

• CORS configuration resides in application-dev.yml or application-prod.yml under the continew-starter.web.cors property block, supporting both wildcard and explicit origin lists.
• Security headers are automatically injected by Spring Security via the starter’s SecurityFilterChain, requiring no YAML configuration for standard protection.
• Custom headers require defining a SecurityFilterChain bean to override defaults while calling cors(Customizer.withDefaults()) to maintain starter CORS settings.
• Authentication exclusions are configured via continew-starter.auth.satoken.security.excludes and processed by SaTokenConfiguration at line 82.
• Trace ID headers can be renamed using the continew-starter.trace.trace-id-name property.

Frequently Asked Questions

Where does ContiNew Admin store CORS configuration?

CORS settings are stored in continew-server/src/main/resources/config/application-dev.yml (or application-prod.yml) under the continew-starter.web.cors property block. The starter reads these values to create a CorsConfigurationSource bean that Spring MVC applies globally.

How do I add a custom Content-Security-Policy header?

Create a SecurityFilterChain bean in a configuration class and use the headers.contentSecurityPolicy() DSL method. Since declaring this bean overrides the starter’s default chain, explicitly call cors(Customizer.withDefaults()) to preserve your YAML-based CORS settings.

Can I disable X-Frame-Options for specific endpoints?

Yes. In your custom SecurityFilterChain bean, use headers.frameOptions(frame -> frame.disable()) to remove the header globally, or implement a custom HeaderWriter to conditionally apply headers based on request patterns. Note that disabling this header increases clickjacking risks.

How do I whitelist endpoints that bypass authentication entirely?

Add Ant-style patterns to continew-starter.auth.satoken.security.excludes in your YAML configuration. The SaTokenConfiguration class (line 82) reads these patterns and configures the SaInterceptor to skip authentication checks for matching routes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}