0
# CDAP Security SPI
1

2
CDAP Security SPI provides the Service Provider Interface for CDAP's security and authorization framework, enabling pluggable authorization mechanisms for the CDAP data platform. It defines core interfaces for authorization enforcement, privilege management, and access control that can be extended to integrate with enterprise security systems.
3

4
## Package Information
5

6
- **Package Name**: cdap-security-spi
7
- **Package Type**: maven
8
- **Group ID**: co.cask.cdap
9
- **Language**: Java
10
- **Installation**: Add dependency to your Maven pom.xml:
11

12
```xml
13
<dependency>
14
  <groupId>co.cask.cdap</groupId>
15
  <artifactId>cdap-security-spi</artifactId>
16
  <version>5.1.2</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
// Core authorization interfaces
24
import co.cask.cdap.security.spi.authorization.Authorizer;
25
import co.cask.cdap.security.spi.authorization.AuthorizationEnforcer;
26
import co.cask.cdap.security.spi.authorization.AuthorizationContext;
27
import co.cask.cdap.security.spi.authorization.PrivilegesManager;
28

29
// Authentication context
30
import co.cask.cdap.security.spi.authentication.AuthenticationContext;
31
import co.cask.cdap.security.spi.authentication.SecurityRequestContext;
32

33
// Exception classes  
34
import co.cask.cdap.security.spi.authorization.UnauthorizedException;
35
import co.cask.cdap.security.spi.authorization.AlreadyExistsException;
36

37
// Base implementations
38
import co.cask.cdap.security.spi.authorization.AbstractAuthorizer;
39
import co.cask.cdap.security.spi.authorization.NoOpAuthorizer;
40
```
41

42
## Basic Usage
43

44
### Implementing a Custom Authorizer
45

46
```java
47
import co.cask.cdap.security.spi.authorization.AbstractAuthorizer;
48
import co.cask.cdap.security.spi.authorization.AuthorizationContext;
49
import co.cask.cdap.proto.security.Action;
50
import co.cask.cdap.proto.security.Principal;
51
import co.cask.cdap.proto.id.EntityId;
52

53
public class CustomAuthorizer extends AbstractAuthorizer {
54

55
  @Override
56
  public void initialize(AuthorizationContext context) throws Exception {
57
    // Initialize your authorization backend
58
    Properties config = context.getExtensionProperties();
59
    // Setup connection to your authorization system
60
  }
61

62
  @Override
63
  public void enforce(EntityId entity, Principal principal, Set<Action> actions) 
64
      throws Exception {
65
    // Check if principal has permissions for actions on entity
66
    // Throw UnauthorizedException if not authorized
67
    if (!hasPermission(entity, principal, actions)) {
68
      throw new UnauthorizedException(principal, actions, entity);
69
    }
70
  }
71

72
  @Override
73
  public void grant(Authorizable authorizable, Principal principal, Set<Action> actions) 
74
      throws Exception {
75
    // Grant permissions to principal on authorizable
76
  }
77

78
  // Implement other required methods...
79
}
80
```
81

82
### Using Security Request Context
83

84
```java
85
import co.cask.cdap.security.spi.authentication.SecurityRequestContext;
86
import co.cask.cdap.proto.security.Principal;
87

88
// Set user context for current thread
89
SecurityRequestContext.setUserId("alice");
90
SecurityRequestContext.setUserIP("192.168.1.100");
91

92
// Get user information
93
String userId = SecurityRequestContext.getUserId();
94
String userIP = SecurityRequestContext.getUserIP();
95

96
// Convert to Principal
97
Principal principal = SecurityRequestContext.toPrincipal();
98
```
99

100
## Architecture
101

102
The CDAP Security SPI follows a modular architecture with distinct responsibilities:
103

104
- **Authorization Layer**: Core authorization enforcement and privilege management
105
- **Authentication Layer**: User identification and context management  
106
- **Exception Layer**: Structured error handling with HTTP status codes
107
- **Extension Points**: Abstract base classes for custom implementations
108

109
## Capabilities
110

111
### Authorization Management
112

113
Core authorization interfaces for implementing custom authorization backends with role-based access control and privilege management.
114

115
```java { .api }
116
@Beta
117
interface Authorizer extends PrivilegesFetcher, PrivilegesManager, AuthorizationEnforcer {
118
  void initialize(AuthorizationContext context) throws Exception;
119
  void createRole(Role role) throws Exception;
120
  void dropRole(Role role) throws Exception;
121
  Set<Role> listAllRoles() throws Exception;
122
  void destroy() throws Exception;
123
}
124
```
125

126
```java { .api }
127
@Beta
128
interface AuthorizationEnforcer {
129
  void enforce(EntityId entity, Principal principal, Action action) throws Exception;
130
  void enforce(EntityId entity, Principal principal, Set<Action> actions) throws Exception;
131
  Set<? extends EntityId> isVisible(Set<? extends EntityId> entityIds, Principal principal) throws Exception;
132
}
133
```
134

135
[Authorization Management](./authorization.md)
136

137
### Authentication Context
138

139
Thread-local authentication context management and user identification for authorization requests.
140

141
```java { .api }
142
interface AuthenticationContext {
143
  Principal getPrincipal();
144
}
145
```
146

147
```java { .api }
148
class SecurityRequestContext {
149
  static String getUserId();
150
  static void setUserId(String userIdParam);
151
  static Principal toPrincipal();
152
}
153
```
154

155
[Authentication Context](./authentication.md)
156

157
### Exception Handling
158

159
Structured exception hierarchy with HTTP status codes for proper error handling in web contexts.
160

161
```java { .api }
162
class UnauthorizedException extends RuntimeException implements HttpErrorStatusProvider {
163
  UnauthorizedException(Principal principal, Action action, EntityId entityId);
164
  UnauthorizedException(Principal principal, Set<Action> actions, EntityId entityId);
165
  int getStatusCode(); // Returns 403
166
}
167
```
168

169
[Exception Handling](./exceptions.md)
170

171
## Types
172

173
### Core Types
174

175
```java { .api }
176
// From cdap-proto dependency
177
class Principal {
178
  Principal(String name, PrincipalType type);
179
  String getName();
180
  PrincipalType getType();
181
}
182

183
enum PrincipalType {
184
  USER, GROUP, ROLE
185
}
186

187
class Role {
188
  Role(String name);
189
  String getName();
190
}
191

192
interface EntityId {
193
  // Entity identifier for CDAP resources
194
}
195

196
enum Action {
197
  READ, WRITE, EXECUTE, ADMIN
198
  // Actions that can be performed on entities
199
}
200

201
class Privilege {
202
  Privilege(Authorizable authorizable, Action action);
203
  Authorizable getAuthorizable();
204
  Action getAction();
205
}
206

207
interface Authorizable {
208
  // Represents an entity that can have privileges granted on it
209
}
210

211
interface HttpErrorStatusProvider {
212
  /**
213
   * Get the HTTP status code for this error condition.
214
   * 
215
   * @return HTTP status code (e.g., 403, 404, 409, 400)
216
   */
217
  int getStatusCode();
218
}
219
```
220

221
### Extension Context
222

223
```java { .api }
224
interface AuthorizationContext extends DatasetContext, Admin, Transactional, 
225
    AuthenticationContext, SecureStore {
226
  Properties getExtensionProperties();
227
  // Messaging methods throw UnsupportedOperationException
228
}
229
```