blob: a2e52e0e05bb6aae549c9bd7c63300f4a986b719 [file] [view]
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# Apache Syncope - AGENTS.md
This document provides context and guidelines for AI agents interacting with the Apache Syncope codebase.
## Project Overview
Apache Syncope is a unified identity management platform that enables consistent management of identities, attributes, group membership, relationships, and authorization across multiple applications and directories (LDAP, Active Directory, databases, SCIM, cloud IdPs).
**Version:** 5.0.0-SNAPSHOT
**License:** Apache-2.0
**Inception Year:** 2010
**Website:** https://syncope.apache.org/
**Build JDK:** OpenJDK 25 (CI also runs on 28-ea)
**Maven:** 3.9.x (CI uses 3.9.6)
## Architecture: Three Domains + Keymaster
Since 4.x the codebase is organized around three parallel domains sharing the same layering:
- **idrepo** - Users, Groups, AnyObjects, Realms, types, schemas, policies
- **idm** - Identity management extensions (roles, delegations, etc.)
- **am** - Access management (auth modules, OIDC clients, SAML SP, MFA)
Each domain is split into `common/<domain>` (API contracts), `core/<domain>` (server logic + REST), `client/<domain>` (Wicket UIs).
**Keymaster** provides key management / encryption and lives in `common/keymaster` + `core/self-keymaster-starter`.
Typical request flow: `client` → JAX-RS interface (`common/*/rest-api`) → implementation (`core/*/rest-cxf`) → logic (`core/*/logic`) → DAO (`core/persistence-api` → `core/persistence-jpa`) → database.
## Multi-Module Maven Structure
```
root (parent POM) [5.0.0-SNAPSHOT]
├── common/
│ ├── keymaster/ - Key management
│ │ ├── client-api/
│ │ ├── client-zookeeper/
│ │ └── self/
│ ├── idrepo/
│ │ ├── lib/ - Shared beans, TOs, utilities
│ │ └── rest-api/ - JAX-RS annotated service interfaces
│ ├── idm/
│ │ ├── lib/
│ │ └── rest-api/
│ └── am/
│ ├── lib/
│ └── rest-api/
├── core/
│ ├── idrepo/ - logic/ + rest-cxf/
│ ├── idm/ - logic/ + rest-cxf/
│ ├── am/ - logic/ + rest-cxf/
│ ├── persistence-api/ - Entity + DAO interfaces
│ ├── persistence-common/ - Shared persistence code
│ ├── persistence-jpa/ - Hibernate ORM entities and DAOs
│ ├── persistence-neo4j/ - Neo4j persistence
│ ├── provisioning-api/ - Provisioning interfaces
│ ├── provisioning-java/ - Provisioning managers, push/pull
│ ├── workflow-api/ - Workflow interfaces
│ ├── workflow-java/ - Workflow logic
│ ├── spring/ - Spring Boot auto-configuration, security
│ ├── starter/ - Spring Boot starter
│ ├── self-keymaster-starter/
│ └── metrics-starter/ - Micrometer / metrics
├── client/
│ ├── idrepo/ - common-ui/, console/, enduser/, lib/
│ ├── idm/ - console/, lib/
│ └── am/ - console/, enduser/, lib/
├── ext/
│ ├── flowable/ - Workflow engine integration (Flowable)
│ ├── saml2sp4ui/ - SAML 2.0 Service Provider for UIs
│ ├── oidcc4ui/ - OpenID Connect for UIs
│ ├── elasticsearch/ - Elasticsearch persistence
│ ├── opensearch/ - OpenSearch persistence
│ ├── scimv2/ - SCIM v2 API
│ └── openfga/ - OpenFGA authorization
├── wa/ - Web Access (legacy): bootstrap/, starter/ with CAS
├── fit/ - Functional integration tests
│ ├── build-tools/
│ ├── persistence-embedded/
│ ├── core-reference/
│ ├── console-reference/
│ ├── enduser-reference/
│ └── wa-reference/
├── standalone/ - Standalone distribution
├── docker/ - Docker images (console/, core/, enduser/, wa/)
├── archetype/ - Maven archetype
└── src/main/asciidoc/ - Reference guide / getting started sources
```
Note: Kubernetes Helm charts are **not** a top-level module; they live under `docker/src/main/resources/kubernetes/`.
## Key Technologies and Dependencies
### Core stack (versions from root `pom.xml`)
| Component | Version | Notes |
|-----------|---------|-------|
| Java / `targetJdk` | 25 | `maven-compiler-plugin` `<release>25</release>` |
| Spring Boot | 4.2.0-RC2 | Provides BOM, auto-configuration, embedded Tomcat |
| Apache CXF | 4.2.4 | JAX-RS (REST) endpoints |
| Hibernate ORM | 7.4.15.Final | JPA provider (Jakarta Persistence), build-time enhancement |
| Spring Security | 7.x | Via `spring-boot-starter-security` |
| Apache Wicket | 11.0.0 | Console / Enduser UIs (not React/Vue) |
| Swagger / OpenAPI | 3.0.0 | + `swagger-ui` 5.34.1 |
| Tomcat | 11.0.27 (from Spring Boot BOM line) | Embedded container |
### Security & identity protocols
- **Spring Security 7** - authentication/authorization in core and clients (no Apache Shiro anymore)
- **Pac4j 6.6.1** - SAML 2.0 (`ext/saml2sp4ui`) and OpenID Connect (`ext/oidcc4ui`)
- **CAS 8.1.0-RC3** / CAS client 4.1.1 - used by the legacy `wa` module
- **OpenFGA** (`openfga.version = v1`) - relationship-based authorization, `ext/openfga`
- **SCIM v2** - `ext/scimv2`
- **BouncyCastle 1.86**, **Nimbus JOSE+JWT 10.10** - crypto/JWT support
### Persistence, search, workflow
- **Hibernate ORM 7.4.15.Final** with `jakarta.persistence` annotations, `hibernate-jcache` for
second-level caching and `hibernate-maven-plugin` for build-time bytecode enhancement
- **Spring Data JPA** - `SyncopeJPARepository` extends `SimpleJpaRepository`
- **Neo4j** - `core/persistence-neo4j`
- **Elasticsearch** 9.5.6 / **OpenSearch** 3.9.0 (Java client 3.11.0) - optional persistence
- **Flowable** 8.0.0 - workflow engine (`ext/flowable`); legacy 6.8.1 also referenced
- **Debezium** 3.4 - CDC integration
### Connectors (ConnId bundles, configured via `connid.*.version`)
LDAP 1.5.11, Active Directory 1.4.0, Azure 3.0.0, SCIM 1.0.5, Okta 3.0.8,
ServiceNow 1.0.4, Database 2.5.0, CSV directory 0.8.10, Kafka 1.0.0, REST 1.2.0, Google Apps 1.4.6.
### Apache Commons (versions in parent POM)
`commons-lang3` 3.22.0, `commons-text` 1.15.0, `commons-codec` 1.22.1, `commons-jexl` 3.7.1;
others (`commons-io`, `commons-collections4`, ...) managed transitively by the Spring Boot BOM.
### Testing stack
| Framework | Version | Purpose |
|-----------|---------|---------|
| JUnit Jupiter | 6.x (Spring Boot BOM) | Unit/integration tests |
| Mockito | 5.x | Mocking |
| AssertJ | 3.x | Fluent assertions |
| Spring Boot Test | 4.2.0-RC2 | Context/integration tests |
| Testcontainers | 2.0.5 | `core/persistence-jpa` and `ext/openfga` tests (FIT uses embedded PostgreSQL + Cargo instead) |
| JaCoCo | | Coverage |
## Agent Guidelines
### Code Quality Standards
1. **Module boundaries**
- `common/<domain>/rest-api`: JAX-RS **interfaces** only (annotations live here)
- `core/<domain>/rest-cxf`: implementations, extend `Abstract*Service`
- `core/<domain>/logic`: business logic, classes usually named `*Logic` / `*LogicOp`
- `core/persistence-api`: entity and DAO **interfaces**
- `core/persistence-jpa`: JPA entities (`JPA*`) and DAO implementations (`JPA*DAO`)
- `ext/*`: optional integrations; keep core free of optional dependencies
2. **Persistence**
- JPA provider is **Hibernate ORM 7** (Jakarta Persistence); annotations are `jakarta.persistence.*`
- Entity interfaces live in `core/persistence-api/entity`, implementations in `core/persistence-jpa/entity`
- DAO interfaces in `core/persistence-api/dao`, implementations in `core/persistence-jpa/dao`
- Hibernate-specific pieces stay in `core/persistence-jpa`: `HibernateJpaVendorAdapter`, the custom
`SyncopePostgreSQLDialect`, `DomainJCacheRegionFactory`, `hibernate.default_schema` / cache
region-prefix configuration and `hibernate-maven-plugin` enhancement
- The package `org.apache.syncope.core.persistence.jpa.openjpa` is a legacy name: it now hosts a
Hibernate/JCache cache-entry listener, not OpenJPA code
- Never mix raw SQL in business logic; use DAOs / JPQL / Criteria
3. **Security-first**
- Use the existing Spring Security configuration (`core/spring`) and the domain auth modules
- Validate inputs via Bean Validation (`jakarta.validation`) and existing validators
- Use parameterized JPA/JPQL queries only; never concatenate user input
- Never log secrets, passwords, tokens, or key material
4. **Testing**
- Unit tests: JUnit Jupiter + Mockito in the same module under `src/test/java`
- Integration/FIT: `fit/core-reference`, `fit/console-reference`, `fit/enduser-reference`, `fit/wa-reference`
(see [Integration Tests (FIT)](#integration-tests-fit) for commands)
- Embedded DB tests: `fit/persistence-embedded`
- Prefer meaningful coverage of logic-bearing classes; exceptions, annotations, enums and
Spring `@Configuration` classes are lower priority
- Test-only changes: run the affected module's tests and Checkstyle
- Production behavior changes: also run `fit/core-reference` when feasible
- Tests must be independent: never rely on class execution order
- **Neo4j persistence tests** (`core/persistence-neo4j`) require the `-Pneo4j` profile and a
running Docker daemon: they start Neo4j containers via the `docker-maven-plugin` and run
through `maven-failsafe-plugin` (integration tests), e.g.
`mvn -pl core/persistence-neo4j -Pneo4j verify`. Use `-Dit.test=...` to select individual
tests (surefire's `-Dtest=...` does not apply).
5. **No compiler warnings**
- Produce clean compilation output: zero compiler warnings (unchecked, deprecation, raw types, etc.).
- Fix root causes rather than suppressing warnings with `@SuppressWarnings`.
- Verify by running `mvn -pl <module> test-compile` and checking for warnings.
6. **Modernizer rules**
- Code must pass the `modernizer:modernizer` check (e.g. prefer `java.util.Map.of()` over traditional map construction).
- Verify by running `mvn -pl <module> modernizer:modernizer` and fixing any reported violations.
### Common Code Patterns
#### JAX-RS service interface (`common/<domain>/rest-api`)
```java
package org.apache.syncope.common.rest.api.service;
@Path("groups")
@Produces({ MediaType.APPLICATION_JSON, SyncopeConstants.APPLICATION_YAML })
@Consumes({ MediaType.APPLICATION_JSON, SyncopeConstants.APPLICATION_YAML })
public interface GroupService extends AnyService<GroupTO> {
@GET
@Path("{key}")
GroupTO read(@PathParam("key") String key);
}
```
#### REST implementation (`core/<domain>/rest-cxf/.../service`)
```java
public class GroupServiceImpl extends AbstractAnyService<GroupTO, GroupCR, GroupUR>
implements GroupService {
protected final GroupDAO groupDAO;
protected final GroupLogicOp logic;
public GroupServiceImpl(AnySearchCondVisitor v, GroupDAO groupDAO, GroupLogicOp logic) {
super(v);
this.groupDAO = groupDAO;
this.logic = logic;
}
}
```
There are **no** `@RestResource` / `@RestMethod` annotations in 5.0; use standard JAX-RS plus the `JAXRSService` interfaces.
#### JPA entity (`core/persistence-jpa/.../entity`)
```java
package org.apache.syncope.core.persistence.jpa.entity;
@Entity
@Table(name = JPADelegation.TABLE, uniqueConstraints =
@UniqueConstraint(columnNames = { "delegating_id", "delegated_id" }))
@Cacheable
public class JPADelegation extends AbstractGeneratedKeyEntity implements Delegation {
public static final String TABLE = "Delegation";
@ManyToOne(optional = false)
private JPAUser delegating;
@NotNull
@Column(nullable = false)
private OffsetDateTime startDate;
}
```
#### DAO (`core/persistence-api/dao` + `core/persistence-jpa/dao`)
```java
public interface GroupDAO extends AnyDAO<Group> { ... }
// implementation in core/persistence-jpa/dao, e.g. JPAGroupDAO
```
#### Provisioning (`core/provisioning-java`)
```java
public class DefaultGroupProvisioningManager implements GroupProvisioningManager {
// push / pull / deprovision logic
}
```
#### Client UI (`client/<domain>`)
The Console and Enduser are **Apache Wicket 11** applications on Spring Boot
(`wicket-spring-boot-starter`), not React/Vue/Angular.
#### Unit tests in `core/spring`
`core/spring` hosts most of the pure unit tests for security, policies, JWS and task
execution. Follow these patterns:
- Use JUnit Jupiter + Mockito; plain `Mockito.mock(...)` is fine, `MockitoExtension` is optional.
- Put the test in the same package as the class under test when protected members need to be
exercised (for example filters' `doFilterInternal` or rules' `enforce`).
- Use `mockStatic(...)` and `mockConstruction(...)` for static factories and collaborators
created with `new` (for example `ImplementationManager` and `RestTemplate`).
- Save and restore global static state in `@BeforeEach` / `@AfterEach`:
- `ApplicationContextProvider` (application context **and** bean factory)
- `SecurityContextHolder` (call `clearContext()`)
- JCache caches used by throttlers
- When a test needs `ApplicationContextProvider`, build a `StaticApplicationContext`, register
the required beans (for example `SecurityProperties`, `UserDAO`), and restore the previous
state afterwards.
- Do **not** leave `ApplicationContextProvider` set to `null`: Spring Test caches application
contexts and will not re-invoke `ApplicationContextAware` on a cached context, which can break
unrelated tests in the same module run.
- For time-dependent throttlers, override `now()` or inject a clock supplier instead of sleeping.
- Respect Checkstyle `ImportOrder`: static imports first (alphabetical, separate group), then
non-static imports alphabetically.
## Build Commands
### Maven
```bash
# Fast local build (skip tests)
mvn clean install -DskipTests
# Full build including unit + integration (FIT) tests - slow
mvn clean install
# Everything except the FIT integration tests
mvn clean install -DskipITs
# Single module + required upstream modules
mvn clean install -pl core/idrepo -am
# Tests only (ignore failures to inspect all)
mvn test -Dmaven.test.failure.ignore=true
# Unit tests for one module plus Checkstyle
mvn -pl core/spring test checkstyle:check
# Single test class / selected test classes
mvn -pl core/spring -Dtest=MyTest test
mvn -pl core/spring -Dtest='MyTest,OtherTest' -DfailIfNoTests=false test
# Disable Maven build cache (avoids stale results when verifying fixes)
mvn -pl <module> ... -Dmaven.build.cache.enabled=false
# JPA persistence tests against a real DBMS via Docker (default: embedded PostgreSQL)
mvn -pl core/persistence-jpa -Pmysql test
mvn -pl core/persistence-jpa -Pmariadb test
mvn -pl core/persistence-jpa -Poracle test
# Static checks used by CI
mvn checkstyle:check tools:verify-legal-files modernizer:modernizer apache-rat:check
# Site / docs (AsciiDoc reference guide)
mvn clean generate-resources site-deploy -Psite
# Docker profile (adds docker/ module)
mvn clean install -Pdocker
```
### Integration Tests (FIT)
The `fit/` modules are part of the default reactor and are **not** unit tests: they start an
embedded PostgreSQL, deploy WARs into an embedded Tomcat 11 (Cargo) and exercise the REST API,
the Console (WicketTester, in-process) and the Enduser. A plain `mvn clean install` therefore
runs them too - use `-DskipITs` (or `-DskipTests`) to skip them.
| Module | Content |
|--------|---------|
| `fit/build-tools` | Shared WAR deployed by all FIT setups (ConnId bundles, test resources) |
| `fit/persistence-embedded` | Embedded PostgreSQL (`io.zonky.test`) behind the `embedded` Spring profile |
| `fit/core-reference` | **All IT sources**: Core REST (`org.apache.syncope.fit.core`), Console (`...fit.console`), Enduser (`...fit.enduser`) |
| `fit/console-reference` | Console WAR (deployed by `fit/wa-reference`) |
| `fit/enduser-reference` | Enduser WAR (deployed by `fit/wa-reference`) |
| `fit/wa-reference` | WA WAR plus `OIDCC4UIITCase`, `OpenFGAUIITCase`, `SAML2SP4UIITCase` (`org.apache.syncope.fit.ui`) |
FIT modules resolve project artifacts from the local repository (not from a reactor), so
install everything first - this is exactly what CI does before running any FIT job:
```bash
mvn -U -T 1C -P 'skipTests,all'
```
Core FIT runs `maven-failsafe-plugin` (`*ITCase`) during `verify`, deploying the WAR to
`http://localhost:9080/syncope` (property `cargo.servlet.port`):
```bash
# Default: embedded PostgreSQL + all extensions (Spring profile "embedded,all")
mvn -f fit/core-reference/pom.xml verify
# Single IT / several ITs - -Dit.test is failsafe; -Dtest only reaches surefire
mvn -f fit/core-reference/pom.xml verify -Dit.test=RESTITCase
mvn -f fit/core-reference/pom.xml verify -Dit.test='RESTITCase,UserITCase'
# Same flags as CI, to silence unrelated plugins
mvn -f fit/core-reference/pom.xml verify -Dit.test=RESTITCase \
-Dinvoker.streamLogs=true -Dmodernizer.skip=true -Drat.skip=true \
-Dcheckstyle.skip=true -Djacoco.skip=true
```
Backend-specific runs use the `*-it` profiles below. They start containers with
`docker-maven-plugin` (Docker daemon required). `elasticsearch-it`, `opensearch-it`,
`mysql-it`, `mariadb-it`, `oracle-it`, `debezium-it` and `syncrepl-it` restrict failsafe to
`org/apache/syncope/fit/core/*ITCase` (Console/Enduser ITs are not run); `zookeeper-it` and
`neo4j-it` run the full suite:
| Profile | Spring profile / container |
|---------|----------------------------|
| `zookeeper-it` | `embedded,zookeeper` - ZooKeeper (keymaster) |
| `elasticsearch-it` | `embedded,elasticsearch` - Elasticsearch + Kibana |
| `opensearch-it` | `embedded,opensearch` - OpenSearch |
| `mysql-it` | `embedded,mysql` - MySQL |
| `mariadb-it` | `embedded,mariadb` - MariaDB |
| `oracle-it` | `embedded,oracle` - Oracle |
| `neo4j-it` | `embedded,neo4j` - Neo4j |
| `debezium-it` | MySQL + Kafka Connect, only `DebeziumITCase` |
| `syncrepl-it` | OpenLDAP, only `SyncReplITCase` |
```bash
mvn -f fit/core-reference/pom.xml -P mysql-it
mvn -f fit/core-reference/pom.xml -P elasticsearch-it
```
#### External search backends: index refresh and IT timing
When the `elasticsearch-it` / `opensearch-it` profile is active, `AnySearchDAO` is backed by the
external index. User / Group / AnyObject documents are written by
`ElasticsearchIndexManager#entity` / `OpenSearchIndexManager#entity`, which are
`@TransactionalEventListener`s invoked after commit; unlike the Realm branch, they do **not**
pass `refresh(Refresh.True)`. Changes therefore become searchable only after the index refresh
interval (default 1s), which can be longer on loaded CI runners.
This makes ITs that assert exact counts immediately after create / update / delete racy; the
`awaitIfExtSearchEnabled()` helper in `AbstractITCase` is only a fixed ~2s sleep, not a real
readiness check. Prefer Awaitility polling until the expected state is observed, re-reading all
involved values inside the retry loop. Also note that with external search `orderBy` does not
participate in `AnySearchDAO.count(...)`, so comparing two counts only checks whether the index
changed between the two requests. These failures typically reproduce only in CI (containerised
ES/OS with limited heap), not locally.
WA FIT deploys Core, Console, Enduser and WA WARs over HTTPS (9443) and starts `httpbin`
and `openfga` containers:
```bash
mvn -f fit/wa-reference/pom.xml verify -Dit.test=OIDCC4UIITCase
mvn -f fit/wa-reference/pom.xml verify -Dit.test=OpenFGAUIITCase
# SAML2SP4UI additionally needs the test keystore on its test classpath
mkdir -p fit/wa-reference/target/test-classes
cp fit/core-reference/src/test/resources/saml.keystore.jks fit/wa-reference/target/test-classes/
mvn -f fit/wa-reference/pom.xml verify -Dit.test=SAML2SP4UIITCase
```
`-P debug` and `-P hotswap` (all `fit/*-reference` modules) change the default goal to
`clean verify cargo:run`: the ITs are skipped and Tomcat stays in the foreground with JDWP on
port 8000 for interactive debugging.
Reports: `target/failsafe-reports/`; Cargo/Tomcat logs under `target/cargo/logs/`.
### Profiles
| Profile | Purpose |
|---------|---------|
| `skipTests` | Skip tests via profile (used by CI build step) |
| `docker` | Adds the `docker` module / image build |
| `site` | AsciiDoc site generation and deployment |
| `mysql`, `mariadb`, `oracle` | `core/persistence-jpa` only: run its tests against the matching DBMS via Docker/Testcontainers instead of embedded PostgreSQL |
| `zookeeper-it`, `elasticsearch-it`, `opensearch-it`, `mysql-it`, `mariadb-it`, `oracle-it`, `neo4j-it`, `debezium-it`, `syncrepl-it` | `fit/core-reference` only: run FIT against the matching backend/container - see [Integration Tests (FIT)](#integration-tests-fit) |
| `debug`, `hotswap` | `fit/*-reference` only: start the container for interactive debugging instead of running ITs |
Hibernate ORM is a regular release dependency: no Apache snapshot repository is required for the
JPA provider (CI builds use `-P 'skipTests,all'`).
### Docker Compose
Compose files live in `docker/src/main/resources/docker-compose/`:
```bash
cd docker/src/main/resources/docker-compose
docker compose -f docker-compose-all.yml up -d --build # full stack, PostgreSQL
docker compose -f docker-compose-postgresql.yml up -d
docker compose -f docker-compose-mysql.yml up -d
docker compose -f docker-compose-mariadb.yml up -d
docker compose -f docker-compose-oracle.yml up -d
docker compose -f docker-compose-ha.yml up -d # HA setup
```
`docker-compose-all.yml` is the full deployment (Core, Console, Enduser, WA, Keymaster/Zookeeper)
on **PostgreSQL**, not MySQL.
### Kubernetes (Helm)
```bash
kubectl apply -f docker/src/main/resources/kubernetes/syncope/
# or Helm
helm install syncope ./docker/src/main/resources/kubernetes/syncope
helm install postgres ./docker/src/main/resources/kubernetes/postgres
```
Charts: `docker/src/main/resources/kubernetes/syncope/` (Core, Console, Enduser)
and `docker/src/main/resources/kubernetes/postgres/`.
## Database Support
- **PostgreSQL** - default for Docker/K8s
- **MySQL**, **MariaDB**, **Oracle**
- **Neo4j** - via `core/persistence-neo4j` (GitHub Actions workflow `neo4j.yml`)
- **Elasticsearch / OpenSearch** - via `ext/elasticsearch` / `ext/opensearch`
- Embedded DB for tests - `fit/persistence-embedded`
Spring profiles select the database in Docker (`docker,postgresql,saml2`, `docker,mysql`, ...).
## CI / Quality Gates
CI is on **GitHub Actions** (`.github/workflows/`), not Jenkins:
- `crosschecks.yml` - build + validate + test matrix on JDK 25 and 28-ea, Linux/Windows/macOS
- `codeql-analysis.yml` - CodeQL security analysis
- `dockerhub.yml` - Docker image publication
- `fit_*.yml` - FIT suites: `fit_Tomcat_PostgreSQL.yml` (default `fit/core-reference`), `fit_Elasticsearch.yml`, `fit_OpenSearch.yml`, `fit_Zookeeper.yml`, `fit_Tomcat_LiveSync.yml` (`debezium-it` + `syncrepl-it`), `fit_WA_*.yml`
- `mysql.yml`, `mariadb.yml`, `oracle.yml`, `neo4j.yml` - `core/persistence-jpa` (or `-neo4j`) unit tests + the matching `fit/core-reference` `*-it` profile
Every FIT job starts with `mvn -U -T 1C -P 'skipTests,all'` and then runs
the corresponding `mvn -f fit/...` command (see [Integration Tests (FIT)](#integration-tests-fit)).
Quality tooling: Checkstyle, Modernizer, Apache RAT, JaCoCo, Maven Enforcer.
## Troubleshooting
1. **JDK errors** - build requires JDK 25 (`targetJdk=25`); older JDKs fail at compile.
2. **Hibernate ORM, not OpenJPA** - the JPA provider is Hibernate; no OpenJPA snapshot or
`use-apache-snapshots` profile is involved. Keep Hibernate-specific code inside
`core/persistence-jpa` and prefer portable Jakarta Persistence APIs elsewhere.
3. **Checkstyle/Modernizer/RAT failures** - run the same goals as CI (see Build Commands) before submitting.
4. **FIT failures** - default FIT needs no Docker (embedded PostgreSQL via `fit/persistence-embedded`);
the `*-it` profiles and `fit/wa-reference` start containers with `docker-maven-plugin`, so Docker
must be running and its images reachable. Install the project first (`-P 'skipTests,...'`),
otherwise FIT resolves stale artifacts from the local repository.
5. **Docker stack issues** - use the compose files under `docker/src/main/resources/docker-compose/`
and check `SPRING_PROFILES_ACTIVE` matches the chosen database.
6. **UI changes** - Console/Enduser are Wicket apps; rebuild `client/<domain>` and use the
`*-reference` FIT modules for regression checks.
7. **Test order interference** - if a test fails only in the full module run, look for global
static state (`ApplicationContextProvider`, `SecurityContextHolder`, JCache) that was not
saved and restored around the test.
8. **External-search FIT failures (counts / visibility)** - `elasticsearch-it` and
`opensearch-it` index writes are near-real-time (no forced refresh for Users / Groups /
AnyObjects), so exact-count assertions right after mutations can fail only in CI; see
[External search backends](#external-search-backends-index-refresh-and-it-timing).
## Repository Information
- **Main Repository:** https://github.com/apache/syncope/
- **CI:** GitHub Actions - https://github.com/apache/syncope/actions
- **Issue Tracker:** https://issues.apache.org/jira/browse/SYNCOPE
- **Mailing Lists:** `user@syncope.apache.org`, `dev@syncope.apache.org`, `commits@syncope.apache.org`
- Archives: https://lists.apache.org/list.html?dev@syncope.apache.org
- **Website & Docs:** https://syncope.apache.org/
## For AI Agents Working with Syncope
1. **Respect the domain layering**: `common/<domain>/rest-api` → `core/<domain>/rest-cxf` → `core/<domain>/logic` → DAO.
2. **JPA is Hibernate ORM + Jakarta Persistence**: keep Hibernate-specific code (dialects, cache,
vendor adapter, enhancement) inside `core/persistence-jpa`.
3. **No Shiro**: authentication/authorization is Spring Security (core/clients) plus Pac4j and OpenFGA.
4. **UIs are Apache Wicket**, not SPA frameworks.
5. **Optional features belong in `ext/`**; core must not depend on them.
6. **Keep JDK 25 compatibility** and run Checkstyle/Modernizer/RAT-compatible code.
7. **Keep unit tests order-independent** and restore global static state
(`ApplicationContextProvider`, `SecurityContextHolder`, JCache) after each test.
---
*This AGENTS.md was generated for Apache Syncope 5.0.0-SNAPSHOT to assist AI agents and developers working with the codebase.*