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