0
# Admin Client
1

2
Client interface for communicating with Ranger Admin server to retrieve policies, roles, service definitions, and perform administrative operations like granting and revoking access permissions.
3

4
## Capabilities
5

6
### RangerAdminClient
7

8
Main interface for communicating with Ranger Admin server.
9

10
```java { .api }
11
/**
12
 * Interface for communicating with Ranger Admin server
13
 */
14
public interface RangerAdminClient {
15
    /**
16
     * Initialize the admin client
17
     * @param serviceName - Name of the service
18
     * @param appId - Application identifier
19
     * @param configPropertyPrefix - Configuration property prefix
20
     * @param config - Hadoop configuration
21
     */
22
    void init(String serviceName, String appId, String configPropertyPrefix, Configuration config);
23
    
24
    /**
25
     * Get service policies if updated since last known version
26
     * @param lastKnownVersion - Last known policy version
27
     * @param lastActivationTimeInMillis - Last activation time
28
     * @return Service policies if updated, null otherwise
29
     * @throws Exception if communication fails
30
     */
31
    ServicePolicies getServicePoliciesIfUpdated(long lastKnownVersion, long lastActivationTimeInMillis) throws Exception;
32
    
33
    /**
34
     * Get roles if updated since last known version
35
     * @param lastKnownRoleVersion - Last known role version
36
     * @param lastActivationTimeInMillis - Last activation time
37
     * @return Ranger roles if updated, null otherwise
38
     * @throws Exception if communication fails
39
     */
40
    RangerRoles getRolesIfUpdated(long lastKnownRoleVersion, long lastActivationTimeInMillis) throws Exception;
41
    
42
    /**
43
     * Create a new role
44
     * @param request - Role creation request
45
     * @return Created role
46
     * @throws Exception if creation fails
47
     */
48
    RangerRole createRole(RangerRole request) throws Exception;
49
    
50
    /**
51
     * Drop an existing role
52
     * @param execUser - Executing user
53
     * @param roleName - Name of role to drop
54
     * @throws Exception if drop fails
55
     */
56
    void dropRole(String execUser, String roleName) throws Exception;
57
    
58
    /**
59
     * Get all roles
60
     * @param execUser - Executing user
61
     * @return List of all role names
62
     * @throws Exception if retrieval fails
63
     */
64
    List<String> getAllRoles(String execUser) throws Exception;
65
    
66
    /**
67
     * Get roles for a specific user
68
     * @param execUser - User to get roles for
69
     * @return List of role names for the user
70
     * @throws Exception if retrieval fails
71
     */
72
    List<String> getUserRoles(String execUser) throws Exception;
73
    
74
    /**
75
     * Get a specific role
76
     * @param execUser - Executing user
77
     * @param roleName - Name of role to retrieve
78
     * @return Role information
79
     * @throws Exception if retrieval fails
80
     */
81
    RangerRole getRole(String execUser, String roleName) throws Exception;
82
    
83
    /**
84
     * Grant a role to users/groups
85
     * @param request - Role grant request
86
     * @throws Exception if grant fails
87
     */
88
    void grantRole(GrantRevokeRoleRequest request) throws Exception;
89
    
90
    /**
91
     * Revoke a role from users/groups
92
     * @param request - Role revoke request
93
     * @throws Exception if revoke fails
94
     */
95
    void revokeRole(GrantRevokeRoleRequest request) throws Exception;
96
    
97
    /**
98
     * Grant access permissions
99
     * @param request - Access grant request
100
     * @throws Exception if grant fails
101
     */
102
    void grantAccess(GrantRevokeRequest request) throws Exception;
103
    
104
    /**
105
     * Revoke access permissions
106
     * @param request - Access revoke request
107
     * @throws Exception if revoke fails
108
     */
109
    void revokeAccess(GrantRevokeRequest request) throws Exception;
110
    
111
    /**
112
     * Get service tags if updated since last known version
113
     * @param lastKnownVersion - Last known tag version
114
     * @param lastActivationTimeInMillis - Last activation time
115
     * @return Service tags if updated, null otherwise
116
     * @throws Exception if retrieval fails
117
     */
118
    ServiceTags getServiceTagsIfUpdated(long lastKnownVersion, long lastActivationTimeInMillis) throws Exception;
119
    
120
    /**
121
     * Get tag types matching a pattern
122
     * @param tagTypePattern - Pattern to match tag types
123
     * @return List of matching tag type names
124
     * @throws Exception if retrieval fails
125
     */
126
    List<String> getTagTypes(String tagTypePattern) throws Exception;
127
    
128
    /**
129
     * Get user store if updated since last known version
130
     * @param lastKnownUserStoreVersion - Last known user store version
131
     * @param lastActivationTimeInMillis - Last activation time
132
     * @return User store if updated, null otherwise
133
     * @throws Exception if retrieval fails
134
     */
135
    RangerUserStore getUserStoreIfUpdated(long lastKnownUserStoreVersion, long lastActivationTimeInMillis) throws Exception;
136
}
137
```
138

139
### AbstractRangerAdminClient
140

141
Abstract base class providing common admin client functionality.
142

143
```java { .api }
144
/**
145
 * Abstract base implementation of RangerAdminClient
146
 */
147
public abstract class AbstractRangerAdminClient implements RangerAdminClient {
148
    /**
149
     * Gson instance for JSON processing
150
     */
151
    protected Gson gson;
152
    
153
    /**
154
     * Initialize the admin client
155
     */
156
    public void init(String serviceName, String appId, String configPropertyPrefix, Configuration config);
157
    
158
    /**
159
     * Check if Kerberos is enabled for the user
160
     * @param user - User group information
161
     * @return True if Kerberos is enabled
162
     */
163
    public boolean isKerberosEnabled(UserGroupInformation user);
164
    
165
    // All interface methods with default implementations
166
    public ServicePolicies getServicePoliciesIfUpdated(long lastKnownVersion, long lastActivationTimeInMillis) throws Exception;
167
    public RangerRoles getRolesIfUpdated(long lastKnownRoleVersion, long lastActivationTimeInMillis) throws Exception;
168
    public RangerRole createRole(RangerRole request) throws Exception;
169
    public void dropRole(String execUser, String roleName) throws Exception;
170
    public List<String> getAllRoles(String execUser) throws Exception;
171
    public List<String> getUserRoles(String execUser) throws Exception;
172
    public RangerRole getRole(String execUser, String roleName) throws Exception;
173
    public void grantRole(GrantRevokeRoleRequest request) throws Exception;
174
    public void revokeRole(GrantRevokeRoleRequest request) throws Exception;
175
    public void grantAccess(GrantRevokeRequest request) throws Exception;
176
    public void revokeAccess(GrantRevokeRequest request) throws Exception;
177
    public ServiceTags getServiceTagsIfUpdated(long lastKnownVersion, long lastActivationTimeInMillis) throws Exception;
178
    public List<String> getTagTypes(String tagTypePattern) throws Exception;
179
    public RangerUserStore getUserStoreIfUpdated(long lastKnownUserStoreVersion, long lastActivationTimeInMillis) throws Exception;
180
}
181
```
182

183
### RangerAdminRESTClient
184

185
REST client implementation for communicating with Ranger Admin server.
186

187
```java { .api }
188
/**
189
 * REST client implementation for Ranger Admin communication
190
 */
191
public class RangerAdminRESTClient extends AbstractRangerAdminClient {
192
    /**
193
     * Initialize the REST client with configuration
194
     * @param serviceName - Name of the service
195
     * @param appId - Application identifier
196
     * @param propertyPrefix - Configuration property prefix
197
     * @param config - Hadoop configuration
198
     */
199
    public void init(String serviceName, String appId, String propertyPrefix, Configuration config);
200
}
201
```
202

203
### Grant/Revoke Data Types
204

205
Data transfer objects for grant and revoke operations.
206

207
```java { .api }
208
/**
209
 * Data for grant/revoke operations
210
 */
211
public class GrantRevokeData implements java.io.Serializable {
212
    /**
213
     * Default constructor
214
     */
215
    public GrantRevokeData();
216
    
217
    /**
218
     * Get the grantor user
219
     * @return Grantor username
220
     */
221
    public String getGrantor();
222
    
223
    /**
224
     * Set the grantor user
225
     * @param grantor - Grantor username
226
     */
227
    public void setGrantor(String grantor);
228
    
229
    /**
230
     * Get repository name
231
     * @return Repository name
232
     */
233
    public String getRepositoryName();
234
    
235
    /**
236
     * Set repository name
237
     * @param repositoryName - Repository name
238
     */
239
    public void setRepositoryName(String repositoryName);
240
    
241
    /**
242
     * Get repository type
243
     * @return Repository type
244
     */
245
    public String getRepositoryType();
246
    
247
    /**
248
     * Set repository type
249
     * @param repositoryType - Repository type
250
     */
251
    public void setRepositoryType(String repositoryType);
252
    
253
    /**
254
     * Get databases
255
     * @return Databases string
256
     */
257
    public String getDatabases();
258
    
259
    /**
260
     * Set databases
261
     * @param databases - Databases string
262
     */
263
    public void setDatabases(String databases);
264
    
265
    /**
266
     * Get tables
267
     * @return Tables string
268
     */
269
    public String getTables();
270
    
271
    /**
272
     * Set tables
273
     * @param tables - Tables string
274
     */
275
    public void setTables(String tables);
276
    
277
    /**
278
     * Get columns
279
     * @return Columns string
280
     */
281
    public String getColumns();
282
    
283
    /**
284
     * Set columns
285
     * @param columns - Columns string
286
     */
287
    public void setColumns(String columns);
288
    
289
    /**
290
     * Get column families
291
     * @return Column families string
292
     */
293
    public String getColumnFamilies();
294
    
295
    /**
296
     * Set column families
297
     * @param columnFamilies - Column families string
298
     */
299
    public void setColumnFamilies(String columnFamilies);
300
    
301
    /**
302
     * Get permission mappings
303
     * @return List of permission mappings
304
     */
305
    public List<PermMap> getPermMapList();
306
    
307
    /**
308
     * Set permission mappings
309
     * @param permMapList - List of permission mappings
310
     */
311
    public void setPermMapList(List<PermMap> permMapList);
312
    
313
    /**
314
     * Set Hive-specific data
315
     * @param grantor - Grantor user
316
     * @param repositoryName - Repository name
317
     * @param databases - Database names
318
     * @param tables - Table names
319
     * @param columns - Column names
320
     * @param permMap - Permission mapping
321
     */
322
    public void setHiveData(String grantor, String repositoryName, String databases, String tables, String columns, PermMap permMap);
323
    
324
    /**
325
     * Set HBase-specific data
326
     * @param grantor - Grantor user
327
     * @param repositoryName - Repository name
328
     * @param tables - Table names
329
     * @param columns - Column names
330
     * @param columnFamilies - Column family names
331
     * @param permMap - Permission mapping
332
     */
333
    public void setHBaseData(String grantor, String repositoryName, String tables, String columns, String columnFamilies, PermMap permMap);
334
    
335
    /**
336
     * Convert to JSON
337
     * @return JSON string representation
338
     */
339
    public String toJson();
340
    
341
    /**
342
     * Permission mapping class
343
     */
344
    public static class PermMap implements java.io.Serializable {
345
        /**
346
         * Default constructor
347
         */
348
        public PermMap();
349
        
350
        /**
351
         * Constructor with single user, group, and permission
352
         * @param user - Username
353
         * @param group - Group name
354
         * @param perm - Permission
355
         */
356
        public PermMap(String user, String group, String perm);
357
        
358
        /**
359
         * Constructor with lists of users, groups, and permissions
360
         * @param userList - List of users
361
         * @param groupList - List of groups
362
         * @param permList - List of permissions
363
         */
364
        public PermMap(List<String> userList, List<String> groupList, List<String> permList);
365
        
366
        /**
367
         * Get user list
368
         * @return List of users
369
         */
370
        public List<String> getUserList();
371
        
372
        /**
373
         * Get group list
374
         * @return List of groups
375
         */
376
        public List<String> getGroupList();
377
        
378
        /**
379
         * Get permission list
380
         * @return List of permissions
381
         */
382
        public List<String> getPermList();
383
        
384
        /**
385
         * Add a user
386
         * @param user - Username to add
387
         */
388
        public void addUser(String user);
389
        
390
        /**
391
         * Add a group
392
         * @param group - Group name to add
393
         */
394
        public void addGroup(String group);
395
        
396
        /**
397
         * Add a permission
398
         * @param perm - Permission to add
399
         */
400
        public void addPerm(String perm);
401
        
402
        /**
403
         * Convert to JSON
404
         * @return JSON string representation
405
         */
406
        public String toJson();
407
    }
408
}
409
```
410

411
### REST Response
412

413
Response object for REST operations.
414

415
```java { .api }
416
/**
417
 * REST response object
418
 */
419
public class RESTResponse implements java.io.Serializable {
420
    /**
421
     * Success status code
422
     */
423
    public static final int STATUS_SUCCESS = 0;
424
    
425
    /**
426
     * Error status code
427
     */
428
    public static final int STATUS_ERROR = 1;
429
    
430
    /**
431
     * Validation error status code
432
     */
433
    public static final int STATUS_VALIDATION = 2;
434
    
435
    /**
436
     * Warning status code
437
     */
438
    public static final int STATUS_WARN = 3;
439
    
440
    /**
441
     * Info status code
442
     */
443
    public static final int STATUS_INFO = 4;
444
    
445
    /**
446
     * Partial success status code
447
     */
448
    public static final int STATUS_PARTIAL_SUCCESS = 5;
449
    
450
    /**
451
     * Maximum response status value
452
     */
453
    public static final int ResponseStatus_MAX = 5;
454
    
455
    /**
456
     * Get HTTP status code
457
     * @return HTTP status code
458
     */
459
    public int getHttpStatusCode();
460
    
461
    /**
462
     * Set HTTP status code
463
     * @param httpStatusCode - HTTP status code
464
     */
465
    public void setHttpStatusCode(int httpStatusCode);
466
    
467
    /**
468
     * Get status code
469
     * @return Status code
470
     */
471
    public int getStatusCode();
472
    
473
    /**
474
     * Set status code
475
     * @param statusCode - Status code
476
     */
477
    public void setStatusCode(int statusCode);
478
    
479
    /**
480
     * Get message description
481
     * @return Message description
482
     */
483
    public String getMsgDesc();
484
    
485
    /**
486
     * Set message description
487
     * @param msgDesc - Message description
488
     */
489
    public void setMsgDesc(String msgDesc);
490
    
491
    /**
492
     * Get message list
493
     * @return List of messages
494
     */
495
    public List<Message> getMessageList();
496
    
497
    /**
498
     * Set message list
499
     * @param messageList - List of messages
500
     */
501
    public void setMessageList(List<Message> messageList);
502
    
503
    /**
504
     * Get combined message
505
     * @return Combined message string
506
     */
507
    public String getMessage();
508
    
509
    /**
510
     * Create REST response from client response
511
     * @param response - Client response
512
     * @return REST response
513
     */
514
    public static RESTResponse fromClientResponse(ClientResponse response);
515
    
516
    /**
517
     * Convert to JSON
518
     * @return JSON string representation
519
     */
520
    public String toJson();
521
    
522
    /**
523
     * Create from JSON
524
     * @param jsonString - JSON string
525
     * @return REST response
526
     */
527
    public static RESTResponse fromJson(String jsonString);
528
    
529
    /**
530
     * Message class for REST responses
531
     */
532
    public static class Message implements java.io.Serializable {
533
        /**
534
         * Get message name
535
         * @return Message name
536
         */
537
        public String getName();
538
        
539
        /**
540
         * Set message name
541
         * @param name - Message name
542
         */
543
        public void setName(String name);
544
        
545
        /**
546
         * Get resource bundle key
547
         * @return Resource bundle key
548
         */
549
        public String getRbKey();
550
        
551
        /**
552
         * Set resource bundle key
553
         * @param rbKey - Resource bundle key
554
         */
555
        public void setRbKey(String rbKey);
556
        
557
        /**
558
         * Get message text
559
         * @return Message text
560
         */
561
        public String getMessage();
562
        
563
        /**
564
         * Set message text
565
         * @param message - Message text
566
         */
567
        public void setMessage(String message);
568
        
569
        /**
570
         * Get object ID
571
         * @return Object ID
572
         */
573
        public Long getObjectId();
574
        
575
        /**
576
         * Set object ID
577
         * @param objectId - Object ID
578
         */
579
        public void setObjectId(Long objectId);
580
        
581
        /**
582
         * Get field name
583
         * @return Field name
584
         */
585
        public String getFieldName();
586
        
587
        /**
588
         * Set field name
589
         * @param fieldName - Field name
590
         */
591
        public void setFieldName(String fieldName);
592
        
593
        /**
594
         * Convert to JSON
595
         * @return JSON string representation
596
         */
597
        public String toJson();
598
    }
599
}
600
```
601

602
**Usage Examples:**
603

604
```java
605
import org.apache.ranger.admin.client.RangerAdminRESTClient;
606
import org.apache.ranger.plugin.util.GrantRevokeRequest;
607
import org.apache.ranger.plugin.util.ServicePolicies;
608
import org.apache.hadoop.conf.Configuration;
609

610
// Initialize admin client
611
RangerAdminRESTClient adminClient = new RangerAdminRESTClient();
612
Configuration config = new Configuration();
613
config.set("ranger.plugin.hdfs.service.name", "hdfs-service");
614
config.set("ranger.plugin.hdfs.policy.rest.url", "http://ranger-admin:6080");
615

616
adminClient.init("hdfs-service", "HDFSPlugin", "ranger.plugin.hdfs", config);
617

618
// Get policies
619
long lastKnownVersion = 0;
620
ServicePolicies policies = adminClient.getServicePoliciesIfUpdated(lastKnownVersion, System.currentTimeMillis());
621
if (policies != null) {
622
    System.out.println("Retrieved " + policies.getPolicies().size() + " policies");
623
    System.out.println("Policy version: " + policies.getPolicyVersion());
624
}
625

626
// Grant access
627
GrantRevokeRequest grantRequest = new GrantRevokeRequest();
628
grantRequest.setGrantor("admin");
629
grantRequest.setUsers(Set.of("alice", "bob"));
630
grantRequest.setGroups(Set.of("analysts"));
631
grantRequest.setAccessTypes(Set.of("read", "write"));
632

633
Map<String, String> resource = new HashMap<>();
634
resource.put("path", "/data/analytics/*");
635
grantRequest.setResource(resource);
636
grantRequest.setIsRecursive(true);
637

638
try {
639
    adminClient.grantAccess(grantRequest);
640
    System.out.println("Access granted successfully");
641
} catch (Exception e) {
642
    System.err.println("Failed to grant access: " + e.getMessage());
643
}
644

645
// Revoke access
646
GrantRevokeRequest revokeRequest = new GrantRevokeRequest();
647
revokeRequest.setGrantor("admin");
648
revokeRequest.setUsers(Set.of("alice"));
649
revokeRequest.setAccessTypes(Set.of("write"));
650
revokeRequest.setResource(resource);
651

652
try {
653
    adminClient.revokeAccess(revokeRequest);
654
    System.out.println("Access revoked successfully");
655
} catch (Exception e) {
656
    System.err.println("Failed to revoke access: " + e.getMessage());
657
}
658

659
// Get roles
660
try {
661
    List<String> allRoles = adminClient.getAllRoles("admin");
662
    System.out.println("Available roles: " + allRoles);
663
    
664
    List<String> userRoles = adminClient.getUserRoles("alice");
665
    System.out.println("Alice's roles: " + userRoles);
666
} catch (Exception e) {
667
    System.err.println("Failed to retrieve roles: " + e.getMessage());
668
}
669
```
670

671
## Configuration Properties
672

673
Common configuration properties for admin clients:
674

675
- `ranger.plugin.<service>.service.name`: Name of the Ranger service
676
- `ranger.plugin.<service>.policy.rest.url`: URL of Ranger Admin server
677
- `ranger.plugin.<service>.policy.rest.client.connection.timeoutMs`: Connection timeout
678
- `ranger.plugin.<service>.policy.rest.client.read.timeoutMs`: Read timeout
679
- `ranger.plugin.<service>.policy.pollIntervalMs`: Policy refresh interval
680

681
## Error Handling
682

683
Admin client operations can throw exceptions for various reasons:
684

685
- Network connectivity issues
686
- Authentication/authorization failures
687
- Invalid request parameters
688
- Server-side errors
689

690
Always wrap admin client calls in try-catch blocks and handle exceptions appropriately.