0
# CAS Server Core Configuration API
1

2
A comprehensive Java library providing configuration management and property source location capabilities for the Central Authentication Service (CAS). This module serves as the foundational component for dynamically locating, loading, validating, and decrypting configuration properties from various sources including files, environment variables, and external systems.
3

4
## Package Information
5

6
- **Package Name**: cas-server-core-configuration-api
7
- **Group ID**: org.apereo.cas
8
- **Language**: Java
9
- **Version**: 7.2.4
10
- **License**: Apache-2.0
11
- **Installation**: Add to Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>org.apereo.cas</groupId>
16
    <artifactId>cas-server-core-configuration-api</artifactId>
17
    <version>7.2.4</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.apereo.cas.configuration.api.CasConfigurationPropertiesSourceLocator;
25
import org.apereo.cas.configuration.CasConfigurationPropertiesEnvironmentManager;
26
import org.apereo.cas.configuration.CasConfigurationWatchService;
27
import org.apereo.cas.configuration.support.CasConfigurationJasyptCipherExecutor;
28
```
29

30
For configuration loaders:
31

32
```java
33
import org.apereo.cas.configuration.loader.CasConfigurationPropertiesLoader;
34
import org.apereo.cas.configuration.loader.YamlConfigurationPropertiesLoader;
35
import org.apereo.cas.configuration.loader.SimpleConfigurationPropertiesLoader;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.apereo.cas.configuration.api.CasConfigurationPropertiesSourceLocator;
42
import org.apereo.cas.configuration.DefaultCasConfigurationPropertiesSourceLocator;
43
import org.apereo.cas.configuration.support.CasConfigurationJasyptCipherExecutor;
44
import org.springframework.core.env.StandardEnvironment;
45
import org.springframework.core.io.DefaultResourceLoader;
46

47
// Create environment and resource loader
48
Environment environment = new StandardEnvironment();
49
ResourceLoader resourceLoader = new DefaultResourceLoader();
50

51
// Create cipher executor for encryption support
52
CasConfigurationJasyptCipherExecutor cipherExecutor = 
53
    new CasConfigurationJasyptCipherExecutor(environment);
54

55
// Create property source locator
56
CasConfigurationPropertiesSourceLocator locator = 
57
    new DefaultCasConfigurationPropertiesSourceLocator(cipherExecutor);
58

59
// Locate configuration property sources
60
Optional<PropertySource<?>> propertySource = locator.locate(environment, resourceLoader);
61

62
if (propertySource.isPresent()) {
63
    System.out.println("Configuration loaded successfully");
64
    // Use the property source with Spring environment
65
}
66
```
67

68
## Architecture
69

70
The CAS Configuration API is built around several key architectural components:
71

72
- **Property Source Locators**: Primary interfaces for discovering and loading configuration from various sources with defined precedence
73
- **Configuration Loaders**: Pluggable mechanism for reading different configuration file formats (YAML, Properties) using ServiceLoader pattern
74
- **Encryption Support**: Jasypt-based cipher executors for encrypting/decrypting sensitive configuration values
75
- **Configuration Management**: Environment managers and validators for runtime configuration handling
76
- **File Watching**: Services that monitor configuration files for changes and publish events
77

78
This architecture enables CAS to support flexible configuration deployment patterns including standalone files, directory-based configurations, embedded classpath resources, and Docker secrets integration.
79

80
## Capabilities
81

82
### Property Source Location
83

84
Core functionality for locating and loading configuration properties from multiple sources with defined precedence. Supports standalone files, configuration directories, classpath resources, system properties, environment variables, and Docker secrets.
85

86
```java { .api }
87
public interface CasConfigurationPropertiesSourceLocator {
88
    Optional<PropertySource<?>> locate(Environment environment, ResourceLoader resourceLoader);
89
    
90
    // Static utility methods
91
    static File getStandaloneProfileConfigurationDirectory(Environment environment);
92
    static File getStandaloneProfileConfigurationFile(Environment environment);
93
    static String getApplicationName(Environment environment);
94
    static String getConfigurationName(Environment environment);
95
    static List<CasConfigurationPropertiesLoader> getConfigurationPropertiesLoaders();
96
}
97
```
98

99
[Property Source Location](./property-source-location.md)
100

101
### Configuration File Loading
102

103
Pluggable configuration loading system supporting multiple file formats (YAML, Properties) with encryption/decryption capabilities and ServiceLoader-based extensibility.
104

105
```java { .api }
106
public interface CasConfigurationPropertiesLoader extends NamedObject {
107
    PropertySource load(Resource resource, Environment environment, String name, 
108
                       CipherExecutor<String, String> configurationCipherExecutor);
109
    boolean supports(Resource resource);
110
}
111
```
112

113
[Configuration Loading](./configuration-loading.md)
114

115
### Configuration Encryption
116

117
Jasypt-based encryption and decryption support for sensitive configuration values with configurable algorithms, providers, and initialization vectors.
118

119
```java { .api }
120
public class CasConfigurationJasyptCipherExecutor implements CipherExecutor<String, String> {
121
    public CasConfigurationJasyptCipherExecutor(String algorithm, String password);
122
    public CasConfigurationJasyptCipherExecutor(Environment environment);
123
    
124
    public String encode(String value, Object[] parameters);
125
    public String decode(String value, Object[] parameters);
126
    public String encryptValue(String value);
127
    public String decryptValue(String value);
128
    
129
    // Static utility methods
130
    static boolean isValueEncrypted(String value);
131
    static String extractEncryptedValue(String value);
132
}
133
```
134

135
[Configuration Encryption](./configuration-encryption.md)
136

137
### Configuration Management
138

139
Runtime configuration management including property rebinding, environment configuration, and validation of configuration properties.
140

141
```java { .api }
142
public class CasConfigurationPropertiesEnvironmentManager {
143
    public CasConfigurationPropertiesEnvironmentManager(ConfigurationPropertiesBindingPostProcessor binder);
144
    
145
    public ApplicationContext rebindCasConfigurationProperties(ApplicationContext applicationContext);
146
    
147
    // Static methods
148
    static ApplicationContext rebindCasConfigurationProperties(
149
        ConfigurationPropertiesBindingPostProcessor binder, ApplicationContext applicationContext);
150
    static CompositePropertySource configureEnvironmentPropertySources(ConfigurableEnvironment environment);
151
}
152
```
153

154
[Configuration Management](./configuration-management.md)
155

156
### Configuration File Watching
157

158
File system monitoring service that watches configuration files and directories for changes, automatically publishing configuration events when modifications are detected.
159

160
```java { .api }
161
public class CasConfigurationWatchService implements Closeable, InitializingBean {
162
    public CasConfigurationWatchService(ConfigurableApplicationContext applicationContext);
163
    
164
    public void initialize();
165
    public void close();
166
    public void afterPropertiesSet();
167
}
168
```
169

170
[Configuration Watching](./configuration-watching.md)
171

172
### Utility Classes
173

174
Core utility classes providing configuration-related helper functions and type conversion capabilities.
175

176
```java { .api }
177
@UtilityClass
178
public final class CasCoreConfigurationUtils {
179
    /**
180
     * Load YAML properties from resources.
181
     *
182
     * @param resource the resources
183
     * @return map of YAML properties
184
     */
185
    static Map<String, Object> loadYamlProperties(Resource... resource);
186
}
187

188
public class CommaSeparatedStringToThrowablesConverter implements Converter<String, List<Class<? extends Throwable>>> {
189
    /**
190
     * Convert comma-separated class names to Throwable classes.
191
     *
192
     * @param source comma-separated string
193
     * @return list of Throwable classes
194
     */
195
    @Override
196
    List<Class<? extends Throwable>> convert(String source);
197
}
198
```
199

200
## Constants and Configuration Properties
201

202
```java { .api }
203
// Property source locator constants
204
String BOOTSTRAP_PROPERTY_LOCATOR_BEAN_NAME = "casCoreBootstrapPropertySourceLocator";
205
String PROPERTY_CAS_STANDALONE_CONFIGURATION_FILE = "cas.standalone.configuration-file";
206
String PROPERTY_CAS_STANDALONE_CONFIGURATION_DIRECTORY = "cas.standalone.configuration-directory";
207

208
// Default configuration directories
209
List<File> DEFAULT_CAS_CONFIG_DIRECTORIES = List.of(
210
    new File("/etc/cas/config"),
211
    new File("/opt/cas/config"), 
212
    new File("/var/cas/config")
213
);
214

215
// Configuration profiles
216
String PROFILE_STANDALONE = "standalone";
217
String PROFILE_NATIVE = "native";
218
String PROFILE_EMBEDDED = "embedded";
219
String PROFILE_NONE = "none";
220

221
// Encryption constants
222
String ENCRYPTED_VALUE_PREFIX = "{cas-cipher}";
223
String DEFAULT_SECRETS_DIR = "/run/secrets/";
224
String VAR_CAS_DOCKER_SECRETS_DIRECTORY = "CAS_DOCKER_SECRETS_DIRECTORY";
225
String VAR_CONTAINER = "CONTAINER";
226

227
// Environment manager bean name
228
String BEAN_NAME = "configurationPropertiesEnvironmentManager";
229
```
230

231
## Types
232

233
```java { .api }
234
// Jasypt encryption parameters enum
235
public enum JasyptEncryptionParameters {
236
    ALGORITHM("cas.standalone.configuration-security.alg", "PBEWithMD5AndTripleDES"),
237
    PROVIDER("cas.standalone.configuration-security.provider", null),
238
    ITERATIONS("cas.standalone.configuration-security.iterations", null),
239
    PASSWORD("cas.standalone.configuration-security.psw", null),
240
    INITIALIZATION_VECTOR("cas.standalone.configuration-security.initialization-vector", null);
241
    
242
    String getPropertyName();
243
    String getDefaultValue();
244
}
245
```