Policy Management

PolicyService

The primary service for policy CRUD, search, approval, validation, simulation, impact analysis, and version rollback. The Policy Center controller uses this service as the main orchestration entry point.

public interface PolicyService {
    List<Policy> getAllPolicies();
    Page<Policy> searchPolicies(String keyword, Pageable pageable);
    Page<Policy> searchPolicies(String keyword,
                                Policy.ApprovalStatus approvalStatus,
                                Boolean activeFilter,
                                Pageable pageable);
    Policy findById(Long id);
    Policy createPolicy(PolicyDto policyDto);
    void updatePolicy(PolicyDto policyDto);
    void deletePolicy(Long id);
    void deletePolicy(Long id, String changeReason);
    void synchronizePolicyForPermission(Permission permission);
    void approvePolicy(Long id, String approver);
    void rejectPolicy(Long id, String rejector);
    List<PolicyConflictDto> detectConflicts(PolicyDto policyDto);
    PolicyValidationReport validateBeforeCreate(PolicyDto policyDto);
    List<PolicyVersion> getVersions(Long policyId);
    Policy rollbackPolicy(Long policyId, int versionNumber, String reason);
    PolicyImpactReport analyzeImpact(PolicyDto policyDto);
    SimulationReport simulate(PolicyDto candidatePolicy,
                              List<SimulationTestCase> testCases);
    AIPolicyValidationReport validateAIPolicy(Long policyId);
}

PolicyDto Structure

The PolicyDto is the transport shape used by Policy Center, classic controllers, version snapshots, and AI validation output.

PolicySynchronizationService

Automatically generates and updates policies when role-permission assignments change. Listens for RolePermissionsChangedEvent via Spring's @EventListener and executes asynchronously with @Async.

public class PolicySynchronizationService {

    @Async
    @EventListener
    @Transactional
    public void handleRolePermissionsChange(
            RolePermissionsChangedEvent event) { ... }
}

Synchronization Flow

Auto-generated policies use the naming convention AUTO_POLICY_FOR_{roleName} with a priority of 500. The condition expression combines the role authority check with individual permission authority checks joined by or.

PolicyBuilderService

The builder service still exists in the server layer for template lookup, visual-model conversion, and conflict analysis. In the current OSS UI, operators primarily use the integrated Policy Center create tab rather than a separate standalone builder template.

public interface PolicyBuilderService {
    List<PolicyTemplateDto> getAvailableTemplates(PolicyContext context);
    Policy buildPolicyFromVisualComponents(VisualPolicyDto visualPolicyDto);
    List<PolicyConflictDto> detectConflicts(Policy newPolicy);
}

PolicyBuilderController and /admin/policy-builder still exist in server code, including /from-resource. However, the current OSS template bundle routes day-to-day authoring through /admin/policy-center.

PolicyEnrichmentService

Enriches policy entities with human-readable descriptions by delegating to PolicyTranslator. This service translates SpEL expressions in policy conditions into natural language descriptions.

public class PolicyEnrichmentService {

    private final PolicyTranslator policyTranslator;

    public void enrichPolicyWithFriendlyDescription(Policy policy) {
        // Translates policy rules/conditions to human-readable text
        // Sets policy.friendlyDescription
    }
}

Example: A policy with condition hasAuthority('ROLE_ADMIN') and isAuthenticated() would be enriched to "(User has authority ROLE_ADMIN and User is authenticated)".

BusinessPolicyService

Provides bidirectional translation between business-level access rules and technical policy definitions, enabling non-technical administrators to manage authorization.

public interface BusinessPolicyService {
    // Create a technical policy from a business rule definition
    Policy createPolicyFromBusinessRule(BusinessPolicyDto dto);

    // Update an existing policy from business rule changes
    Policy updatePolicyFromBusinessRule(Long policyId, BusinessPolicyDto dto);

    // Get the business rule representation for a technical policy
    BusinessPolicyDto getBusinessRuleForPolicy(Long policyId);

    // Translate an existing technical policy to business rule format
    BusinessPolicyDto translatePolicyToBusinessRule(Long policyId);
}

Policy Entity Model

Policy Authoring Flow

The current OSS policy authoring experience is centered on Policy Center, with related admin policy routes and detail editing supporting the same lifecycle.

Five-Step Workflow

1. Name & Description —Set the policy name, description, and effect (ALLOW/DENY)
2. Targets —Define URL patterns or method identifiers this policy applies to
3. Rules —Configure ALLOW/DENY rules with priority ordering
4. Conditions —Write SpEL expressions for each rule
5. Condition Picker —Select from compatible condition templates

From-Resource Mode

When policy creation starts from a selected resource in the Policy Center integrated resources area, or from the legacy /admin/policy-builder/from-resource route, the builder enters from-resource mode:

• Resource target information is pre-filled
• Only compatible condition templates are shown (filtered by ConditionCompatibilityService)
• Domain-specific variables and ABAC applicability are considered

Condition Template System

Condition templates are reusable SpEL expression patterns that simplify policy creation.

Three-Tier Classification

AI Auto-Generation

The AutoConditionTemplateService exists to generate condition templates through admin/maintenance flows and AI-backed generation services. In the current OSS tree, this is not wired as an always-on startup step for Policy Center authoring:

• Batch generation based on resource types and access patterns
• Complexity scoring (1-10 scale) for each template
• SpEL safety validation to block dangerous patterns

Condition Compatibility

ConditionCompatibilityService filters conditions per resource:

• Domain compatibility —matches condition domain to resource domain
• Available variables —ensures referenced SpEL variables exist in the evaluation context
• ABAC applicability —checks if Attribute-Based Access Control conditions are relevant

Business Policy Service

BusinessPolicyService translates business-level authorization rules into technical SpEL policy conditions, persists the policy, records a version snapshot, updates linked resource status when permission-backed targets are involved, and reloads runtime authorization mappings.

SpEL Expression Conversion

Safety Validation

Custom SpEL expressions are validated before storage to block:

• System-level method calls
• Reflection-based access
• Runtime class loading
• File system operations

Policy Creation Flow

Policy Wizard: Quick Grant Guide

The quick-create flow inside Policy Center is the fastest way to author a simple policy. Use it when you need straightforward role-based access with selected roles, stored permissions, CRUD actions, or a saved SecuritySpel expression, without editing the full manual form.

When to Use the Wizard

• Simple role-based permission grants without complex conditions
• Granting access to a single resource for one or more roles
• Quick setup during initial resource onboarding
• No need for time-based, IP-based, or AI-assisted conditions

Step-by-Step Guide

What the Wizard Auto-Creates

When you confirm, the quick flow persists a policy and updates the linked runtime metadata shown below:

Policy Authoring: Advanced Policy Creation

The advanced authoring flow is exposed primarily through the Policy Center create tab. The legacy /admin/policy-builder controller path still exists in server code, but the current OSS bundle centers operator workflows on Policy Center.

When to Use the Builder

• Policies with time-based, IP-based, or ownership conditions
• AI-assisted authorization expressions (#ai.isAllowed())
• Multi-rule policies with different condition combinations
• DENY policies or priority-sensitive configurations
• Policies requiring custom SpEL expressions

Step-by-Step Guide

Context-Aware Mode (from-resource)

When launched from a selected Policy Center resource or the legacy /admin/policy-builder/from-resource route, the builder enters from-resource mode:

• Pre-filled target: The resource URL pattern or method signature is automatically set as the policy target
• Filtered conditions: ConditionCompatibilityService filters condition templates to show only those compatible with the resource domain
• Domain-specific variables: Available SpEL context variables are displayed based on the resource type
• ABAC applicability: Attribute-Based Access Control conditions are shown only when relevant to the resource

Condition Template Selection

AI-Assisted Condition Recommendation

Policy authoring can use AI-assisted draft generation and condition suggestions backed by the resource, role, permission, template, and existing policy data already loaded into Policy Center. In OSS, the AI result feeds the existing business-rule and manual authoring model rather than introducing a separate policy language or a dedicated AI action editor.

• The selected resource metadata such as type, identifier, and HTTP method
• Existing policies and validation data already loaded for similar targets
• The currently selected roles, CRUD permissions, and stored SpEL shortcuts
• Stored condition templates and compatibility results for the resource context

Suggested conditions can be reviewed, edited, or replaced before the policy is saved.

Wizard vs. Builder: Decision Guide

AI Policy Approval Workflow

Policies generated by the AI engine follow an approval workflow to ensure human oversight before enforcement.

Approval Lifecycle

Enforcement Rules

CustomDynamicAuthorizationManager only evaluates policies that meet all of the following criteria:

• isActive = true -- the policy is currently enabled
• approvalStatus is neither PENDING nor REJECTED -- AI-generated policies must be APPROVED, while manual policies typically remain NOT_REQUIRED

Policies created through the normal quick/manual Policy Center flows typically use source = MANUAL and approvalStatus = NOT_REQUIRED. They can be enforced as soon as they are saved and activated.

Admin Review Process

1. Open /admin/policy-center?tab=list and filter the policy list by approvalStatus = PENDING
2. Review the policy details in the list/detail flow: name, description, targets, rules, and conditions
3. Check the generated friendlyDescription, reasoning, and source metadata for accuracy
4. Use the Policy Center simulator or /admin/policy-center/api/simulate to preview the impact before approval
5. Use validation, AI validation, and impact-analysis results to review conflicts before approval
6. Approve or reject the policy through /admin/policies/{id}/approve or /admin/policies/{id}/reject while working from the Policy Center list/detail flow

Condition Template Examples

The following examples illustrate common condition templates used in policy rules. Each template is a SpEL expression that is evaluated at authorization time.

Policy Center REST API

The current Policy Center server surface is centered on /admin/policy-center, with analysis APIs under /admin/policy-center/api/, form submission under /admin/policy-center/create-policy, and business-rule creation under /admin/api/policies/build-from-business-rule.

Policy CRUD

Policy Analysis

Policy Versioning

The versioning endpoints are implemented and active. The current OSS Policy Center template does not render a dedicated version-history panel, so operators typically consume these endpoints from automation, custom tooling, or future UI extensions.

Resource & Permission Queries

Migration & Maintenance