0
# CAS Server Core Multitenancy
1

2
CAS Server Core Multitenancy is a Java library that provides comprehensive tenant management capabilities for the Central Authentication Service (CAS). It enables multi-tenant authentication deployments where different organizations or environments can coexist within a single CAS infrastructure while maintaining complete isolation and customization capabilities for each tenant.
3

4
## Package Information
5

6
- **Package Name**: cas-server-core-multitenancy
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 7.2.4
10
- **Group ID**: org.apereo.cas
11
- **Installation**: Add dependency to your Maven/Gradle build file
12

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

22
Gradle:
23
```groovy
24
implementation 'org.apereo.cas:cas-server-core-multitenancy:7.2.4'
25
```
26

27
## Core Imports
28

29
```java
30
import org.apereo.cas.multitenancy.TenantsManager;
31
import org.apereo.cas.multitenancy.TenantExtractor;
32
import org.apereo.cas.multitenancy.TenantDefinition;
33
import org.apereo.cas.multitenancy.DefaultTenantsManager;
34
import org.apereo.cas.multitenancy.DefaultTenantExtractor;
35
```
36

37
## Basic Usage
38

39
```java
40
import org.apereo.cas.multitenancy.*;
41
import org.apereo.cas.configuration.CasConfigurationProperties;
42
import org.springframework.core.io.ClassPathResource;
43
import org.springframework.core.io.Resource;
44
import java.util.Optional;
45

46
// Create a tenants manager with JSON configuration
47
Resource tenantsConfig = new ClassPathResource("tenants.json");
48
TenantsManager tenantsManager = new DefaultTenantsManager(tenantsConfig);
49

50
// Find a specific tenant
51
Optional<TenantDefinition> tenant = tenantsManager.findTenant("tenant1");
52
if (tenant.isPresent()) {
53
    TenantDefinition tenantDef = tenant.get();
54
    System.out.println("Tenant: " + tenantDef.getId());
55
    System.out.println("Description: " + tenantDef.getDescription());
56
}
57

58
// Extract tenant from request path (requires CAS configuration)
59
CasConfigurationProperties casProperties = new CasConfigurationProperties();
60
TenantExtractor extractor = new DefaultTenantExtractor(tenantsManager, casProperties);
61
Optional<TenantDefinition> extractedTenant = extractor.extract("/tenants/tenant1/login");
62
```
63

64
## Architecture
65

66
The CAS multitenancy module is built around several key components:
67

68
- **Tenant Management**: Central repository for tenant definitions with JSON-based configuration and dynamic reloading
69
- **Tenant Extraction**: URL pattern matching to identify tenant context from incoming requests
70
- **Policy Framework**: Separate, configurable policies for authentication, communication, delegation, and multifactor authentication per tenant
71
- **Spring Integration**: Full Spring Boot auto-configuration with proper bean lifecycle management
72
- **Configuration Watching**: File system monitoring for dynamic tenant configuration updates
73

74
## Capabilities
75

76
### Tenant Management
77

78
Core functionality for managing tenant definitions, including loading from JSON configuration files and providing lookup capabilities.
79

80
```java { .api }
81
public interface TenantsManager {
82
    Optional<TenantDefinition> findTenant(String tenantId);
83
    List<TenantDefinition> findTenants();
84
}
85

86
public class DefaultTenantsManager implements TenantsManager, DisposableBean {
87
    public DefaultTenantsManager();
88
    public DefaultTenantsManager(Resource resource);
89
}
90
```
91

92
[Tenant Management](./tenant-management.md)
93

94
### Tenant Extraction
95

96
System for extracting tenant context from HTTP requests using configurable URL patterns and request processing.
97

98
```java { .api }
99
public interface TenantExtractor {
100
    TenantsManager getTenantsManager();
101
    Optional<TenantDefinition> extract(HttpServletRequest request);
102
    Optional<TenantDefinition> extract(RequestContext requestContext);
103
    Optional<TenantDefinition> extract(String requestPath);
104
    static String tenantIdFromPath(String requestPath);
105
}
106

107
public class DefaultTenantExtractor implements TenantExtractor {
108
    public DefaultTenantExtractor(TenantsManager tenantsManager, CasConfigurationProperties casProperties);
109
}
110
```
111

112
[Tenant Extraction](./tenant-extraction.md)
113

114
### Tenant Definition and Policies
115

116
Complete tenant configuration model with separate policy objects for different aspects of authentication and communication.
117

118
```java { .api }
119
public class TenantDefinition implements Serializable {
120
    private String id;
121
    private String description;
122
    private TenantAuthenticationPolicy authenticationPolicy;
123
    private TenantCommunicationPolicy communicationPolicy;
124
    private TenantDelegatedAuthenticationPolicy delegatedAuthenticationPolicy;
125
    private TenantMultifactorAuthenticationPolicy multifactorAuthenticationPolicy;
126
    
127
    public String getId();
128
    public void setId(String id);
129
    public String getDescription();
130
    public void setDescription(String description);
131
    public TenantAuthenticationPolicy getAuthenticationPolicy();
132
    public void setAuthenticationPolicy(TenantAuthenticationPolicy authenticationPolicy);
133
    public TenantCommunicationPolicy getCommunicationPolicy();
134
    public void setCommunicationPolicy(TenantCommunicationPolicy communicationPolicy);
135
    public TenantDelegatedAuthenticationPolicy getDelegatedAuthenticationPolicy();
136
    public void setDelegatedAuthenticationPolicy(TenantDelegatedAuthenticationPolicy delegatedAuthenticationPolicy);
137
    public TenantMultifactorAuthenticationPolicy getMultifactorAuthenticationPolicy();
138
    public void setMultifactorAuthenticationPolicy(TenantMultifactorAuthenticationPolicy multifactorAuthenticationPolicy);
139
}
140
```
141

142
[Tenant Policies](./tenant-policies.md)
143

144
### Spring Configuration
145

146
Auto-configuration classes and beans for seamless Spring Boot integration with proper conditional configuration.
147

148
```java { .api }
149
@AutoConfiguration
150
@EnableConfigurationProperties(CasConfigurationProperties.class)
151
@ConditionalOnFeatureEnabled(feature = CasFeatureModule.FeatureCatalog.Multitenancy)
152
public class CasCoreMultitenancyAutoConfiguration {
153
    @Bean
154
    @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
155
    @ConditionalOnMissingBean(name = TenantsManager.BEAN_NAME)
156
    public TenantsManager tenantsManager(CasConfigurationProperties casProperties) throws Exception;
157
    
158
    @Bean
159
    @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
160
    @ConditionalOnMissingBean(name = TenantExtractor.BEAN_NAME)
161
    public TenantExtractor tenantExtractor(CasConfigurationProperties casProperties, 
162
        @Qualifier(TenantsManager.BEAN_NAME) TenantsManager tenantsManager);
163
    
164
    @Bean
165
    @ConditionalOnMissingBean(name = "casMultitenancyEndpointConfigurer")
166
    @RefreshScope(proxyMode = ScopedProxyMode.DEFAULT)
167
    public CasWebSecurityConfigurer<HttpSecurity> casMultitenancyEndpointConfigurer();
168
}
169
```
170

171
[Spring Integration](./spring-integration.md)
172

173
## Common Types
174

175
### Core Constants
176

177
```java { .api }
178
public interface TenantsManager {
179
    String BEAN_NAME = "tenantsManager";
180
}
181

182
public interface TenantExtractor {
183
    String BEAN_NAME = "tenantExtractor";
184
    Pattern PATTERN_TENANTS = Pattern.compile("tenants/(.+)/(.+)", Pattern.CASE_INSENSITIVE);
185
}
186
```
187

188
### Exception Types
189

190
```java { .api }
191
public class UnknownTenantException extends RuntimeException {
192
    public UnknownTenantException(String message);
193
}
194
```