This document provides a general description of how to add a new component to Apache Ranger.
Apache Ranger has three main components:
Admin Tool -- Provides web interface & REST API for managing security policies
Custom Authorization Module for components -- Provides custom authorization within the (Hadoop) component to enforce the policies defined in Admin Tool
UserGroup synchronizer -- Enables the user/group information in Apache Ranger to synchronize with the Enterprise user/group information stored in LDAP or Active directory.
For supporting new component authorization using Apache Ranger, the component details needs to be added to Apache Ranger as follows:
Add component details to the Admin Tool
Develop a custom authorization module for the new component
Adding Component Details to the Admin Tool
The Apache Ranger Admin tool supports policy management via both a web interface (UI) and support for (public) REST API. In order to support a new component in both the UI and the Server, the Admin Tool needs to be modified.
Required UI changes to support the new component:
Add a new component template to the Policy Manager page (console home page):
Show new component on the policy manager page i.e home page[#!/policymanager]. Apache Ranger needs to add table template to policy manager page and make changes in corresponding JS files. Ranger also needs to create a new repository type enum to distinguish the component for which the repository/policy is created/updated.
For example: Add a table template to PolicyManagerLayout_tmpl.html file to view the new component on the Policy Manager page and make changes in the PolicyManagerLayout.js file related to the new componen, such as passing knox repository collection data to the PolicyManagerLayout_tmpl template. Also create a new repository type enum (for example, ASSET_KNOX) in the XAEnums.js file.
Add new configuration information to the Repository Form:
Add new configuration fields to Repository Form [AssetForm.js] as per new component configuration information. This will cause the display of new configuration fields in the corresponding repository Create/Update page. Please note that the AssetForm.js is a common file for every component to create/update the repository.
For example: Add new field(configuration) information to AssetForm.js and AssetForm_tmpl.js.
Add a new Policy Listing page:
Add a new policy listing page for the new component in the View Policy list. For example: Create a new KnoxTableLayout.js file and add JS-related changes as per the old component[HiveTableLayout.js] to the View Policy listing. Also create a template page, KnoxTableLayout_tmpl.html.
Add a new Policy Create/Update page:
Add a Policy Create/Update page for the new component. Also add a policy form JS file and its template to handle all policy form-related actions for the new component. For example: Create a new KnoxPolicyCreate.js file for Create/Update Knox Policy. Create a KnoxPolicyForm.js file to add knox policy fields information. Also create a corresponding KnoxPolicyForm_tmpl.html template.
Other file changes, as needed:
Make changes in existing common files as per our new component like Router.js, Controller.js, XAUtils.js, FormInputList.js, UserPermissionList.js, XAEnums.js, etc.
Required server changes for the new component:
Let's assume that Apache Ranger has three components supported in their portal and we want to introduce one new component, Knox:
Create New Repository Type
If Apache Ranger is introducing new component i.e Knox, then they will add one new repository type for knox. i.e repositoryType = “Knox”. On the basis of repository type, while creating/updating repository/policy, Apache Ranger will distinguish for which component this repository/policy is created/updated.
Add new required parameters in existig objects and populate objects
For Policy Creation/Update of any component (i.e HDFS, Hive, Hbase), Apache Ranger uses only one common object, `VXPolicy.` The same goes for the Repository Creation/Update of any component: Apache Ranger uses only one common object `VXRepository.` As Apache Ranger has three components, it will have all the required parameters of all of those three components in `VXPolicy/VXRepository.` But for Knox, Apache Ranger requires some different parameters which are not there in previous components. Thus, it will add only required parameters into `VXPolicy/VXRepository` object. When a user sends a request to the Knox create/update policy, they will only send the parameters that are required for Knox to create/update the VXPolicy object.
After adding new parameters into VXPolixy/VXRepository, Apache Ranger populates the newly-added parameters in corresponding services, so that it can map those objects with Entity Object.
Add newly-added fields (into database table) related parameters into entity object and populate them
As Apache Ranger is using JPA-EclipseLink for database mapping into java, it is necessary to update the Entity object. For example, if for Knox policy Apache Ranger has added two new fields (`topology` and `service`) into db table `x_resource`, it will also have to update the entity object of table (i.e `XXResource`), since it is altering table structure.
After updating the entity object Apache Ranger will populate newly-added parameters in corresponding services (i.e XResourceService), so that it can communicate with the client using the updated entity object.
Change middleware code business logic
After adding and populating newly required parameters for new component, Apache Ranger will have to write business logic into file `AssetMgr`, where it may also need to do some minor changes. For example, if it wants to create a default policy while creating the Repository, then on the basis of repositoryType, Apache Ranger will create one default policy for the given repository. Everything else will work fine, as it is common for all components.
Required database changes for the new component:
For repository and policy management, Apache Ranger includes the following tables:
x_asset (for repository)
x_resource (for repository)
As written above, if Apache Ranger is introducing new component then it is not required to create individual table in database for each component. Apache Ranger has common tables for all components.
If Apache Ranger has three components and wants to introduce a fourth one, then it will add required fields into these two tables and will map accordingly with java object. For example, for Knox, Apache Ranger will add two fields (`topology`, `service`) into `x_resource`. After this, it will be able to perform CRUD operation of policy and repository for our new component, and also for previous components.
