+ * This class ensures thread-safe user retrieval and creation by using a
+ * {@link ReadWriteLock}. Implementations must define specific storage
+ * operations for finding and creating users.
+ *
+ *
+ *
+ * When a new user is created, an {@link AccountCreated} event is published
+ * using the {@link ApplicationEventPublisher} to notify the system of the new
+ * account.
+ *
+ *
+ * @see AccountManager
+ * @see org.georchestra.gateway.security.exceptions.DuplicatedEmailFoundException
+ * @see org.georchestra.security.model.GeorchestraUser
+ */
@RequiredArgsConstructor
public abstract class AbstractAccountsManager implements AccountManager {
@@ -36,11 +55,38 @@ public abstract class AbstractAccountsManager implements AccountManager {
protected final ReadWriteLock lock = new ReentrantReadWriteLock();
+ /**
+ * Retrieves an existing stored user corresponding to {@code mappedUser} or
+ * creates a new one if not found.
+ *
+ * This method ensures thread safety by acquiring a read lock when searching for
+ * the user and a write lock when creating a new user.
+ *
+ *
+ * If a new user is created, an {@link AccountCreated} event is published.
+ *
+ *
+ * @param mappedUser the user to find or create
+ * @return the existing or newly created {@link GeorchestraUser}
+ * @throws DuplicatedEmailFoundException if a user with the same email already
+ * exists
+ */
@Override
public GeorchestraUser getOrCreate(@NonNull GeorchestraUser mappedUser) throws DuplicatedEmailFoundException {
return find(mappedUser).orElseGet(() -> createIfMissing(mappedUser));
}
+ /**
+ * Retrieves the stored user corresponding to {@code mappedUser}, if it exists.
+ *
+ * This method is thread-safe and acquires a read lock to ensure consistent
+ * reads.
+ *
+ *
+ * @param mappedUser the user to search for
+ * @return an {@link Optional} containing the found user, or an empty
+ * {@link Optional} if not found
+ */
public Optional find(GeorchestraUser mappedUser) {
lock.readLock().lock();
try {
@@ -50,34 +96,86 @@ public Optional find(GeorchestraUser mappedUser) {
}
}
+ /**
+ * Internal method to search for a user based on OAuth2 credentials or username.
+ *
+ * This method is called within {@link #find(GeorchestraUser)} and does not
+ * apply any locking.
+ *
+ *
+ * @param mappedUser the user to search for
+ * @return an {@link Optional} containing the found user, or an empty
+ * {@link Optional} if not found
+ */
protected Optional findInternal(GeorchestraUser mappedUser) {
- if ((null != mappedUser.getOAuth2Provider()) && (null != mappedUser.getOAuth2Uid())) {
+ if (mappedUser.getOAuth2Provider() != null && mappedUser.getOAuth2Uid() != null) {
return findByOAuth2Uid(mappedUser.getOAuth2Provider(), mappedUser.getOAuth2Uid());
}
return findByUsername(mappedUser.getUsername());
}
+ /**
+ * Creates a user if it does not already exist in the repository.
+ *
+ * This method acquires a write lock to ensure only one thread creates a user at
+ * a time. If a user is created, an {@link AccountCreated} event is published.
+ *
+ *
+ * @param mapped the user to create if missing
+ * @return the existing or newly created {@link GeorchestraUser}
+ * @throws DuplicatedEmailFoundException if a user with the same email already
+ * exists
+ */
protected GeorchestraUser createIfMissing(GeorchestraUser mapped) throws DuplicatedEmailFoundException {
lock.writeLock().lock();
try {
GeorchestraUser existing = findInternal(mapped).orElse(null);
- if (null == existing) {
+ if (existing == null) {
createInternal(mapped);
existing = findInternal(mapped).orElseThrow(() -> new IllegalStateException(
- "User " + mapped.getUsername() + " not found right after creation"));
+ "User " + mapped.getUsername() + " not found immediately after creation"));
eventPublisher.publishEvent(new AccountCreated(existing));
}
return existing;
-
} finally {
lock.writeLock().unlock();
}
}
+ /**
+ * Finds a user by their OAuth2 provider and unique identifier.
+ *
+ * Implementations must provide a concrete method for retrieving users from
+ * storage.
+ *
+ *
+ * @param oauth2Provider the OAuth2 provider (e.g., Google, GitHub)
+ * @param oauth2Uid the unique identifier assigned by the OAuth2 provider
+ * @return an {@link Optional} containing the found user, or an empty
+ * {@link Optional} if not found
+ */
protected abstract Optional findByOAuth2Uid(String oauth2Provider, String oauth2Uid);
+ /**
+ * Finds a user by their username.
+ *
+ * Implementations must provide a concrete method for retrieving users from
+ * storage.
+ *
+ *
+ * @param username the username to search for
+ * @return an {@link Optional} containing the found user, or an empty
+ * {@link Optional} if not found
+ */
protected abstract Optional findByUsername(String username);
+ /**
+ * Creates a new user in the repository.
+ *
+ * Implementations must define how users are persisted in the storage system.
+ *
+ *
+ * @param mapped the user to create
+ */
protected abstract void createInternal(GeorchestraUser mapped);
-
-}
+}
\ No newline at end of file
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountCreated.java b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountCreated.java
index ee536f54..14f695f3 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountCreated.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountCreated.java
@@ -24,10 +24,23 @@
import lombok.Value;
/**
- * Application event published when a new account has been created
+ * Event published when a new {@link GeorchestraUser} account is created.
+ *
+ * This event is triggered whenever a new user is successfully registered in the
+ * system. It can be used to listen for account creation and trigger additional
+ * actions such as logging, notifications, or audits.
+ *
+ *
+ *
+ * This class is immutable and thread-safe, though the attached
+ * {@link GeorchestraUser} is mutable, so make sure not to modify it.
+ *
+ *
+ * @see GeorchestraUser
*/
@Value
public class AccountCreated {
+ /** The newly created user account. */
private @NonNull GeorchestraUser user;
-}
+}
\ No newline at end of file
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountManager.java b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountManager.java
index 02d1b897..90e79a75 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountManager.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/AccountManager.java
@@ -27,35 +27,48 @@
import org.springframework.security.core.Authentication;
/**
+ * Manages the retrieval and creation of stored {@link GeorchestraUser
+ * Georchestra users}.
+ *
+ * This interface provides methods to look up an existing user or create a new
+ * one if it does not exist. Implementations of this interface should ensure
+ * that user accounts are correctly managed within the system and that necessary
+ * events are published when a new user is created.
+ *
+ *
* @see CreateAccountUserCustomizer
* @see ResolveGeorchestraUserGlobalFilter
*/
public interface AccountManager {
/**
- * Finds the stored user that belongs to the {@code mappedUser} if it exists
+ * Retrieves the stored user corresponding to the given {@code mappedUser}, if
+ * it exists.
*
- * @param mappedUser the user {@link ResolveGeorchestraUserGlobalFilter}
- * resolved by calling
+ * @param mappedUser the user resolved by
+ * {@link ResolveGeorchestraUserGlobalFilter}, obtained
+ * through a call to
* {@link GeorchestraUserMapper#resolve(Authentication)}
- * @return the stored version of the user if it exists, otherwise an empty
- * Optional
+ * @return an {@link Optional} containing the stored version of the user if
+ * found; otherwise, an empty {@link Optional}
*/
Optional find(GeorchestraUser mappedUser);
/**
- * Finds the stored user that belongs to the {@code mappedUser} or creates it if
- * it doesn't exist in the users repository.
+ * Retrieves the stored user corresponding to the given {@code mappedUser}, or
+ * creates a new user if one does not already exist in the repository.
*
- * When a user is created, an {@link AccountCreated} event must be published to
- * the {@link ApplicationEventPublisher}.
- *
- * @param mappedUser the user {@link ResolveGeorchestraUserGlobalFilter}
- * resolved by calling
+ * If a new user is created, an {@link AccountCreated} event must be published
+ * via the {@link ApplicationEventPublisher} to notify the system of the new
+ * account.
+ *
+ *
+ * @param mappedUser the user resolved by
+ * {@link ResolveGeorchestraUserGlobalFilter}, obtained
+ * through a call to
* {@link GeorchestraUserMapper#resolve(Authentication)}
- * @return the stored version of the user, whether it existed or was created as
- * the result of calling this method.
+ * @return the stored version of the user, either previously existing or newly
+ * created
*/
GeorchestraUser getOrCreate(GeorchestraUser mappedUser);
-
-}
+}
\ No newline at end of file
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/GeorchestraLdapAccountManagementConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/GeorchestraLdapAccountManagementConfiguration.java
index d03501ce..35e5a092 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/GeorchestraLdapAccountManagementConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/GeorchestraLdapAccountManagementConfiguration.java
@@ -41,10 +41,34 @@
import org.springframework.ldap.pool.factory.PoolingContextSource;
import org.springframework.ldap.pool.validation.DefaultDirContextValidator;
+/**
+ * Spring Boot configuration class for geOrchestra's LDAP-based account
+ * management.
+ *
+ * This class defines beans for managing LDAP user accounts, roles, and
+ * organizations using Spring LDAP and pooled connections.
+ *
+ *
+ * The configuration is driven by properties defined in
+ * {@link GeorchestraGatewaySecurityConfigProperties}.
+ *
+ */
@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(GeorchestraGatewaySecurityConfigProperties.class)
public class GeorchestraLdapAccountManagementConfiguration {
+ /**
+ * Defines the primary {@link AccountManager} bean using LDAP as the backend.
+ *
+ * @param eventPublisher the event publisher for account-related events
+ * @param accountDao the DAO for managing user accounts in LDAP
+ * @param roleDao the DAO for managing roles in LDAP
+ * @param orgsDao the DAO for managing organizations in LDAP
+ * @param demultiplexingUsersApi API for resolving users based on OAuth2
+ * credentials
+ * @param configProperties the security configuration properties
+ * @return an instance of {@link LdapAccountsManager}
+ */
@Bean
AccountManager ldapAccountsManager(//
ApplicationEventPublisher eventPublisher, //
@@ -53,16 +77,29 @@ AccountManager ldapAccountsManager(//
OrgsDao orgsDao, //
DemultiplexingUsersApi demultiplexingUsersApi,
GeorchestraGatewaySecurityConfigProperties configProperties) {
-
return new LdapAccountsManager(eventPublisher::publishEvent, accountDao, roleDao, orgsDao,
demultiplexingUsersApi, configProperties);
}
+ /**
+ * Registers a {@link CreateAccountUserCustomizer} bean to handle automatic
+ * account creation when a user logs in via trusted authentication mechanisms.
+ *
+ * @param accountManager the account manager responsible for user retrieval and
+ * creation
+ * @return a {@link CreateAccountUserCustomizer} instance
+ */
@Bean
CreateAccountUserCustomizer createAccountUserCustomizer(AccountManager accountManager) {
return new CreateAccountUserCustomizer(accountManager);
}
+ /**
+ * Creates an LDAP context source for connecting to a single LDAP directory.
+ *
+ * @param config the LDAP configuration properties
+ * @return a configured {@link LdapContextSource} instance
+ */
@Bean
LdapContextSource singleContextSource(GeorchestraGatewaySecurityConfigProperties config) {
ExtendedLdapConfig ldapConfig = config.extendedEnabled().get(0);
@@ -74,6 +111,12 @@ LdapContextSource singleContextSource(GeorchestraGatewaySecurityConfigProperties
return singleContextSource;
}
+ /**
+ * Configures a pooling LDAP context source to optimize connection management.
+ *
+ * @param singleContextSource the base LDAP context source
+ * @return a {@link PoolingContextSource} with connection pooling enabled
+ */
@Bean
PoolingContextSource contextSource(LdapContextSource singleContextSource) {
PoolingContextSource contextSource = new PoolingContextSource();
@@ -88,11 +131,24 @@ PoolingContextSource contextSource(LdapContextSource singleContextSource) {
return contextSource;
}
+ /**
+ * Creates an {@link LdapTemplate} for interacting with LDAP.
+ *
+ * @param contextSource the pooled LDAP context source
+ * @return an initialized {@link LdapTemplate}
+ */
@Bean
- LdapTemplate ldapTemplate(PoolingContextSource contextSource) throws Exception {
+ LdapTemplate ldapTemplate(PoolingContextSource contextSource) {
return new LdapTemplate(contextSource);
}
+ /**
+ * Creates a {@link RoleDao} implementation for managing LDAP roles.
+ *
+ * @param ldapTemplate the LDAP template for querying LDAP
+ * @param config the security configuration properties
+ * @return a configured {@link RoleDaoImpl}
+ */
@Bean
RoleDao roleDao(LdapTemplate ldapTemplate, GeorchestraGatewaySecurityConfigProperties config) {
RoleDaoImpl impl = new RoleDaoImpl();
@@ -101,6 +157,13 @@ RoleDao roleDao(LdapTemplate ldapTemplate, GeorchestraGatewaySecurityConfigPrope
return impl;
}
+ /**
+ * Creates an {@link OrgsDao} implementation for managing LDAP organizations.
+ *
+ * @param ldapTemplate the LDAP template for querying LDAP
+ * @param config the security configuration properties
+ * @return a configured {@link OrgsDaoImpl}
+ */
@Bean
OrgsDao orgsDao(LdapTemplate ldapTemplate, GeorchestraGatewaySecurityConfigProperties config) {
OrgsDaoImpl impl = new OrgsDaoImpl();
@@ -112,35 +175,33 @@ OrgsDao orgsDao(LdapTemplate ldapTemplate, GeorchestraGatewaySecurityConfigPrope
return impl;
}
+ /**
+ * Creates an {@link AccountDao} implementation for managing user accounts in
+ * LDAP.
+ *
+ * @param ldapTemplate the LDAP template for querying LDAP
+ * @param config the security configuration properties
+ * @return a configured {@link AccountDaoImpl}
+ */
@Bean
AccountDao accountDao(LdapTemplate ldapTemplate, GeorchestraGatewaySecurityConfigProperties config) {
ExtendedLdapConfig ldapConfig = config.extendedEnabled().get(0);
- String baseDn = ldapConfig.getBaseDn();
- String userSearchBaseDN = ldapConfig.getUsersRdn();
- String roleSearchBaseDN = ldapConfig.getRolesRdn();
-
- // we don't need a configuration property for this,
- // we don't allow pending users to log in. The LdapAuthenticationProvider won't
- // even look them up.
- final String pendingUsersSearchBaseDN = "ou=pendingusers";
-
AccountDaoImpl impl = new AccountDaoImpl(ldapTemplate);
- impl.setBasePath(baseDn);
- impl.setUserSearchBaseDN(userSearchBaseDN);
- impl.setRoleSearchBaseDN(roleSearchBaseDN);
- impl.setPendingUserSearchBaseDN(pendingUsersSearchBaseDN);
-
- String orgSearchBaseDN = ldapConfig.getOrgsRdn();
- requireNonNull(orgSearchBaseDN);
- impl.setOrgSearchBaseDN(orgSearchBaseDN);
-
- final String pendingOrgSearchBaseDN = "ou=pendingorgs";
- impl.setPendingOrgSearchBaseDN(pendingOrgSearchBaseDN);
-
+ impl.setBasePath(ldapConfig.getBaseDn());
+ impl.setUserSearchBaseDN(ldapConfig.getUsersRdn());
+ impl.setRoleSearchBaseDN(ldapConfig.getRolesRdn());
+ impl.setPendingUserSearchBaseDN("ou=pendingusers");
+ impl.setOrgSearchBaseDN(requireNonNull(ldapConfig.getOrgsRdn()));
+ impl.setPendingOrgSearchBaseDN("ou=pendingorgs");
impl.init();
return impl;
}
+ /**
+ * Defines role protection rules for preventing modification of critical roles.
+ *
+ * @return a {@link RoleProtected} instance with predefined protected roles
+ */
@Bean
RoleProtected roleProtected() {
RoleProtected roleProtected = new RoleProtected();
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/LdapAccountsManager.java b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/LdapAccountsManager.java
index 72978696..e4961492 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/LdapAccountsManager.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/admin/ldap/LdapAccountsManager.java
@@ -49,19 +49,64 @@
import lombok.extern.slf4j.Slf4j;
/**
- * {@link AccountManager} that fetches and creates {@link GeorchestraUser}s from
- * the Georchestra extended LDAP service provided by an {@link AccountDao} and
- * {@link RoleDao}.
+ * Implementation of {@link AccountManager} that manages {@link GeorchestraUser}
+ * accounts through an extended LDAP service.
+ *
+ * This class provides methods for fetching, creating, and managing user
+ * accounts stored in LDAP via an {@link AccountDao} and {@link RoleDao}. If a
+ * user does not exist, it ensures the necessary roles and organizational
+ * memberships are created.
+ *
+ *
+ *
+ * Role names are automatically prefixed with {@code "ROLE_"} if missing.
+ *
+ *
+ * @see AccountManager
+ * @see AbstractAccountsManager
+ * @see DemultiplexingUsersApi
+ * @see AccountDao
+ * @see RoleDao
+ * @see OrgsDao
*/
@Slf4j(topic = "org.georchestra.gateway.accounts.admin.ldap")
class LdapAccountsManager extends AbstractAccountsManager {
+ /** Configuration properties for security-related settings. */
private final @NonNull GeorchestraGatewaySecurityConfigProperties georchestraGatewaySecurityConfigProperties;
+
+ /** DAO for managing user accounts in LDAP. */
private final @NonNull AccountDao accountDao;
+
+ /** DAO for managing roles and permissions in LDAP. */
private final @NonNull RoleDao roleDao;
+
+ /** DAO for managing organizations in LDAP. */
private final @NonNull OrgsDao orgsDao;
+
+ /** API for resolving users based on OAuth2 credentials. */
private final @NonNull DemultiplexingUsersApi demultiplexingUsersApi;
+ /**
+ * Constructs an instance of {@code LdapAccountsManager}.
+ *
+ * @param eventPublisher the application event
+ * publisher used for
+ * publishing account-related
+ * events
+ * @param accountDao the DAO responsible for
+ * managing user accounts in
+ * LDAP
+ * @param roleDao the DAO responsible for
+ * managing roles in LDAP
+ * @param orgsDao the DAO responsible for
+ * managing organizations in
+ * LDAP
+ * @param demultiplexingUsersApi the API used for resolving
+ * users by OAuth2 credentials
+ * @param georchestraGatewaySecurityConfigProperties configuration properties
+ * for security settings
+ */
public LdapAccountsManager(ApplicationEventPublisher eventPublisher, AccountDao accountDao, RoleDao roleDao,
OrgsDao orgsDao, DemultiplexingUsersApi demultiplexingUsersApi,
GeorchestraGatewaySecurityConfigProperties georchestraGatewaySecurityConfigProperties) {
@@ -73,23 +118,77 @@ public LdapAccountsManager(ApplicationEventPublisher eventPublisher, AccountDao
this.georchestraGatewaySecurityConfigProperties = georchestraGatewaySecurityConfigProperties;
}
+ /**
+ * Retrieves a stored user based on their OAuth2 provider and unique identifier.
+ *
+ * This method queries the {@link DemultiplexingUsersApi} for a user with the
+ * given OAuth2 provider and unique identifier. If found, the user's roles are
+ * normalized to ensure they are properly prefixed.
+ *
+ *
+ * @param oAuth2Provider the OAuth2 provider (e.g., Google, GitHub)
+ * @param oAuth2Uid the unique identifier assigned by the OAuth2 provider
+ * @return an {@link Optional} containing the user if found, otherwise empty
+ */
@Override
protected Optional findByOAuth2Uid(@NonNull String oAuth2Provider, @NonNull String oAuth2Uid) {
return demultiplexingUsersApi.findByOAuth2Uid(oAuth2Provider, oAuth2Uid).map(this::ensureRolesPrefixed);
}
+ /**
+ * Retrieves a stored user based on their username.
+ *
+ * This method queries the {@link DemultiplexingUsersApi} for a user with the
+ * given username. If found, the user's roles are normalized to ensure they are
+ * properly prefixed.
+ *
+ *
+ * @param username the username to search for
+ * @return an {@link Optional} containing the user if found, otherwise empty
+ */
@Override
protected Optional findByUsername(@NonNull String username) {
return demultiplexingUsersApi.findByUsername(username).map(this::ensureRolesPrefixed);
}
+ /**
+ * Ensures all roles assigned to a user are prefixed with {@code "ROLE_"}.
+ *
+ * If a role does not start with "ROLE_", this method adds the prefix. This
+ * normalization ensures consistency when handling role-based access.
+ *
+ *
+ * @param user the user whose roles need to be normalized
+ * @return the updated {@link GeorchestraUser} with properly formatted roles
+ */
private GeorchestraUser ensureRolesPrefixed(GeorchestraUser user) {
List roles = user.getRoles().stream().filter(Objects::nonNull)
- .map(r -> r.startsWith("ROLE_") ? r : "ROLE_" + r).toList();
- user.setRoles(new ArrayList<>(roles));
+ .map(r -> r.startsWith("ROLE_") ? r : "ROLE_" + r).toList(); // Converts to an immutable list
+ user.setRoles(new ArrayList<>(roles)); // Ensures mutability
return user;
}
+ /**
+ * Creates a new user in the LDAP repository if one does not already exist.
+ *
+ * This method first attempts to insert the user into LDAP. If an error occurs
+ * due to duplicate emails or usernames, appropriate exceptions are thrown.
+ *
+ *
+ * If the user is successfully inserted, their organization is ensured to exist.
+ * If an error occurs while managing the organization, the user account creation
+ * is rolled back.
+ *
+ *
+ * Finally, roles are assigned to the user to ensure correct access levels.
+ *
+ *
+ * @param mapped the user to create
+ * @throws DuplicatedEmailFoundException if a user with the same email
+ * already exists
+ * @throws DuplicatedUsernameFoundException if a user with the same username
+ * already exists
+ */
@Override
protected void createInternal(GeorchestraUser mapped) throws DuplicatedEmailFoundException {
Account newAccount = mapToAccountBrief(mapped);
@@ -115,6 +214,12 @@ protected void createInternal(GeorchestraUser mapped) throws DuplicatedEmailFoun
ensureRolesExist(mapped, newAccount);
}
+ /**
+ * Ensures all roles assigned to a user are prefixed with {@code "ROLE_"}.
+ *
+ * @param user the user whose roles need to be normalized
+ * @return the updated user with properly formatted roles
+ */
private void ensureRolesExist(GeorchestraUser mapped, Account newAccount) {
try {// account created, add roles
if (!mapped.getRoles().contains("ROLE_USER")) {
@@ -135,6 +240,11 @@ private void ensureRolesExist(GeorchestraUser mapped, Account newAccount) {
}
}
+ /**
+ * Ensures the organization associated with a user exists in LDAP.
+ *
+ * @param newAccount the account whose organization needs verification
+ */
private void ensureRoleExists(String role) throws DataServiceException {
try {
roleDao.findByCommonName(role);
@@ -147,6 +257,20 @@ private void ensureRoleExists(String role) throws DataServiceException {
}
}
+ /**
+ * Maps a {@link GeorchestraUser} to a brief {@link Account} representation for
+ * LDAP storage.
+ *
+ * This method extracts key user details such as username, email, and
+ * organization, and constructs an {@link Account} object suitable for insertion
+ * into LDAP. The generated account is marked as non-pending and assigned a
+ * default organization if none is provided.
+ *
+ *
+ * @param preAuth the pre-authenticated {@link GeorchestraUser} containing user
+ * details
+ * @return a newly created {@link Account} object with mapped attributes
+ */
private Account mapToAccountBrief(@NonNull GeorchestraUser preAuth) {
String username = preAuth.getUsername();
String email = preAuth.getEmail();
@@ -183,6 +307,12 @@ private void ensureOrgExists(@NonNull Account newAccount) {
}
}
+ /**
+ * Creates an organization and assigns the user to it.
+ *
+ * @param newAccount the user account to add to the new organization
+ * @param orgId the identifier of the organization
+ */
private void createOrgAndAddAccount(Account newAccount, final String orgId) {
try {
log.info("Org {} does not exist, trying to create it", orgId);
@@ -200,6 +330,13 @@ private void addAccountToOrg(Account newAccount, Org org) {
orgsDao.update(org);
}
+ /**
+ * Finds an organization by its identifier.
+ *
+ * @param orgId the identifier of the organization
+ * @return an {@link Optional} containing the organization if found, otherwise
+ * empty
+ */
private Optional findOrg(String orgId) {
try {
return Optional.of(orgsDao.findByCommonName(orgId));
@@ -208,6 +345,11 @@ private Optional findOrg(String orgId) {
}
}
+ /**
+ * Rolls back user creation if an error occurs.
+ *
+ * @param newAccount the user account to remove from LDAP
+ */
private void rollbackAccount(Account newAccount) {
try {// roll-back account
accountDao.delete(newAccount);
@@ -216,6 +358,9 @@ private void rollbackAccount(Account newAccount) {
}
}
+ /**
+ * Factory method to create a new org with the given id and return it
+ */
private Org newOrg(final String orgId) {
Org org = new Org();
org.setId(orgId);
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqAccountCreatedEventSender.java b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqAccountCreatedEventSender.java
index 06ddccee..44bd6f2f 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqAccountCreatedEventSender.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqAccountCreatedEventSender.java
@@ -27,26 +27,48 @@
import org.springframework.context.event.EventListener;
/**
- * Service bean that listens to {@link AccountCreated} events and publish a
- * distributed event through rabbitmq to the {@literal OAUTH2-ACCOUNT-CREATION}
+ * A service bean that listens for {@link AccountCreated} events and publishes a
+ * distributed event through RabbitMQ to the {@literal OAUTH2-ACCOUNT-CREATION}
* queue.
+ *
+ * This class is responsible for notifying other services when a new user
+ * account is created via OAuth2 authentication. It transforms the event data
+ * into a JSON message and sends it to the configured RabbitMQ routing key.
+ *
+ *
+ * @see AccountCreated
+ * @see AmqpTemplate
*/
-
public class RabbitmqAccountCreatedEventSender {
+ /** The RabbitMQ queue name for OAuth2 account creation events. */
public static final String OAUTH2_ACCOUNT_CREATION = "OAUTH2-ACCOUNT-CREATION";
- private AmqpTemplate eventTemplate;
+ /** The AMQP template for sending messages to the RabbitMQ exchange. */
+ private final AmqpTemplate eventTemplate;
+ /**
+ * Constructs a new {@code RabbitmqAccountCreatedEventSender}.
+ *
+ * @param eventTemplate the AMQP template used for sending messages
+ */
public RabbitmqAccountCreatedEventSender(AmqpTemplate eventTemplate) {
this.eventTemplate = eventTemplate;
}
+ /**
+ * Handles {@link AccountCreated} events and sends a message to the RabbitMQ
+ * queue if the new account was created via an OAuth2 provider.
+ *
+ * @param event the {@link AccountCreated} event containing user details
+ */
@EventListener
public void on(AccountCreated event) {
GeorchestraUser user = event.getUser();
final String oAuth2Provider = user.getOAuth2Provider();
- if (null != oAuth2Provider) {
+
+ // Only send events for OAuth2-authenticated users
+ if (oAuth2Provider != null) {
String fullName = user.getFirstName() + " " + user.getLastName();
String localUid = user.getUsername();
String email = user.getEmail();
@@ -56,6 +78,38 @@ public void on(AccountCreated event) {
}
}
+ /**
+ * Sends a message to RabbitMQ indicating that a new OAuth2 user account has
+ * been created.
+ *
+ * This method constructs a JSON object containing user details and publishes it
+ * to the RabbitMQ exchange with the routing key {@code routing-gateway}.
+ *
+ *
+ * @param fullName the full name of the user
+ * @param localUid the local username assigned to the user
+ * @param email the email address of the user
+ * @param organization the organization to which the user belongs
+ * @param providerName the name of the OAuth2 provider (e.g., Google, GitHub)
+ * @param providerUid the unique identifier assigned by the OAuth2 provider
+ */
public void sendNewOAuthAccountMessage(String fullName, String localUid, String email, String organization,
String providerName, String providerUid) {
JSONObject jsonObj = new JSONObject();
@@ -67,6 +121,8 @@ public void sendNewOAuthAccountMessage(String fullName, String localUid, String
jsonObj.put("organization", organization);
jsonObj.put("providerName", providerName);
jsonObj.put("providerUid", providerUid);
- eventTemplate.convertAndSend("routing-gateway", jsonObj.toString());// send
+
+ // Publish the message to the RabbitMQ queue
+ eventTemplate.convertAndSend("routing-gateway", jsonObj.toString());
}
-}
\ No newline at end of file
+}
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfiguration.java
index a1fa9322..9208646b 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfiguration.java
@@ -29,29 +29,58 @@
import org.springframework.context.annotation.ImportResource;
/**
- * {@link Configuration @Configuration} to enable sending events over rabbitmq *
+ * Configures RabbitMQ event handling for geOrchestra account creation events.
*
- * When an account is created in geOrchestra's LDAP in response to a
- * pre-authenticated or OIDC successful authentication, an
- * {@link AccountCreated} event will be catch up and sent over the wire.
- *
+ * This configuration enables the system to send events via RabbitMQ when an
+ * account is created in geOrchestra's LDAP in response to pre-authenticated or
+ * OpenID Connect (OIDC) authentication.
+ *
+ *
+ * When an {@link AccountCreated} event is published, it is intercepted and
+ * forwarded to the RabbitMQ event queue.
+ *
+ *
+ *
+ * This configuration also imports RabbitMQ-related XML context files:
+ *
+ *
+ *
+ * @see AccountCreated
* @see RabbitmqEventsConfigurationProperties
- *
*/
@Configuration
@EnableConfigurationProperties(RabbitmqEventsConfigurationProperties.class)
@ImportResource({ "classpath:rabbit-listener-context.xml", "classpath:rabbit-sender-context.xml" })
public class RabbitmqEventsConfiguration {
+ /**
+ * Defines the RabbitMQ event sender for publishing account creation events.
+ *
+ * @param eventTemplate the RabbitMQ {@link RabbitTemplate} used for message
+ * publishing
+ * @return an instance of {@link RabbitmqAccountCreatedEventSender}
+ */
@Bean
RabbitmqAccountCreatedEventSender eventsSender(@Qualifier("eventTemplate") RabbitTemplate eventTemplate) {
return new RabbitmqAccountCreatedEventSender(eventTemplate);
}
+ /**
+ * Configures a RabbitMQ connection factory.
+ *
+ * This method initializes a {@link CachingConnectionFactory} using the RabbitMQ
+ * connection properties defined in
+ * {@link RabbitmqEventsConfigurationProperties}.
+ *
+ *
+ * @param config the RabbitMQ configuration properties
+ * @return a configured {@link CachingConnectionFactory} instance
+ */
@Bean
- org.springframework.amqp.rabbit.connection.CachingConnectionFactory connectionFactory(
- RabbitmqEventsConfigurationProperties config) {
-
+ CachingConnectionFactory connectionFactory(RabbitmqEventsConfigurationProperties config) {
com.rabbitmq.client.ConnectionFactory fac = new com.rabbitmq.client.ConnectionFactory();
fac.setHost(config.getHost());
fac.setPort(config.getPort());
@@ -61,9 +90,18 @@ org.springframework.amqp.rabbit.connection.CachingConnectionFactory connectionFa
return new CachingConnectionFactory(fac);
}
+ /**
+ * Configures a health indicator for monitoring the RabbitMQ connection status.
+ *
+ * This health indicator integrates with Spring Boot Actuator, allowing
+ * real-time monitoring of the RabbitMQ connection through health endpoints.
+ *
+ *
+ * @param eventTemplate the RabbitMQ template used for event communication
+ * @return a configured {@link RabbitHealthIndicator}
+ */
@Bean
RabbitHealthIndicator rabbitHealthIndicator(@Qualifier("eventTemplate") RabbitTemplate eventTemplate) {
return new RabbitHealthIndicator(eventTemplate);
}
-
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfigurationProperties.java b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfigurationProperties.java
index 63c5f776..cf30bef6 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfigurationProperties.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsConfigurationProperties.java
@@ -25,8 +25,37 @@
import lombok.Generated;
/**
- * Configuration properties to enable rabbit-mq event dispatching of accounts
- * created
+ * Configuration properties for RabbitMQ event dispatching related to account
+ * creation.
+ *
+ * These properties define how geOrchestra should publish events to RabbitMQ
+ * when a new LDAP account is created following a user's first successful login
+ * via OAuth2 authentication.
+ *
+ *
+ * The properties are prefixed with
+ * {@code georchestra.gateway.security.events.rabbitmq} and can be configured in
+ * the application's configuration file (e.g., {@code application.yml}).
+ *
+ *
+ * @see org.springframework.boot.context.properties.ConfigurationProperties
*/
@Data
@Generated
@@ -34,28 +63,41 @@
@ConfigurationProperties(prefix = RabbitmqEventsConfigurationProperties.PREFIX)
public class RabbitmqEventsConfigurationProperties {
+ /** The prefix for all RabbitMQ-related configuration properties. */
public static final String PREFIX = "georchestra.gateway.security.events.rabbitmq";
+
+ /** The configuration key to enable or disable RabbitMQ event dispatching. */
public static final String ENABLED = PREFIX + ".enabled";
/**
- * Whether rabbit-mq events should be sent when an LDAP account was created upon
- * a first successful login through OAuth2
+ * Whether RabbitMQ events should be sent when an LDAP account is created
+ * following a user's first successful login via OAuth2 authentication.
+ *
+ * Default: {@code false}.
+ *
*/
private boolean enabled;
+
/**
- * The rabbit-mq host name
+ * The hostname of the RabbitMQ server.
*/
private String host;
+
/**
- * The rabbit-mq host port number
+ * The port number of the RabbitMQ server.
+ *
*/
private int port;
+
/**
- * The rabbit-mq authentication user
+ * The username used for authentication with the RabbitMQ server.
*/
private String user;
+
/**
- * The rabbit-mq authentication password
+ * The password used for authentication with the RabbitMQ server.
*/
private String password;
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsListener.java b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsListener.java
index 251664b7..30ff3cb7 100644
--- a/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsListener.java
+++ b/gateway/src/main/java/org/georchestra/gateway/accounts/events/rabbitmq/RabbitmqEventsListener.java
@@ -30,33 +30,69 @@
import lombok.extern.slf4j.Slf4j;
+/**
+ * Listens for messages from RabbitMQ and processes received events.
+ *
+ * This listener processes incoming messages related to OAuth2 account creation
+ * events. It ensures that duplicate messages are not logged more than once by
+ * maintaining a synchronized set of processed message UIDs.
+ *
+ *
+ *
+ * If an error occurs while processing a message, it is logged and silently
+ * discarded.
+ *
+ */
@Slf4j
public class RabbitmqEventsListener implements MessageListener {
+ /**
+ * The subject indicating that an OAuth2 account creation event has been
+ * received.
+ */
public static final String OAUTH2_ACCOUNT_CREATION_RECEIVED = "OAUTH2-ACCOUNT-CREATION-RECEIVED";
- private static Set synReceivedMessageUid = Collections.synchronizedSet(new HashSet());
+ /**
+ * A synchronized set to track processed message UIDs and prevent duplicate
+ * processing.
+ */
+ private static final Set synReceivedMessageUid = Collections.synchronizedSet(new HashSet<>());
+ /**
+ * Processes an incoming RabbitMQ message.
+ *
+ * If the message contains a subject matching
+ * {@code OAUTH2-ACCOUNT-CREATION-RECEIVED} and has not already been processed,
+ * it logs the message content.
+ *
+ *
+ * @param message the incoming RabbitMQ message
+ */
+ @Override
public void onMessage(Message message) {
try {
String messageBody = new String(message.getBody());
JSONObject jsonObj = new JSONObject(messageBody);
String uid = jsonObj.getString("uid");
String subject = jsonObj.getString("subject");
- if (subject.equals(OAUTH2_ACCOUNT_CREATION_RECEIVED)
- && !synReceivedMessageUid.stream().anyMatch(s -> s.equals(uid))) {
+
+ if (subject.equals(OAUTH2_ACCOUNT_CREATION_RECEIVED) && !synReceivedMessageUid.contains(uid)) {
String msg = jsonObj.getString("msg");
synReceivedMessageUid.add(uid);
log.info(msg);
}
-
} catch (Exception e) {
- log.error("Exception caught when evaluating a message from RabbitMq, it will be silently discarded.", e);
+ log.error("Exception caught when evaluating a message from RabbitMQ. It will be silently discarded.", e);
}
}
+ /**
+ * Returns the set of received message UIDs for testing purposes.
+ *
+ * @return an unmodifiable view of the received message UIDs
+ */
@VisibleForTesting
public static Set getSynReceivedMessageUid() {
- return synReceivedMessageUid;
+ return Collections.unmodifiableSet(synReceivedMessageUid);
}
-}
\ No newline at end of file
+}
diff --git a/gateway/src/main/java/org/georchestra/gateway/app/GeorchestraGatewayApplication.java b/gateway/src/main/java/org/georchestra/gateway/app/GeorchestraGatewayApplication.java
index cac78fe4..2a4171d1 100644
--- a/gateway/src/main/java/org/georchestra/gateway/app/GeorchestraGatewayApplication.java
+++ b/gateway/src/main/java/org/georchestra/gateway/app/GeorchestraGatewayApplication.java
@@ -38,21 +38,61 @@
import lombok.extern.slf4j.Slf4j;
+/**
+ * Main application class for the geOrchestra Gateway.
+ *
+ * This class initializes the Spring Boot application, manages application-wide
+ * configuration, and sets up essential beans and event listeners.
+ *
+ *
+ *
+ * Most additional functionalities, such as security, routing, and external
+ * integrations, are contributed via Spring Boot
+ * {@link org.springframework.boot.autoconfigure.AutoConfiguration} classes.
+ * These auto-configurations enable features dynamically based on the
+ * application’s dependencies and configuration properties.
+ *
+ *
+ *
+ * The only explicitly defined controllers in this package are those required
+ * for gateway-specific endpoints, such as authentication entry points or
+ * request introspection. All other functionalities are provided through
+ * auto-configuration.
+ *
+ */
@Slf4j
@SpringBootApplication
@EnableConfigurationProperties(GeorchestraGatewaySecurityConfigProperties.class)
public class GeorchestraGatewayApplication {
+ /**
+ * The route locator for retrieving gateway routes. Only used for reporting the
+ * number of configured routes at startup
+ */
private @Autowired RouteLocator routeLocator;
+
+ /** The basename for message resources, configurable via properties. */
private @Value("${spring.messages.basename:}") String messagesBasename;
+ /**
+ * Entry point for the geOrchestra Gateway application.
+ *
+ * @param args command-line arguments
+ */
public static void main(String[] args) {
SpringApplication.run(GeorchestraGatewayApplication.class, args);
}
/**
- * REVISIT: why do we need to define this bean in the Application class and not
- * in a configuration that depends on whether rabbit is enabled?
+ * Configures a {@link MessageSource} bean for loading internationalized
+ * messages.
+ *
+ * This method sets up a {@link ReloadableResourceBundleMessageSource} that
+ * loads messages from {@code classpath:messages/login} and additional basenames
+ * configured via {@code spring.messages.basename}.
+ *
+ * This method retrieves environment properties, including the data directory,
+ * instance ID, available CPU cores, and memory usage, and logs them for
+ * debugging. It also counts the number of registered routes.
+ *
+ *
+ * @param event the application ready event
+ */
@EventListener(ApplicationReadyEvent.class)
- public void onApplicationReady(ApplicationReadyEvent e) {
- Environment env = e.getApplicationContext().getEnvironment();
+ public void onApplicationReady(ApplicationReadyEvent event) {
+ Environment env = event.getApplicationContext().getEnvironment();
String datadir = env.getProperty("georchestra.datadir");
- if (null != datadir) {
+ if (datadir != null) {
datadir = new File(datadir).getAbsolutePath();
}
String app = env.getProperty("spring.application.name");
@@ -81,8 +132,12 @@ public void onApplicationReady(ApplicationReadyEvent e) {
routeCount, instanceId, cpus, maxMem);
}
+ /**
+ * Retrieves the maximum memory allocated to the JVM and formats it in MB or GB.
+ *
+ * @return the formatted maximum memory value
+ */
private String getMaxMem() {
- String maxMem;
DataSize maxMemBytes = DataSize.ofBytes(Runtime.getRuntime().maxMemory());
double value = maxMemBytes.toKilobytes() / 1024d;
String unit = "MB";
@@ -90,7 +145,6 @@ private String getMaxMem() {
value = value / 1024d;
unit = "GB";
}
- maxMem = String.format("%.2f %s", value, unit);
- return maxMem;
+ return String.format("%.2f %s", value, unit);
}
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/app/LoginLogoutController.java b/gateway/src/main/java/org/georchestra/gateway/app/LoginLogoutController.java
index 89d2042c..4aa1e6e0 100644
--- a/gateway/src/main/java/org/georchestra/gateway/app/LoginLogoutController.java
+++ b/gateway/src/main/java/org/georchestra/gateway/app/LoginLogoutController.java
@@ -10,14 +10,21 @@
*
* geOrchestra is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
* more details.
*
* You should have received a copy of the GNU General Public License along with
- * geOrchestra. If not, see .
+ * geOrchestra. If not, see .
*/
package org.georchestra.gateway.app;
+import java.nio.file.Paths;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+import javax.annotation.PostConstruct;
+
import org.apache.commons.lang3.tuple.Pair;
import org.georchestra.gateway.security.GeorchestraGatewaySecurityConfigProperties;
import org.georchestra.gateway.security.GeorchestraGatewaySecurityConfigProperties.Server;
@@ -30,86 +37,155 @@
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
-import javax.annotation.PostConstruct;
-import java.nio.file.Paths;
-import java.util.HashMap;
-import java.util.Map;
-import java.util.Optional;
-
+/**
+ * Controller handling login and logout views for the geOrchestra gateway.
+ *
+ * This controller serves the login and logout pages, manages authentication
+ * options, and provides necessary attributes for rendering login-related
+ * templates.
+ *
+ *
+ *
+ * It supports authentication through:
+ *
+ *
LDAP (if enabled via configuration)
+ *
OAuth2 providers registered in Spring Security
+ *
Header-based authentication
+ *
+ *
+ */
// We have to use the @Controller annotation, not the @RestController one
// here, so that the login/logout page will go through the thymeleaf templating
// system.
@Controller
public class LoginLogoutController {
+ /** Configuration properties for gateway security, including LDAP settings. */
private @Autowired(required = false) GeorchestraGatewaySecurityConfigProperties georchestraGatewaySecurityConfigProperties;
+ /** Whether LDAP authentication is enabled. */
private boolean ldapEnabled;
+ /** OAuth2 client configuration, if available. */
private @Autowired(required = false) OAuth2ClientProperties oauth2ClientConfig;
+
+ /** Whether header-based authentication is enabled. */
private @Value("${georchestra.gateway.headerEnabled:true}") boolean headerEnabled;
- // defined in georchestra datadir's default.properties
+ /** Path to the geOrchestra custom stylesheet, if configured. */
private @Value("${georchestraStylesheet:}") String georchestraStylesheet;
+
+ /** Whether to use the legacy geOrchestra header. */
private @Value("${useLegacyHeader:false}") boolean useLegacyHeader;
+
+ /** URL of the geOrchestra header component. */
private @Value("${headerUrl:/header/}") String headerUrl;
+
+ /** Path to the geOrchestra header configuration file. */
private @Value("${headerConfigFile:}") String headerConfigFile;
+
+ /** Height of the geOrchestra header in pixels. */
private @Value("${headerHeight:80}") int headerHeight;
+
+ /** URL of the logo displayed in the header. */
private @Value("${logoUrl:}") String logoUrl;
+
+ /** JavaScript file used to load the geOrchestra header. */
private @Value("${headerScript:https://cdn.jsdelivr.net/gh/georchestra/header@dist/header.js}") String headerScript;
+ /**
+ * Initializes authentication settings based on configuration properties.
+ *
+ * Determines whether LDAP authentication is enabled by checking the configured
+ * LDAP servers.
+ *
+ * This method sets necessary attributes for rendering the logout page.
+ *
+ *
+ * @param model the model for passing attributes to the view
+ * @return the name of the logout view template
+ */
@GetMapping(path = "/logout")
- public String logout(Model mdl) {
- setHeaderAttributes(mdl);
+ public String logout(Model model) {
+ setHeaderAttributes(model);
return "logout";
}
+ /**
+ * Handles the login page rendering and authentication flow.
+ *
+ * If only one OAuth2 provider is available and LDAP authentication is disabled,
+ * the user is automatically redirected to the provider’s authentication
+ * endpoint. Otherwise, the login page is rendered with available authentication
+ * options.
+ *
+ *
+ * @param allRequestParams request parameters, including authentication errors
+ * @param model the model for passing attributes to the view
+ * @return the login view name or a redirect to an authentication provider
+ */
@GetMapping(path = "/login")
- public String loginPage(@RequestParam Map allRequestParams, Model mdl) {
+ public String loginPage(@RequestParam Map allRequestParams, Model model) {
Map> oauth2LoginLinks = new HashMap<>();
- if (oauth2ClientConfig != null) {
- oauth2ClientConfig.getRegistration().forEach((k, v) -> {
- String clientName = Optional.ofNullable(v.getClientName()).orElse(k);
- String providerPath = Paths.get("login/img/", k + ".png").toString();
+ // Populate OAuth2 login links
+ if (oauth2ClientConfig != null) {
+ oauth2ClientConfig.getRegistration().forEach((key, value) -> {
+ String clientName = Optional.ofNullable(value.getClientName()).orElse(key);
+ String providerPath = Paths.get("login/img/", key + ".png").toString();
String logo = new ClassPathResource("static/" + providerPath).exists() ? providerPath
: "login/img/default.png";
- oauth2LoginLinks.put("/oauth2/authorization/" + k, Pair.of(clientName, logo));
+ oauth2LoginLinks.put("/oauth2/authorization/" + key, Pair.of(clientName, logo));
});
}
+ // Auto-redirect if only one OAuth2 provider is available and LDAP is disabled
if (oauth2LoginLinks.size() == 1 && !ldapEnabled) {
return "redirect:" + oauth2LoginLinks.keySet().stream().findFirst().orElseThrow();
}
- setHeaderAttributes(mdl);
- mdl.addAttribute("ldapEnabled", ldapEnabled);
- mdl.addAttribute("oauth2LoginLinks", oauth2LoginLinks);
- boolean expired = "expired_password".equals(allRequestParams.get("error"));
- mdl.addAttribute("passwordExpired", expired);
- boolean invalidCredentials = "invalid_credentials".equals(allRequestParams.get("error"));
- mdl.addAttribute("invalidCredentials", invalidCredentials);
- boolean duplicateAccount = "duplicate_account".equals(allRequestParams.get("error"));
- mdl.addAttribute("duplicateAccount", duplicateAccount);
+ // Set model attributes for login page rendering
+ setHeaderAttributes(model);
+ model.addAttribute("ldapEnabled", ldapEnabled);
+ model.addAttribute("oauth2LoginLinks", oauth2LoginLinks);
+
+ // Handle authentication error messages
+ model.addAttribute("passwordExpired", "expired_password".equals(allRequestParams.get("error")));
+ model.addAttribute("invalidCredentials", "invalid_credentials".equals(allRequestParams.get("error")));
+ model.addAttribute("duplicateAccount", "duplicate_account".equals(allRequestParams.get("error")));
+
return "login";
}
- private void setHeaderAttributes(Model mdl) {
- mdl.addAttribute("georchestraStylesheet", georchestraStylesheet);
- mdl.addAttribute("useLegacyHeader", useLegacyHeader);
- mdl.addAttribute("headerUrl", headerUrl);
- mdl.addAttribute("headerHeight", headerHeight);
- mdl.addAttribute("logoUrl", logoUrl);
- mdl.addAttribute("headerConfigFile", headerConfigFile);
- mdl.addAttribute("headerEnabled", headerEnabled);
- mdl.addAttribute("headerScript", headerScript);
+ /**
+ * Sets header-related attributes in the model for rendering views.
+ *
+ * These attributes control the appearance and behavior of the geOrchestra
+ * header displayed on the login and logout pages.
+ *
+ *
+ * @param model the model where attributes will be added
+ */
+ private void setHeaderAttributes(Model model) {
+ model.addAttribute("georchestraStylesheet", georchestraStylesheet);
+ model.addAttribute("useLegacyHeader", useLegacyHeader);
+ model.addAttribute("headerUrl", headerUrl);
+ model.addAttribute("headerHeight", headerHeight);
+ model.addAttribute("logoUrl", logoUrl);
+ model.addAttribute("headerConfigFile", headerConfigFile);
+ model.addAttribute("headerEnabled", headerEnabled);
+ model.addAttribute("headerScript", headerScript);
}
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/app/StyleConfigController.java b/gateway/src/main/java/org/georchestra/gateway/app/StyleConfigController.java
index 08ce6d56..2ded201a 100644
--- a/gateway/src/main/java/org/georchestra/gateway/app/StyleConfigController.java
+++ b/gateway/src/main/java/org/georchestra/gateway/app/StyleConfigController.java
@@ -10,11 +10,11 @@
*
* geOrchestra is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
* more details.
*
* You should have received a copy of the GNU General Public License along with
- * geOrchestra. If not, see .
+ * geOrchestra. If not, see .
*/
package org.georchestra.gateway.app;
@@ -28,17 +28,31 @@
import reactor.core.publisher.Mono;
+/**
+ * Controller that provides the geOrchestra UI style configuration.
+ *
+ * This controller exposes an endpoint that returns style-related settings, such
+ * as the stylesheet URL and logo URL, used for customizing the user interface.
+ * The values are loaded from the geOrchestra data directory's
+ * {@code default.properties}.
+ *
+ */
@RestController
public class StyleConfigController {
- private String georchestraStylesheet;
- private String logoUrl;
+ /** The URL of the custom stylesheet for geOrchestra, if defined. */
+ private final String georchestraStylesheet;
+
+ /** The URL of the logo used in geOrchestra, if defined. */
+ private final String logoUrl;
/**
- * @param georchestraStylesheet defined in georchestra datadir's
- * default.properties
- * @param logoUrl defined in georchestra datadir's
- * default.properties
+ * Constructs a {@code StyleConfigController} with style configuration values.
+ *
+ * @param georchestraStylesheet the URL of the geOrchestra stylesheet, usually
+ * loaded from {@code default.properties}
+ * @param logoUrl the URL of the geOrchestra logo, usually loaded
+ * from {@code default.properties}
*/
public StyleConfigController(@Value("${georchestraStylesheet:}") String georchestraStylesheet,
@Value("${logoUrl:}") String logoUrl) {
@@ -46,13 +60,32 @@ public StyleConfigController(@Value("${georchestraStylesheet:}") String georches
this.logoUrl = logoUrl;
}
+ /**
+ * Provides the geOrchestra UI style configuration as a JSON object.
+ *
+ * This endpoint returns a JSON response containing the configured stylesheet
+ * URL and logo URL.
+ *
+ *
+ * @return a reactive {@link Mono} containing a map with style configuration
+ * properties
+ */
@GetMapping(path = "/style-config", produces = MediaType.APPLICATION_JSON_VALUE)
public Mono> styleConfig() {
-
- Map ret = new LinkedHashMap<>();
- ret.put("stylesheet", georchestraStylesheet);
- ret.put("logo", logoUrl);
- return Mono.just(ret);
-
+ Map config = new LinkedHashMap<>();
+ config.put("stylesheet", georchestraStylesheet);
+ config.put("logo", logoUrl);
+ return Mono.just(config);
}
-}
+}
\ No newline at end of file
diff --git a/gateway/src/main/java/org/georchestra/gateway/app/WhoamiController.java b/gateway/src/main/java/org/georchestra/gateway/app/WhoamiController.java
index f0b53707..d7fe6926 100644
--- a/gateway/src/main/java/org/georchestra/gateway/app/WhoamiController.java
+++ b/gateway/src/main/java/org/georchestra/gateway/app/WhoamiController.java
@@ -10,11 +10,11 @@
*
* geOrchestra is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
* more details.
*
* You should have received a copy of the GNU General Public License along with
- * geOrchestra. If not, see .
+ * geOrchestra. If not, see .
*/
package org.georchestra.gateway.app;
@@ -33,15 +33,65 @@
import reactor.core.publisher.Mono;
+/**
+ * Controller that provides user authentication details.
+ *
+ * This controller exposes an endpoint to return information about the currently
+ * authenticated user, including their mapped {@link GeorchestraUser} details.
+ *
+ */
@RestController
public class WhoamiController {
- private GeorchestraUserMapper userMapper;
+ /**
+ * The user mapper responsible for resolving authentication details into a
+ * {@link GeorchestraUser}.
+ */
+ private final GeorchestraUserMapper userMapper;
+ /**
+ * Constructs a {@code WhoamiController} with a user mapper for authentication
+ * resolution.
+ *
+ * @param userMapper the {@link GeorchestraUserMapper} used to resolve
+ * authentication details
+ */
public WhoamiController(GeorchestraUserMapper userMapper) {
this.userMapper = userMapper;
}
+ /**
+ * Returns details about the currently authenticated user.
+ *
+ * This endpoint returns a JSON response containing the mapped
+ * {@link GeorchestraUser} object and the raw {@link Authentication} object. If
+ * the user is not authenticated, both values will be {@code null}.
+ *
+ *
+ * @param principal the currently authenticated user, if available
+ * @param exchange the current web exchange request context
+ * @return a reactive {@link Mono} containing a map with user authentication
+ * details
+ */
@GetMapping(path = "/whoami", produces = MediaType.APPLICATION_JSON_VALUE)
public Mono> whoami(Authentication principal, ServerWebExchange exchange) {
GeorchestraUser user;
@@ -50,7 +100,6 @@ public Mono> whoami(Authentication principal, ServerWebExcha
} catch (DuplicatedEmailFoundException e) {
user = null;
}
-
Map ret = new LinkedHashMap<>();
ret.put("GeorchestraUser", user);
if (principal == null) {
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnCreateLdapAccounts.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnCreateLdapAccounts.java
index be2ba2c1..7573479f 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnCreateLdapAccounts.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnCreateLdapAccounts.java
@@ -28,8 +28,26 @@
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
/**
+ * Meta-annotation that enables a bean only if LDAP account creation is allowed.
+ *
+ * This annotation is used to conditionally enable beans when both of the
+ * following conditions are met:
+ *
+ *
The default geOrchestra LDAP integration is enabled (via
+ * {@link ConditionalOnDefaultGeorchestraLdapEnabled}).
+ *
The property
+ * {@code georchestra.gateway.security.create-non-existing-users-in-l-d-a-p} is
+ * set to {@code true}.
+ *
+ *
+ *
+ *
+ * If the property is missing or explicitly set to {@code false}, the annotated
+ * bean will not be created.
+ *
*
* @see ConditionalOnDefaultGeorchestraLdapEnabled
+ * @see ConditionalOnProperty
*/
@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnDefaultGeorchestraLdapEnabled.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnDefaultGeorchestraLdapEnabled.java
index 579a9bec..b65a6a41 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnDefaultGeorchestraLdapEnabled.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/ConditionalOnDefaultGeorchestraLdapEnabled.java
@@ -29,7 +29,26 @@
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
/**
+ * Meta-annotation that enables a bean only if the default geOrchestra LDAP
+ * integration is enabled.
+ *
+ * This annotation is used to conditionally activate beans when both of the
+ * following conditions are met:
+ *
+ *
LDAP is enabled for geOrchestra (via
+ * {@link ConditionalOnLdapEnabled}).
+ *
The property {@code georchestra.gateway.security.ldap.default.enabled} is
+ * set to {@code true}.
+ *
+ *
*
+ *
+ * If the property is missing or explicitly set to {@code false}, the annotated
+ * bean will not be created.
+ *
+ *
+ *
* @see ConditionalOnCreateLdapAccounts
* @see GeorchestraLdapAccountManagementConfiguration
+ * @see ExtendedLdapAuthenticationConfiguration
*/
@AutoConfiguration
@ConditionalOnCreateLdapAccounts
@@ -43,13 +68,21 @@
@RequiredArgsConstructor
public class GeorchestraLdapAccountsCreationAutoConfiguration {
+ /** The list of extended LDAP configurations required for account creation. */
@NonNull
private final List configs;
+ /**
+ * Ensures that an extended LDAP configuration is available.
+ *
+ * If no extended LDAP configurations are present, this method throws an
+ * {@link IllegalStateException} to prevent startup with invalid settings.
+ *
+ */
@PostConstruct
- void failIfNoExtendedLdapCongfigs() {
+ void failIfNoExtendedLdapConfigs() {
if (configs.isEmpty()) {
throw new IllegalStateException("LDAP account creation requires an extended LDAP configuration");
}
}
-}
\ No newline at end of file
+}
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/RabbitmqEventsAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/RabbitmqEventsAutoConfiguration.java
index e5c13399..834bc7f5 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/RabbitmqEventsAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/accounts/RabbitmqEventsAutoConfiguration.java
@@ -26,17 +26,33 @@
import org.springframework.context.annotation.Import;
/**
- * {@link AutoConfiguration @AutoConfiguration} to enable sending events over
- * rabbitmq when it is enabled through
- * {@literal georchestra.gateway.security.events.rabbitmq = true}.
+ * Auto-configuration for enabling RabbitMQ event dispatching when configured.
*
- * When an account is created in geOrchestra's LDAP in response to a
- * pre-authenticated or OIDC successful authentication, an
- * {@link AccountCreated} event will be catch up and sent over the wire.
- *
- *
+ * This configuration enables RabbitMQ integration when the following conditions
+ * are met:
+ *
+ *
LDAP account creation is enabled
+ * ({@link ConditionalOnCreateLdapAccounts}).
+ *
The property {@code georchestra.gateway.security.events.rabbitmq} is set
+ * to {@code true}.
+ *
+ *
+ *
+ *
+ * When a user account is created in geOrchestra's LDAP following a successful
+ * authentication via pre-authenticated headers or OIDC, an
+ * {@link AccountCreated} event is published. This event is then transmitted via
+ * RabbitMQ.
+ *
+ *
+ *
+ * This class imports {@link RabbitmqEventsConfiguration}, which defines the
+ * RabbitMQ message sender and event handling beans.
+ *
+ *
* @see ConditionalOnCreateLdapAccounts
* @see RabbitmqEventsConfiguration
+ * @see RabbitmqEventsConfigurationProperties
*/
@AutoConfiguration
@ConditionalOnCreateLdapAccounts
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/CustomErrorAttributes.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/CustomErrorAttributes.java
index b39e655c..8b8dc884 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/CustomErrorAttributes.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/CustomErrorAttributes.java
@@ -25,34 +25,78 @@
import org.springframework.boot.autoconfigure.web.reactive.error.ErrorWebFluxAutoConfiguration;
import org.springframework.boot.web.error.ErrorAttributeOptions;
import org.springframework.boot.web.reactive.error.DefaultErrorAttributes;
-import org.springframework.boot.web.reactive.error.ErrorAttributes;
import org.springframework.boot.web.reactive.error.ErrorWebExceptionHandler;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.reactive.function.server.ServerRequest;
/**
- * Maps connection exceptions to HTTP 503 status code instead of 500
+ * Custom error attributes that remap specific exceptions to appropriate HTTP
+ * status codes.
*
- * In the event that a route exists and the downstream service is not available,
- * usually the Gateway returns a 503 status code as expected.
+ * This class extends {@link DefaultErrorAttributes} to modify error responses
+ * in a Spring WebFlux application. It ensures that:
+ *
+ *
{@link UnknownHostException} and {@link ConnectException} return an HTTP
+ * 503 ({@link HttpStatus#SERVICE_UNAVAILABLE}) instead of the default HTTP
+ * 500.
+ *
{@link AccessDeniedException} results in an HTTP 403
+ * ({@link HttpStatus#FORBIDDEN}).
+ *
+ *
+ *
*
- * On a dynamic environment though, such as k8s and docker compose, the
- * underlying error results from a DNS lookup failure, and the default error is
- * 500 instead.
+ * In dynamic environments like Kubernetes and Docker Compose, service
+ * unavailability may manifest as DNS resolution failures, which would normally
+ * result in HTTP 500. This class ensures that such failures correctly return
+ * HTTP 503.
+ *
+ *
*
- * This {@link ErrorAttributes} overrides the {@link DefaultErrorAttributes}
- * configured in {@link ErrorWebFluxAutoConfiguration} and injected to the
- * {@link ErrorWebExceptionHandler}, and translates
- * {@link java.net.UnknownHostException} and {@link java.net.ConnectException}
- * to {@link HttpStatus#SERVICE_UNAVAILABLE}
+ * This class is injected into the {@link ErrorWebExceptionHandler} and replaces
+ * the default error handling provided by {@link ErrorWebFluxAutoConfiguration}.
+ *
+ *
+ * @see DefaultErrorAttributes
+ * @see ErrorWebFluxAutoConfiguration
+ * @see ErrorWebExceptionHandler
*/
public class CustomErrorAttributes extends DefaultErrorAttributes {
+ /**
+ * Overrides the default error attributes to remap specific exceptions to
+ * appropriate HTTP status codes.
+ *
+ * This method retrieves the original error attributes and modifies the status
+ * code for the following exceptions:
+ *
+ *
+ * @param request the server request that caused the error
+ * @param options options for error attribute filtering
+ * @return a modified map of error attributes with updated status codes
+ */
@Override
public Map getErrorAttributes(ServerRequest request, ErrorAttributeOptions options) {
Map attributes = super.getErrorAttributes(request, options);
Throwable error = super.getError(request);
+
if (error instanceof UnknownHostException || error instanceof ConnectException) {
attributes.put("status", HttpStatus.SERVICE_UNAVAILABLE.value());
attributes.put("error", HttpStatus.SERVICE_UNAVAILABLE.getReasonPhrase());
@@ -60,7 +104,7 @@ public Map getErrorAttributes(ServerRequest request, ErrorAttrib
attributes.put("status", HttpStatus.FORBIDDEN.value());
attributes.put("error", HttpStatus.FORBIDDEN.getReasonPhrase());
}
+
return attributes;
}
-
-}
\ No newline at end of file
+}
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/ErrorCustomizerAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/ErrorCustomizerAutoConfiguration.java
index 9da8bc46..d0de9f14 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/ErrorCustomizerAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/ErrorCustomizerAutoConfiguration.java
@@ -24,13 +24,40 @@
import org.springframework.context.annotation.Bean;
/**
- * Overrides the {@lin k DefaultErrorAttributes} configured in
- * {@link ErrorWebFluxAutoConfiguration} and injected to the
- * {@link ErrorWebExceptionHandler}
+ * Auto-configuration for customizing error handling in geOrchestra Gateway
+ *
+ * This configuration replaces the default error attributes provided by
+ * {@link ErrorWebFluxAutoConfiguration} with {@link CustomErrorAttributes},
+ * which modifies error responses for specific exceptions.
+ *
+ *
+ *
+ * This ensures that certain network-related failures (e.g., DNS resolution
+ * errors) return an HTTP 503 (Service Unavailable) instead of HTTP 500.
+ *
+ *
+ *
+ * The customized error attributes are injected into the
+ * {@link ErrorWebExceptionHandler}, affecting how errors are represented in the
+ * application's responses.
+ *
+ * This bean ensures that network-related exceptions and access control errors
+ * are properly mapped to HTTP 503 and HTTP 403 respectively.
+ *
+ *
+ * @return an instance of {@link CustomErrorAttributes} for handling errors
+ */
@Bean
CustomErrorAttributes customErrorAttributes() {
return new CustomErrorAttributes();
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/FiltersAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/FiltersAutoConfiguration.java
index b0d90661..4b6ea08d 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/FiltersAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/FiltersAutoConfiguration.java
@@ -35,6 +35,24 @@
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Import;
+/**
+ * Auto-configuration for geOrchestra gateway filters and predicates.
+ *
+ * This configuration registers custom filters and predicates that enhance
+ * Spring Cloud Gateway's request handling capabilities. It ensures that
+ * necessary filters are available before {@link GatewayAutoConfiguration} is
+ * loaded.
+ *
+ *
+ *
+ * This class also imports {@link HeaderFiltersConfiguration} and enables
+ * configuration properties via {@link GatewayConfigProperties}.
+ *
+ *
+ * @see GatewayAutoConfiguration
+ * @see HeaderFiltersConfiguration
+ * @see GatewayConfigProperties
+ */
@AutoConfiguration
@AutoConfigureBefore(GatewayAutoConfiguration.class)
@Import(HeaderFiltersConfiguration.class)
@@ -42,40 +60,71 @@
public class FiltersAutoConfiguration {
/**
- * {@link GlobalFilter} to {@link GeorchestraTargetConfig#setTarget save) the
- * matched Route's GeorchestraTargetConfig for each HTTP request-response
- * interaction before other filters are applied.
+ * Registers a {@link GlobalFilter} that resolves the target configuration for
+ * each incoming request.
+ *
+ * This filter extracts the matched route's {@link GeorchestraTargetConfig} and
+ * saves it for later processing in the request-response lifecycle.
+ *
+ *
+ * @param config the gateway configuration properties
+ * @return an instance of {@link ResolveTargetGlobalFilter}
*/
@Bean
ResolveTargetGlobalFilter resolveTargetWebFilter(GatewayConfigProperties config) {
return new ResolveTargetGlobalFilter(config);
}
+ /**
+ * Registers a gateway filter factory that processes login-related query
+ * parameters.
+ *
+ * @return an instance of {@link LoginParamRedirectGatewayFilterFactory}
+ */
@Bean
LoginParamRedirectGatewayFilterFactory loginParamRedirectGatewayFilterFactory() {
return new LoginParamRedirectGatewayFilterFactory();
}
/**
- * Custom gateway predicate factory to support matching by regular expressions
- * on both name and value of query parameters
+ * Registers a custom route predicate factory that allows matching query
+ * parameters based on regular expressions.
+ *
+ * @return an instance of {@link RegExpQueryRoutePredicateFactory}
*/
@Bean
RegExpQueryRoutePredicateFactory regExpQueryRoutePredicateFactory() {
return new RegExpQueryRoutePredicateFactory();
}
- /** Allows to enable routes only if a given spring profile is enabled */
+ /**
+ * Registers a gateway filter factory that enables or disables routes based on
+ * the active Spring profiles.
+ *
+ * @return an instance of {@link RouteProfileGatewayFilterFactory}
+ */
@Bean
RouteProfileGatewayFilterFactory routeProfileGatewayFilterFactory() {
return new RouteProfileGatewayFilterFactory();
}
+ /**
+ * Registers a gateway filter factory that strips the base path from incoming
+ * requests.
+ *
+ * @return an instance of {@link StripBasePathGatewayFilterFactory}
+ */
@Bean
StripBasePathGatewayFilterFactory stripBasePathGatewayFilterFactory() {
return new StripBasePathGatewayFilterFactory();
}
+ /**
+ * Registers a gateway filter factory that handles application-level errors
+ * gracefully.
+ *
+ * @return an instance of {@link ApplicationErrorGatewayFilterFactory}
+ */
@Bean
ApplicationErrorGatewayFilterFactory applicationErrorGatewayFilterFactory() {
return new ApplicationErrorGatewayFilterFactory();
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/RoutePredicateFactoriesAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/RoutePredicateFactoriesAutoConfiguration.java
index 8ee823fd..79ee635c 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/RoutePredicateFactoriesAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/app/RoutePredicateFactoriesAutoConfiguration.java
@@ -22,9 +22,27 @@
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.context.annotation.Bean;
+/**
+ * Auto-configuration for custom route predicate factories in geOrchestra
+ * Gateway.
+ *
+ * This configuration registers custom predicate factories that extend the
+ * routing capabilities of Spring Cloud Gateway.
+ *
+ */
@AutoConfiguration
public class RoutePredicateFactoriesAutoConfiguration {
+ /**
+ * Registers a route predicate factory that allows matching requests based on
+ * query parameters.
+ *
+ * This predicate enables routing decisions based on the presence and values of
+ * query parameters in incoming requests.
+ *
+ *
+ * @return an instance of {@link QueryParamRoutePredicateFactory}
+ */
@Bean
QueryParamRoutePredicateFactory queryParamRoutePredicateFactory() {
return new QueryParamRoutePredicateFactory();
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/AtLeastOneLdapDatasourceEnabledCondition.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/AtLeastOneLdapDatasourceEnabledCondition.java
index 384d4dd9..9e322479 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/AtLeastOneLdapDatasourceEnabledCondition.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/AtLeastOneLdapDatasourceEnabledCondition.java
@@ -43,17 +43,27 @@
import com.google.common.collect.Streams;
/**
- * {@link Condition} that matches if at least one LDAP config is enabled from
- * the externalized config properties
- * {@code georchestra.gateway.security.ldap..enabled}
- *
+ * {@link Condition} that matches if at least one LDAP configuration is enabled.
+ *
+ * This condition checks the externalized configuration properties:
+ * {@code georchestra.gateway.security.ldap..enabled}. If at least
+ * one LDAP configuration is enabled, the condition evaluates to {@code true}.
+ *
+ *
* @see GeorchestraGatewaySecurityConfigProperties
*/
class AtLeastOneLdapDatasourceEnabledCondition extends SpringBootCondition {
+ /**
+ * Determines whether the condition matches based on the presence of at least
+ * one enabled LDAP data source.
+ *
+ * @param context the condition evaluation context
+ * @param metadata the metadata of the annotated component
+ * @return a {@link ConditionOutcome} indicating whether the condition matches
+ */
@Override
public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
-
Set enabledDatasourceNames = findEnabled(context);
boolean anyEnabled = !enabledDatasourceNames.isEmpty();
@@ -62,20 +72,19 @@ public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeM
}
ItemsBuilder itemsBuilder = ConditionMessage.forCondition(ConditionalOnLdapEnabled.class)
- .didNotFind("any enabled ldap config");
+ .didNotFind("any enabled LDAP configuration");
- ConditionMessage message;
- if (enabledDatasourceNames.isEmpty()) {
- message = itemsBuilder.atAll();
- } else {
- message = itemsBuilder.items(enabledDatasourceNames);
- }
+ ConditionMessage message = enabledDatasourceNames.isEmpty() ? itemsBuilder.atAll()
+ : itemsBuilder.items(enabledDatasourceNames);
return ConditionOutcome.noMatch(message);
}
/**
- * @return the configured LDAP data source names that are enabled
+ * Finds enabled LDAP configurations based on environment properties.
+ *
+ * @param context the condition evaluation context
+ * @return a set of enabled LDAP data source names
*/
static Set findEnabled(ConditionContext context) {
Environment environment = context.getEnvironment();
@@ -86,30 +95,30 @@ static Set findEnabled(ConditionContext context) {
List propertyNames = findMatchingPropertyNames(propertySources, regex);
Set names = new HashSet<>();
- for (String p : propertyNames) {
- String value = environment.getProperty(p);
+ for (String property : propertyNames) {
+ String value = environment.getProperty(property);
if (Boolean.parseBoolean(value)) {
- Matcher matcher = pattern.matcher(p);
+ Matcher matcher = pattern.matcher(property);
if (matcher.matches()) {
- String name = matcher.group(1);
- names.add(name);
+ names.add(matcher.group(1));
}
}
}
return names;
}
+ /**
+ * Retrieves property names that match the specified regular expression.
+ *
+ * @param propertySources the available property sources
+ * @param regex the regular expression to match property names
+ * @return a list of matching property names
+ */
static List findMatchingPropertyNames(MutablePropertySources propertySources, final String regex) {
-
final Pattern pattern = Pattern.compile(regex);
final Predicate filter = pattern.asMatchPredicate();
- return Streams.stream(propertySources)//
- .filter(EnumerablePropertySource.class::isInstance)//
- .map(EnumerablePropertySource.class::cast)//
- .map(EnumerablePropertySource::getPropertyNames)//
- .flatMap(Stream::of)//
- .filter(filter)//
- .toList();
+ return Streams.stream(propertySources).filter(EnumerablePropertySource.class::isInstance)
+ .map(EnumerablePropertySource.class::cast).map(EnumerablePropertySource::getPropertyNames)
+ .flatMap(Stream::of).filter(filter).toList();
}
-
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnHeaderPreAuthentication.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnHeaderPreAuthentication.java
index dfbd381f..e7f565bd 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnHeaderPreAuthentication.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnHeaderPreAuthentication.java
@@ -16,7 +16,6 @@
* You should have received a copy of the GNU General Public License along with
* geOrchestra. If not, see .
*/
-
package org.georchestra.gateway.autoconfigure.security;
import java.lang.annotation.Documented;
@@ -29,7 +28,14 @@
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
/**
+ * Condition that enables a bean if header-based pre-authentication is enabled.
+ *
+ * This annotation ensures that a component is only loaded when the
+ * {@code georchestra.gateway.security.preauth.enabled} property is set to
+ * {@code true}.
+ *
*
+ * @see HeaderPreauthConfigProperties
*/
@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnLdapEnabled.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnLdapEnabled.java
index 6e4326ba..7ec0e3f0 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnLdapEnabled.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/ConditionalOnLdapEnabled.java
@@ -16,7 +16,6 @@
* You should have received a copy of the GNU General Public License along with
* geOrchestra. If not, see .
*/
-
package org.georchestra.gateway.autoconfigure.security;
import java.lang.annotation.Documented;
@@ -30,7 +29,19 @@
import org.springframework.ldap.core.LdapTemplate;
/**
+ * Condition that enables a bean if LDAP support is available and at least one
+ * LDAP data source is enabled.
+ *
+ * This annotation ensures that a component is only loaded when:
+ *
+ *
The {@link LdapTemplate} class is present on the classpath.
+ *
At least one LDAP configuration is enabled, as determined by
+ * {@link AtLeastOneLdapDatasourceEnabledCondition}.
- * This feature shall be enabled through the
- * {@code georchestra.gateway.security.header-authentication.enabled=true}
- * config property.
- *
+ * This configuration enables header-based pre-authentication when the
+ * {@code georchestra.gateway.security.header-authentication.enabled} property
+ * is set to {@code true}.
+ *
+ *
+ *
+ * It imports {@link HeaderPreAuthenticationConfiguration}, which provides the
+ * necessary beans for handling pre-authentication via request headers.
+ *
+ *
* @see ConditionalOnHeaderPreAuthentication
* @see HeaderPreAuthenticationConfiguration
*/
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/LdapSecurityAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/LdapSecurityAutoConfiguration.java
index fc71708c..895359b3 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/LdapSecurityAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/LdapSecurityAutoConfiguration.java
@@ -22,14 +22,27 @@
import org.georchestra.gateway.security.ldap.LdapAuthenticationConfiguration;
import org.springframework.boot.autoconfigure.AutoConfiguration;
-import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Import;
import lombok.extern.slf4j.Slf4j;
/**
- * {@link EnableAutoConfiguration AutoConfiguration} to set up LDAP security
- *
+ * Auto-configuration for LDAP-based authentication in geOrchestra.
+ *
+ * This configuration enables LDAP authentication when at least one LDAP data
+ * source is enabled and the required dependencies are available.
+ *
+ *
+ *
+ * It imports {@link LdapAuthenticationConfiguration}, which sets up the
+ * necessary beans for LDAP authentication.
+ *
+ *
+ *
+ * Upon initialization, this configuration logs a message indicating that LDAP
+ * authentication has been enabled.
+ *
+ *
* @see LdapAuthenticationConfiguration
*/
@AutoConfiguration
@@ -38,7 +51,11 @@
@Slf4j(topic = "org.georchestra.gateway.autoconfigure.security")
public class LdapSecurityAutoConfiguration {
- public @PostConstruct void log() {
+ /**
+ * Logs a message when LDAP security is enabled.
+ */
+ @PostConstruct
+ public void log() {
log.info("georchestra LDAP security enabled");
}
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/OAuth2SecurityAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/OAuth2SecurityAutoConfiguration.java
index 9c157d66..74f7588b 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/OAuth2SecurityAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/OAuth2SecurityAutoConfiguration.java
@@ -28,23 +28,66 @@
import lombok.extern.slf4j.Slf4j;
+/**
+ * Auto-configuration for OAuth2-based authentication in geOrchestra.
+ *
+ * This configuration conditionally enables or disables OAuth2 security based on
+ * the property {@code georchestra.gateway.security.oauth2.enabled}.
+ *
+ *
+ *
+ * It imports either:
+ *
+ *
{@link Enabled} when OAuth2 is enabled.
+ *
{@link Disabled} when OAuth2 is disabled (default).
+ *
+ *
+ *
+ * @see OAuth2Configuration
+ */
@AutoConfiguration
@Slf4j(topic = "org.georchestra.gateway.autoconfigure.security")
@Import({ OAuth2SecurityAutoConfiguration.Enabled.class, OAuth2SecurityAutoConfiguration.Disabled.class })
public class OAuth2SecurityAutoConfiguration {
+
private static final String ENABLED_PROP = "georchestra.gateway.security.oauth2.enabled";
+ /**
+ * Configuration that enables OAuth2 security when explicitly enabled.
+ *
+ * This configuration is loaded if
+ * {@code georchestra.gateway.security.oauth2.enabled} is set to {@code true}.
+ *
+ */
@Import(OAuth2Configuration.class)
@ConditionalOnProperty(name = ENABLED_PROP, havingValue = "true", matchIfMissing = false)
static @Configuration class Enabled {
- public @PostConstruct void log() {
+
+ /**
+ * Logs a message indicating that OAuth2 security is enabled.
+ */
+ @PostConstruct
+ public void log() {
log.info("georchestra OAuth2 security enabled");
}
}
+ /**
+ * Configuration that disables OAuth2 security by default.
+ *
+ * This configuration is loaded if
+ * {@code georchestra.gateway.security.oauth2.enabled} is set to {@code false}
+ * or is missing.
+ *
+ */
@ConditionalOnProperty(name = ENABLED_PROP, havingValue = "false", matchIfMissing = true)
static @Configuration class Disabled {
- public @PostConstruct void log() {
+
+ /**
+ * Logs a message indicating that OAuth2 security is disabled.
+ */
+ @PostConstruct
+ public void log() {
log.info("georchestra OAuth2 security disabled");
}
}
diff --git a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/WebSecurityAutoConfiguration.java b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/WebSecurityAutoConfiguration.java
index 5a4ff71a..bdac034c 100644
--- a/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/WebSecurityAutoConfiguration.java
+++ b/gateway/src/main/java/org/georchestra/gateway/autoconfigure/security/WebSecurityAutoConfiguration.java
@@ -24,6 +24,28 @@
import org.springframework.boot.autoconfigure.security.ConditionalOnDefaultWebSecurity;
import org.springframework.context.annotation.Import;
+/**
+ * Auto-configuration for web security in geOrchestra Gateway.
+ *
+ * This configuration is applied only when Spring Security's default web
+ * security is enabled, as determined by
+ * {@link ConditionalOnDefaultWebSecurity}.
+ *
+ *
+ *
+ * It imports:
+ *
+ *
{@link GatewaySecurityConfiguration} - Configures security settings for
+ * the gateway.
+ *
+ *
+ * @see GatewaySecurityConfiguration
+ * @see AccessRulesConfiguration
+ * @see ConditionalOnDefaultWebSecurity
+ */
@AutoConfiguration
@ConditionalOnDefaultWebSecurity
@Import({ GatewaySecurityConfiguration.class, AccessRulesConfiguration.class })
diff --git a/gateway/src/main/java/org/georchestra/gateway/filter/global/ApplicationErrorGatewayFilterFactory.java b/gateway/src/main/java/org/georchestra/gateway/filter/global/ApplicationErrorGatewayFilterFactory.java
index 770ec931..d4d1d8cc 100644
--- a/gateway/src/main/java/org/georchestra/gateway/filter/global/ApplicationErrorGatewayFilterFactory.java
+++ b/gateway/src/main/java/org/georchestra/gateway/filter/global/ApplicationErrorGatewayFilterFactory.java
@@ -38,17 +38,20 @@
import reactor.core.publisher.Mono;
/**
- * Filter to allow custom error pages to be used when an application behind the
- * gateways returns an error, only for idempotent HTTP response status codes
- * (i.e. GET, HEAD, OPTIONS).
+ * Gateway filter that enables custom error pages when a proxied application
+ * responds with an error status, applicable only for idempotent HTTP methods
+ * (e.g., GET, HEAD, OPTIONS).
*
- * {@link GatewayFilterFactory} providing a {@link GatewayFilter} that throws a
- * {@link ResponseStatusException} with the proxied response status code if the
- * target responded with a {@code 400...} or {@code 500...} status code.
- *
+ * This {@link GatewayFilterFactory} provides a {@link GatewayFilter} that
+ * throws a {@link ResponseStatusException} with the response status code if the
+ * proxied service returns a {@code 400...} or {@code 500...} status. The
+ * gateway will then apply its custom error handling.
+ *
*
- * Usage: to enable it globally, add this to application.yaml :
- *
+ * Usage: To enable this filter globally, add the following to
+ * {@code application.yaml}:
+ *
- *
- * To enable it only on some routes, add this to concerned routes in
- * {@literal routes.yaml}:
- *
+ *
+ *
+ * To enable it only for specific routes, configure the filter in
+ * {@code routes.yaml}:
+ *
+ *
*
*
* filters:
@@ -81,11 +86,22 @@ public GatewayFilter apply(final Object config) {
return new ServiceErrorGatewayFilter();
}
+ /**
+ * Gateway filter that intercepts error responses and triggers a
+ * {@link ResponseStatusException} to allow the gateway to render a custom error
+ * page.
+ */
private class ServiceErrorGatewayFilter implements GatewayFilter, Ordered {
+
/**
- * @return {@link Ordered#HIGHEST_PRECEDENCE} or
- * {@link ApplicationErrorConveyorHttpResponse#beforeCommit(Supplier)}
- * won't be called
+ * Returns the order of this filter to ensure it runs at the highest precedence.
+ *
+ * This is necessary so that
+ * {@link ApplicationErrorConveyorHttpResponse#beforeCommit(Supplier)} gets
+ * executed properly.
+ *
+ *
+ * @return {@link Ordered#HIGHEST_PRECEDENCE}
*/
@Override
public int getOrder() {
@@ -93,11 +109,18 @@ public int getOrder() {
}
/**
- * If the request method is idempotent and accepts {@literal text/html}, applies
- * a filter that when the routed response receives an error status code, will
- * throw a {@link ResponseStatusException} with the same status, for the gateway
- * to apply the customized error template, also when the status code comes from
- * a proxied service response
+ * Applies the filter logic by wrapping the response in a decorator that checks
+ * for error statuses.
+ *
+ * If the request method is idempotent and the request accepts
+ * {@code text/html}, the response is wrapped in a
+ * {@link ApplicationErrorConveyorHttpResponse}, which throws a
+ * {@link ResponseStatusException} if an error status code is encountered.
+ *
+ *
+ * @param exchange the current server exchange
+ * @param chain the gateway filter chain
+ * @return a {@link Mono} that completes when the filter chain is executed
*/
@Override
public Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) {
@@ -108,16 +131,37 @@ public Mono filter(ServerWebExchange exchange, GatewayFilterChain chain) {
}
}
+ /**
+ * Wraps the server exchange's response with an
+ * {@link ApplicationErrorConveyorHttpResponse} to intercept error statuses.
+ *
+ * @param exchange the server exchange to decorate
+ * @return a new {@link ServerWebExchange} instance with the decorated response
+ */
ServerWebExchange decorate(ServerWebExchange exchange) {
var response = new ApplicationErrorConveyorHttpResponse(exchange.getResponse());
exchange = exchange.mutate().response(response).build();
return exchange;
}
+ /**
+ * Determines if the request should be filtered based on method idempotency and
+ * accepted content types.
+ *
+ * @param request the incoming HTTP request
+ * @return {@code true} if the request should be filtered, {@code false}
+ * otherwise
+ */
boolean canFilter(ServerHttpRequest request) {
return methodIsIdempotent(request.getMethod()) && acceptsHtml(request);
}
+ /**
+ * Checks if the request method is idempotent (i.e., does not modify state).
+ *
+ * @param method the HTTP method to check
+ * @return {@code true} if the method is idempotent, {@code false} otherwise
+ */
boolean methodIsIdempotent(HttpMethod method) {
return switch (method) {
case GET, HEAD, OPTIONS, TRACE -> true;
@@ -125,15 +169,21 @@ boolean methodIsIdempotent(HttpMethod method) {
};
}
+ /**
+ * Determines whether the request accepts HTML responses.
+ *
+ * @param request the incoming HTTP request
+ * @return {@code true} if the request accepts {@code text/html}, {@code false}
+ * otherwise
+ */
boolean acceptsHtml(ServerHttpRequest request) {
return request.getHeaders().getAccept().stream().anyMatch(MediaType.TEXT_HTML::isCompatibleWith);
}
/**
- * A response decorator that throws a {@link ResponseStatusException} at
- * {@link #beforeCommit} if the status code is an error code, thus letting the
- * gateway render the appropriate custom error page instead of the original
- * application response body.
+ * A response decorator that throws a {@link ResponseStatusException} in
+ * {@link #beforeCommit} if the status code is an error, allowing the gateway to
+ * handle the error with a custom response page.
*/
private static class ApplicationErrorConveyorHttpResponse extends ServerHttpResponseDecorator {
@@ -148,6 +198,10 @@ public void beforeCommit(Supplier> action) {
super.beforeCommit(() -> checkedAction);
}
+ /**
+ * Throws a {@link ResponseStatusException} if the response status is in the 4xx
+ * or 5xx range, allowing the gateway to apply custom error handling.
+ */
private void checkStatusCode() {
HttpStatus statusCode = getStatusCode();
log.debug("native status code: {}", statusCode);
diff --git a/gateway/src/main/java/org/georchestra/gateway/filter/global/LoginParamRedirectGatewayFilterFactory.java b/gateway/src/main/java/org/georchestra/gateway/filter/global/LoginParamRedirectGatewayFilterFactory.java
index 3856a80f..f5c89de7 100644
--- a/gateway/src/main/java/org/georchestra/gateway/filter/global/LoginParamRedirectGatewayFilterFactory.java
+++ b/gateway/src/main/java/org/georchestra/gateway/filter/global/LoginParamRedirectGatewayFilterFactory.java
@@ -48,12 +48,18 @@
import reactor.core.publisher.Mono;
/**
- * {@link GatewayFilterFactory} that redirects to {@literal /login} if the
- * request's query string contains a {@literal login} parameter and the request
- * is not already authenticated.
+ * {@link GatewayFilterFactory} that redirects unauthenticated requests to
+ * {@literal /login} when the query string contains a {@literal login}
+ * parameter.
*
- * Sample usage:
- *
+ * This filter applies only to idempotent HTTP methods (GET, HEAD, OPTIONS,
+ * TRACE) and ensures that authenticated users proceed without redirection.
+ *
+ *
+ * Usage: Add the following to {@code application.yaml} to enable this
+ * filter for specific routes:
+ *