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
```