0
# CAS Server Core Webflow MFA API
1
2
The CAS Server Core Webflow MFA API provides the foundational interfaces and base classes for integrating multifactor authentication (MFA) providers into the Apereo Central Authentication Service webflow. This module serves as the core framework for MFA webflow configuration, event resolution, and provider orchestration within CAS deployments.
3
4
## Package Information
5
6
- **Package Name**: cas-server-core-webflow-mfa-api
7
- **Package Type**: maven
8
- **Language**: Java 21
9
- **Group ID**: org.apereo.cas
10
- **Installation**: Include as Maven dependency in CAS modules
11
12
## Core Imports
13
14
```java
15
import org.apereo.cas.web.flow.configurer.AbstractCasMultifactorWebflowConfigurer;
16
import org.apereo.cas.web.flow.configurer.CasMultifactorWebflowConfigurer;
17
import org.apereo.cas.web.flow.util.MultifactorAuthenticationWebflowUtils;
18
import org.apereo.cas.web.flow.actions.AbstractMultifactorAuthenticationAction;
19
```
20
21
## Basic Usage
22
23
```java
24
// Extend base configurer to create custom MFA webflow
25
public class MyMfaWebflowConfigurer extends AbstractCasMultifactorWebflowConfigurer {
26
27
public MyMfaWebflowConfigurer(
28
FlowBuilderServices flowBuilderServices,
29
FlowDefinitionRegistry flowDefinitionRegistry,
30
ConfigurableApplicationContext applicationContext,
31
CasConfigurationProperties casProperties,
32
Optional<FlowDefinitionRegistry> mfaFlowDefinitionRegistry,
33
List<CasMultifactorWebflowCustomizer> mfaFlowCustomizers) {
34
super(flowBuilderServices, flowDefinitionRegistry, applicationContext,
35
casProperties, mfaFlowDefinitionRegistry, mfaFlowCustomizers);
36
}
37
38
@Override
39
protected void doInitialize() {
40
val loginFlow = getLoginFlow();
41
registerMultifactorProviderAuthenticationWebflow(loginFlow, "myMfaProvider");
42
}
43
}
44
45
// Create custom MFA action
46
public class MyMfaAction extends AbstractMultifactorAuthenticationAction<MyMfaProvider> {
47
48
@Override
49
protected Event doExecuteInternal(RequestContext context) {
50
// Access resolved provider via this.provider field
51
val principal = resolvePrincipal(
52
WebUtils.getAuthentication(context).getPrincipal(), context);
53
54
// Perform MFA-specific logic
55
return success();
56
}
57
}
58
```
59
60
## Architecture
61
62
The CAS MFA Webflow API is organized into several key architectural layers:
63
64
- **Configuration Layer**: Interfaces and base classes for webflow configuration (`CasMultifactorWebflowConfigurer`, `AbstractCasMultifactorWebflowConfigurer`)
65
- **Event Resolution Layer**: Components that determine when and which MFA providers should be triggered during authentication flows
66
- **Action Layer**: Webflow actions that execute MFA-specific logic during state transitions
67
- **Provider Selection Layer**: Specialized components for handling scenarios with multiple available MFA providers
68
- **Utility Layer**: Static utility methods for managing MFA-related data in webflow scopes
69
70
## Capabilities
71
72
### Webflow Configuration
73
74
Core interfaces and base classes for configuring MFA webflows and integrating MFA providers into the CAS authentication flow.
75
76
```java { .api }
77
public interface CasMultifactorWebflowConfigurer {
78
void registerMultifactorProviderAuthenticationWebflow(Flow flow, String subflowId, String providerId);
79
default void registerMultifactorProviderAuthenticationWebflow(Flow flow, String providerId);
80
int getOrder();
81
List<FlowDefinitionRegistry> getMultifactorAuthenticationFlowDefinitionRegistries();
82
}
83
84
public abstract class AbstractCasMultifactorWebflowConfigurer extends AbstractCasWebflowConfigurer
85
implements CasMultifactorWebflowConfigurer {
86
87
public void registerMultifactorProviderAuthenticationWebflow(Flow flow, String subflowId, String providerId);
88
public List<FlowDefinitionRegistry> getMultifactorAuthenticationFlowDefinitionRegistries();
89
public int getOrder();
90
}
91
```
92
93
[Webflow Configuration](./webflow-configuration.md)
94
95
### Event Resolution
96
97
Components responsible for determining when MFA should be triggered and which providers should be used based on authentication context and policies.
98
99
```java { .api }
100
public abstract class AbstractCasMultifactorAuthenticationWebflowEventResolver
101
extends AbstractCasWebflowEventResolver {
102
103
protected AbstractCasMultifactorAuthenticationWebflowEventResolver(
104
CasWebflowEventResolutionConfigurationContext webflowEventResolutionConfigurationContext);
105
}
106
107
public class RankedMultifactorAuthenticationProviderWebflowEventResolver
108
extends AbstractCasMultifactorAuthenticationWebflowEventResolver {
109
110
public Set<Event> resolveInternal(RequestContext context);
111
public Event resolveSingle(RequestContext context);
112
public void addDelegate(CasWebflowEventResolver resolver);
113
public void addDelegate(CasWebflowEventResolver resolver, int index);
114
}
115
```
116
117
[Event Resolution](./event-resolution.md)
118
119
### Webflow Actions
120
121
Action classes that execute during webflow state transitions to perform MFA-specific operations like availability checks, bypassing, and failure handling.
122
123
```java { .api }
124
public abstract class AbstractMultifactorAuthenticationAction<T extends MultifactorAuthenticationProvider>
125
extends BaseCasWebflowAction {
126
127
protected T provider;
128
129
protected Principal resolvePrincipal(Principal principal, RequestContext requestContext);
130
protected String getThrottledRequestKeyFor(Authentication authentication, RequestContext requestContext);
131
}
132
133
public class MultifactorAuthenticationAvailableAction
134
extends AbstractMultifactorAuthenticationAction<MultifactorAuthenticationProvider>;
135
136
public class MultifactorAuthenticationBypassAction
137
extends AbstractMultifactorAuthenticationAction<MultifactorAuthenticationProvider>;
138
```
139
140
[Webflow Actions](./webflow-actions.md)
141
142
### Provider Selection
143
144
Specialized components for handling composite MFA scenarios where multiple providers are available and selection logic is required.
145
146
```java { .api }
147
@FunctionalInterface
148
public interface MultifactorProviderSelectionCriteria {
149
boolean shouldProceedWithMultifactorProviderSelection(RequestContext requestContext);
150
static MultifactorProviderSelectionCriteria select();
151
}
152
153
public class MultifactorProviderSelectedAction extends BaseCasWebflowAction {
154
public static final String PARAMETER_SELECTED_MFA_PROVIDER = "mfaProvider";
155
156
protected Event doExecuteInternal(RequestContext requestContext);
157
protected void rememberSelectedMultifactorAuthenticationProvider(RequestContext context, String providerId);
158
}
159
```
160
161
[Provider Selection](./provider-selection.md)
162
163
### Authentication Components
164
165
Core authentication and provider selection logic including selectors, resolvers, and transaction management components.
166
167
```java { .api }
168
public abstract class BaseMultifactorAuthenticationProviderEventResolver
169
extends AbstractCasMultifactorAuthenticationWebflowEventResolver {
170
171
protected RegisteredService resolveRegisteredServiceInRequestContext(RequestContext requestContext);
172
}
173
174
public class RankedMultifactorAuthenticationProviderSelector
175
implements MultifactorAuthenticationProviderSelector {
176
177
public MultifactorAuthenticationProvider resolve(
178
Collection<MultifactorAuthenticationProvider> providers,
179
RegisteredService service,
180
Principal principal);
181
}
182
```
183
184
[Authentication Components](./authentication-components.md)
185
186
### Webflow Utilities
187
188
Static utility methods for managing MFA-related data in webflow scopes, device registration, provider selection, and token management.
189
190
```java { .api }
191
@UtilityClass
192
public class MultifactorAuthenticationWebflowUtils {
193
194
// Provider management
195
public static void putMultifactorAuthenticationProvider(RequestContext context, MultifactorAuthenticationProvider provider);
196
public static String getMultifactorAuthenticationProvider(RequestContext context);
197
public static void putResolvedMultifactorAuthenticationProviders(RequestContext context, Collection<MultifactorAuthenticationProvider> value);
198
public static Collection<String> getResolvedMultifactorAuthenticationProviders(RequestContext context);
199
200
// Device registration
201
public static boolean isMultifactorDeviceRegistrationEnabled(RequestContext requestContext);
202
public static void putMultifactorDeviceRegistrationEnabled(RequestContext requestContext, boolean enabled);
203
204
// Provider selection
205
public static void putSelectableMultifactorAuthenticationProviders(RequestContext requestContext, List<String> mfaProviders);
206
public static List<String> getSelectableMultifactorAuthenticationProviders(RequestContext requestContext);
207
}
208
```
209
210
[Webflow Utilities](./webflow-utilities.md)
211
212
## Types
213
214
### Core Types
215
216
```java { .api }
217
// From CAS core authentication API
218
public interface MultifactorAuthenticationProvider {
219
String getId();
220
int getOrder();
221
String getFriendlyName();
222
boolean matches(String identifier);
223
MultifactorAuthenticationFailureMode getFailureMode();
224
String getFailureModeEvaluator();
225
MultifactorAuthenticationBypassEvaluator getBypassEvaluator();
226
}
227
228
// From Spring Webflow
229
public interface RequestContext {
230
FlowScope getFlowScope();
231
ConversationScope getConversationScope();
232
ViewScope getViewScope();
233
}
234
235
public interface Flow {
236
String getId();
237
StateDefinition getStartState();
238
TransitionableState getTransitionableState(String stateId);
239
}
240
```