0
# Apache Ranger Plugins Common
1

2
Apache Ranger Plugins Common is a foundational Java library that provides shared functionality for all Apache Ranger plugins. It enables consistent security policy enforcement across diverse big data ecosystems through a comprehensive set of common components including plugin architecture, administrative client interfaces, policy models, context enrichers, audit facilities, and authorization utilities.
3

4
## Package Information
5

6
- **Package Name**: ranger-plugins-common
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.apache.ranger
10
- **Artifact ID**: ranger-plugins-common
11
- **Installation**: Add to pom.xml:
12

13
```xml
14
<dependency>
15
  <groupId>org.apache.ranger</groupId>
16
  <artifactId>ranger-plugins-common</artifactId>
17
  <version>2.7.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.apache.ranger.plugin.service.RangerBasePlugin;
25
import org.apache.ranger.admin.client.RangerAdminClient;
26
import org.apache.ranger.plugin.policyengine.RangerAccessRequest;
27
import org.apache.ranger.plugin.policyengine.RangerAccessRequestImpl;
28
import org.apache.ranger.plugin.policyengine.RangerAccessResourceImpl;
29
import org.apache.ranger.plugin.policyengine.RangerAccessResult;
30
import org.apache.ranger.plugin.model.RangerPolicy;
31
import org.apache.ranger.plugin.model.RangerServiceDef;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.apache.ranger.plugin.service.RangerBasePlugin;
38
import org.apache.ranger.plugin.policyengine.RangerAccessRequestImpl;
39
import org.apache.ranger.plugin.policyengine.RangerAccessResourceImpl;
40

41
// Initialize plugin
42
RangerBasePlugin plugin = new RangerBasePlugin("hdfs", "MyHDFSPlugin");
43
plugin.init();
44

45
// Create access request
46
RangerAccessResourceImpl resource = new RangerAccessResourceImpl();
47
resource.setValue("path", "/user/data/file.txt");
48

49
RangerAccessRequestImpl request = new RangerAccessRequestImpl();
50
request.setResource(resource);
51
request.setAccessType("read");
52
request.setUser("alice");
53

54
// Evaluate access
55
RangerAccessResult result = plugin.isAccessAllowed(request);
56
if (result.getIsAllowed()) {
57
    System.out.println("Access granted");
58
} else {
59
    System.out.println("Access denied: " + result.getReason());
60
}
61

62
// Note: Auditing is handled automatically during access evaluation
63
// Access results contain audit information processed by the plugin's audit providers
64
```
65

66
## Architecture
67

68
Apache Ranger Plugins Common is built around several key architectural components:
69

70
- **Plugin Framework**: Core plugin architecture with `RangerBasePlugin` providing lifecycle management, policy evaluation, and audit logging
71
- **Policy Engine**: `RangerPolicyEngine` for evaluating access policies with support for different policy types (access, data masking, row filtering)
72
- **Admin Client**: `RangerAdminClient` interface and implementations for communicating with Ranger Admin server
73
- **Model Objects**: Rich domain models (`RangerPolicy`, `RangerServiceDef`, `RangerRole`) representing security policies and service definitions
74
- **Context Enrichment**: Pluggable context enrichers for attribute-based access control and dynamic policy evaluation
75
- **Resource Matching**: Flexible resource matching framework supporting wildcards, regex, and custom matchers
76
- **Audit Framework**: Comprehensive audit logging with pluggable audit handlers and event processing
77

78
## Capabilities
79

80
### Plugin Services
81

82
Core plugin framework providing the main entry point for Ranger plugins, with lifecycle management, policy evaluation, and audit integration.
83

84
```java { .api }
85
public class RangerBasePlugin {
86
    public RangerBasePlugin(String serviceType, String appId);
87
    public RangerBasePlugin(String serviceType, String serviceName, String appId);
88
    public RangerBasePlugin(RangerPluginConfig pluginConfig);
89
    public void init();
90
    public RangerAccessResult isAccessAllowed(RangerAccessRequest request);
91
    public Collection<RangerAccessResult> isAccessAllowed(Collection<RangerAccessRequest> requests, RangerAccessResultProcessor resultProcessor);
92
    public RangerAccessResult evalDataMaskPolicies(RangerAccessRequest request, RangerAccessResultProcessor resultProcessor);
93
    public RangerAccessResult evalRowFilterPolicies(RangerAccessRequest request, RangerAccessResultProcessor resultProcessor);
94
    public RangerResourceACLs getResourceACLs(RangerAccessRequest request);
95
    public void refreshPoliciesAndTags();
96
}
97
```
98

99
[Plugin Services](./plugin-services.md)
100

101
### Policy Engine
102

103
Policy evaluation engine that processes access requests against configured policies, supporting access control, data masking, and row filtering policies.
104

105
```java { .api }
106
public interface RangerPolicyEngine {
107
    RangerAccessResult evaluatePolicies(RangerAccessRequest request, int policyType, RangerAccessResultProcessor resultProcessor);
108
    Collection<RangerAccessResult> evaluatePolicies(Collection<RangerAccessRequest> requests, int policyType, RangerAccessResultProcessor resultProcessor);
109
    RangerResourceACLs getResourceACLs(RangerAccessRequest request);
110
}
111

112
public class RangerPolicyEngineImpl implements RangerPolicyEngine {
113
    public RangerPolicyEngineImpl(ServicePolicies servicePolicies, RangerPluginContext pluginContext, RangerRoles roles);
114
}
115
```
116

117
[Policy Engine](./policy-engine.md)
118

119
### Admin Client
120

121
Client interface for communicating with Ranger Admin server to retrieve policies, roles, and service definitions, and to perform administrative operations.
122

123
```java { .api }
124
public interface RangerAdminClient {
125
    void init(String serviceName, String appId, String configPropertyPrefix, Configuration config);
126
    ServicePolicies getServicePoliciesIfUpdated(long lastKnownVersion, long lastActivationTimeInMillis) throws Exception;
127
    RangerRoles getRolesIfUpdated(long lastKnownRoleVersion, long lastActivationTimeInMills) throws Exception;
128
    void grantAccess(GrantRevokeRequest request) throws Exception;
129
    void revokeAccess(GrantRevokeRequest request) throws Exception;
130
}
131

132
public class RangerAdminRESTClient extends AbstractRangerAdminClient {
133
    public void init(String serviceName, String appId, String propertyPrefix, Configuration config);
134
}
135
```
136

137
[Admin Client](./admin-client.md)
138

139
### Policy Models
140

141
Rich domain models representing policies, service definitions, roles, and other security constructs with full serialization support.
142

143
```java { .api }
144
public class RangerPolicy extends RangerBaseModelObject {
145
    public static final int POLICY_TYPE_ACCESS = 0;
146
    public static final int POLICY_TYPE_DATAMASK = 1;
147
    public static final int POLICY_TYPE_ROWFILTER = 2;
148
    
149
    public String getService();
150
    public String getName();
151
    public Integer getPolicyType();
152
    public Map<String, RangerPolicyResource> getResources();
153
    public List<RangerPolicyItem> getPolicyItems();
154
}
155

156
public class RangerServiceDef extends RangerBaseModelObject {
157
    public String getName();
158
    public List<RangerResourceDef> getResources();
159
    public List<RangerAccessTypeDef> getAccessTypes();
160
}
161
```
162

163
[Policy Models](./policy-models.md)
164

165
### Context Enrichment
166

167
Pluggable context enrichment framework for enhancing access requests with additional attributes for policy evaluation.
168

169
```java { .api }
170
public interface RangerContextEnricher {
171
    void init();
172
    void enrich(RangerAccessRequest request);
173
}
174

175
public abstract class RangerAbstractContextEnricher implements RangerContextEnricher {
176
    // Base implementation with common functionality
177
}
178

179
public class RangerTagEnricher extends RangerAbstractContextEnricher {
180
    // Tag-based context enrichment
181
}
182
```
183

184
[Context Enrichment](./context-enrichment.md)
185

186
### Resource Matching
187

188
Flexible resource matching framework supporting various matching strategies including wildcards, regular expressions, and custom matchers.
189

190
```java { .api }
191
public interface RangerResourceMatcher {
192
    void init();
193
    boolean isMatch(RangerAccessResource resource, Map<String, Object> evalContext);
194
    boolean isCompleteMatch(RangerAccessResource resource, Map<String, Object> evalContext);
195
}
196

197
public class RangerDefaultResourceMatcher extends RangerAbstractResourceMatcher {
198
    // Default wildcard-based matching
199
}
200

201
public class RangerPathResourceMatcher extends RangerAbstractResourceMatcher {
202
    // Path-specific matching with hierarchy support
203
}
204
```
205

206
[Resource Matching](./resource-matching.md)
207

208
### Authentication & Security
209

210
Kerberos authentication support and security utilities for secure communication and credential management.
211

212
```java { .api }
213
public class SecureClientLogin {
214
    public static Subject loginUserFromKeytab(String user, String path) throws IOException;
215
    public static Subject loginUserWithPassword(String user, String password) throws IOException;
216
    public static boolean isKerberosCredentialExists(String principal, String keytabPath);
217
}
218
```
219

220
[Authentication & Security](./authentication-security.md)
221

222
## Types
223

224
### Core Request/Response Types
225

226
```java { .api }
227
public interface RangerAccessRequest {
228
    RangerAccessResource getResource();
229
    String getAccessType();
230
    String getUser();
231
    Set<String> getUserGroups();
232
    Set<String> getUserRoles();
233
    Date getAccessTime();
234
    String getClientIPAddress();
235
    Map<String, Object> getContext();
236
}
237

238
public class RangerAccessRequestImpl implements RangerAccessRequest {
239
    public RangerAccessRequestImpl();
240
    public RangerAccessRequestImpl(RangerAccessResource resource, String accessType, String user, Set<String> userGroups, Set<String> userRoles);
241
}
242

243
public interface RangerAccessResource {
244
    String getOwnerUser();
245
    boolean exists(String name);
246
    String getValue(String name);
247
    String[] getValues(String name);
248
    Set<String> getKeys();
249
    Map<String, Object> getAsMap();
250
}
251

252
public class RangerAccessResult {
253
    public String getServiceName();
254
    public RangerAccessRequest getAccessRequest();
255
    public boolean getIsAllowed();
256
    public boolean getIsAudited();
257
    public long getPolicyId();
258
    public String getReason();
259
}
260
```
261

262
### Configuration Types
263

264
```java { .api }
265
public class RangerPluginConfig extends RangerConfiguration {
266
    public RangerPluginConfig(String serviceType, String serviceName, String appId, String clusterName, String clusterType, PolicyRefresher policyRefresher);
267
    public String getServiceType();
268
    public String getServiceName();
269
    public String getAppId();
270
}
271

272
public class ServicePolicies {
273
    public String getServiceName();
274
    public Long getPolicyVersion();
275
    public List<RangerPolicy> getPolicies();
276
    public RangerServiceDef getServiceDef();
277
}
278
```
279

280
### Grant/Revoke Types
281

282
```java { .api }
283
public class GrantRevokeRequest {
284
    public String getGrantor();
285
    public Map<String, String> getResource();
286
    public Set<String> getUsers();
287
    public Set<String> getGroups();
288
    public Set<String> getAccessTypes();
289
    public Boolean getIsRecursive();
290
}
291

292
public class GrantRevokeRoleRequest {
293
    // Role-based grant/revoke operations
294
}
295
```