CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apache-ranger--ranger-plugins-common

Common library for Apache Ranger plugins providing shared functionality, models, and utilities for security policy enforcement across various big data components.

—

Pending
Overview
Eval results
Files

context-enrichment.mddocs/

Context Enrichment

Pluggable context enrichment framework for enhancing access requests with additional attributes for policy evaluation. Context enrichers add dynamic information to access requests such as tags, user attributes, geographical location, time-based data, and other contextual information that policies can use for fine-grained access control decisions.

Capabilities

RangerContextEnricher

Core interface for context enrichment components that add attributes to access requests during policy evaluation.

/**
 * Interface for context enrichment components
 */
public interface RangerContextEnricher {
    /**
     * Initialize the context enricher with configuration
     */
    public void init();
    
    /**
     * Enrich the access request with additional context
     * @param request - Access request to enrich with context
     */
    public void enrich(RangerAccessRequest request);
    
    /**
     * Check if this enricher needs dynamic evaluation
     * @return True if dynamic evaluation is required
     */
    public boolean preCleanup();
    
    /**
     * Cleanup resources after enrichment
     */
    public void cleanup();
}

RangerAbstractContextEnricher

Abstract base class providing common functionality for context enrichers, including configuration management and lifecycle support.

/**
 * Abstract base implementation for context enrichers
 */
public abstract class RangerAbstractContextEnricher implements RangerContextEnricher {
    /**
     * Enricher definition from service definition
     */
    protected RangerContextEnricherDef enricherDef;
    
    /**
     * Service definition this enricher belongs to
     */
    protected RangerServiceDef serviceDef;
    
    /**
     * Application ID for this enricher
     */
    protected String appId;
    
    /**
     * Initialize the abstract context enricher
     * @param enricherDef - Enricher definition
     * @param serviceDef - Service definition
     * @param appId - Application identifier
     */
    public void init(RangerContextEnricherDef enricherDef, RangerServiceDef serviceDef, String appId);
    
    /**
     * Get enricher configuration options
     * @return Map of configuration options
     */
    public Map<String, String> getOptions();
    
    /**
     * Get a specific configuration option
     * @param name - Option name
     * @return Option value or null if not found
     */
    public String getOption(String name);
    
    /**
     * Get a configuration option with default value
     * @param name - Option name
     * @param defaultValue - Default value if option not found
     * @return Option value or default value
     */
    public String getOption(String name, String defaultValue);
    
    /**
     * Get a boolean configuration option
     * @param name - Option name
     * @param defaultValue - Default value if option not found
     * @return Boolean option value or default value
     */
    public boolean getBooleanOption(String name, boolean defaultValue);
    
    /**
     * Get an integer configuration option
     * @param name - Option name
     * @param defaultValue - Default value if option not found
     * @return Integer option value or default value
     */
    public int getIntOption(String name, int defaultValue);
    
    /**
     * Get a long configuration option
     * @param name - Option name
     * @param defaultValue - Default value if option not found
     * @return Long option value or default value
     */
    public long getLongOption(String name, long defaultValue);
    
    /**
     * Get the enricher name
     * @return Enricher name
     */
    public String getEnricherName();
    
    /**
     * Get the service name
     * @return Service name
     */
    public String getServiceName();
    
    /**
     * Get the service type
     * @return Service type
     */
    public String getServiceType();
    
    /**
     * Default implementation - no pre-cleanup needed
     * @return False by default
     */
    @Override
    public boolean preCleanup();
    
    /**
     * Default implementation - no cleanup needed
     */
    @Override
    public void cleanup();
}

RangerTagEnricher

Context enricher that adds tag-based attributes to access requests for attribute-based access control (ABAC).

/**
 * Context enricher for tag-based attributes
 */
public class RangerTagEnricher extends RangerAbstractContextEnricher {
    /**
     * Key for storing tags in request context
     */
    public static final String TAG_ATTR_SET_KEY = "TAGS";
    
    /**
     * Key for storing tag-based policies in context
     */
    public static final String TAG_POLICIES_KEY = "TAG_POLICIES";
    
    /**
     * Initialize the tag enricher
     */
    @Override
    public void init();
    
    /**
     * Enrich access request with tag information
     * @param request - Access request to enrich
     */
    @Override
    public void enrich(RangerAccessRequest request);
    
    /**
     * Get tags for a specific resource
     * @param resource - Resource to get tags for
     * @return Set of tags associated with the resource
     */
    public Set<RangerTagForEval> getTagsForResource(RangerAccessResource resource);
    
    /**
     * Get all tags for resource matching
     * @return List of all available tags
     */
    public List<RangerTag> getTags();
    
    /**
     * Get service tags configuration
     * @return Service tags configuration
     */
    public ServiceTags getServiceTags();
    
    /**
     * Update service tags configuration
     * @param serviceTags - New service tags configuration
     */
    public void setServiceTags(ServiceTags serviceTags);
    
    /**
     * Get tag policies for evaluation
     * @return List of tag-based policies
     */
    public List<RangerPolicy> getTagPolicies();
    
    /**
     * Check if tag enricher is enabled
     * @return True if tag enricher is enabled
     */
    public boolean isTagEnricherEnabled();
    
    /**
     * Get tag attribute evaluators
     * @return Map of attribute names to evaluators
     */
    public Map<String, RangerTagAttributeEvaluator> getTagAttributeEvaluators();
}

RangerUserStoreEnricher

Context enricher that adds user and group attribute information to access requests.

/**
 * Context enricher for user and group attributes
 */
public class RangerUserStoreEnricher extends RangerAbstractContextEnricher {
    /**
     * Key for storing user attributes in context
     */
    public static final String USER_ATTRIBUTES_KEY = "USER_ATTRIBUTES";
    
    /**
     * Key for storing group attributes in context
     */
    public static final String GROUP_ATTRIBUTES_KEY = "GROUP_ATTRIBUTES";
    
    /**
     * Initialize the user store enricher
     */
    @Override
    public void init();
    
    /**
     * Enrich access request with user and group attributes
     * @param request - Access request to enrich
     */
    @Override
    public void enrich(RangerAccessRequest request);
    
    /**
     * Get user attributes
     * @param userName - Username to get attributes for
     * @return Map of user attributes
     */
    public Map<String, String> getUserAttributes(String userName);
    
    /**
     * Get group attributes
     * @param groupName - Group name to get attributes for
     * @return Map of group attributes
     */
    public Map<String, String> getGroupAttributes(String groupName);
    
    /**
     * Get all users in user store
     * @return Set of all usernames
     */
    public Set<String> getAllUsers();
    
    /**
     * Get all groups in user store
     * @return Set of all group names
     */
    public Set<String> getAllGroups();
    
    /**
     * Get groups for a specific user
     * @param userName - Username to get groups for
     * @return Set of group names for the user
     */
    public Set<String> getGroupsForUser(String userName);
    
    /**
     * Update user store configuration
     * @param userStore - New user store configuration
     */
    public void setUserStore(RangerUserStore userStore);
    
    /**
     * Get current user store configuration
     * @return Current user store configuration
     */
    public RangerUserStore getUserStore();
    
    /**
     * Check if user store enricher is enabled
     * @return True if user store enricher is enabled
     */
    public boolean isUserStoreEnricherEnabled();
}

RangerScriptEnricher

Context enricher that allows custom script-based context enrichment for advanced use cases.

/**
 * Script-based context enricher for custom enrichment logic
 */
public class RangerScriptEnricher extends RangerAbstractContextEnricher {
    /**
     * Configuration key for script engine type
     */
    public static final String SCRIPT_ENGINE_TYPE = "script.engine.type";
    
    /**
     * Configuration key for script content
     */
    public static final String SCRIPT_CONTENT = "script.content";
    
    /**
     * Configuration key for script file path
     */
    public static final String SCRIPT_FILE_PATH = "script.file.path";
    
    /**
     * Default script engine type (JavaScript)
     */
    public static final String DEFAULT_SCRIPT_ENGINE = "javascript";
    
    /**
     * Initialize the script enricher
     */
    @Override
    public void init();
    
    /**
     * Enrich access request using custom script logic
     * @param request - Access request to enrich
     */
    @Override
    public void enrich(RangerAccessRequest request);
    
    /**
     * Get the script engine being used
     * @return Script engine instance
     */
    public ScriptEngine getScriptEngine();
    
    /**
     * Get the script content
     * @return Script content as string
     */
    public String getScriptContent();
    
    /**
     * Load script from file
     * @param filePath - Path to script file
     * @return Script content
     * @throws IOException if file cannot be read
     */
    public String loadScriptFromFile(String filePath) throws IOException;
    
    /**
     * Execute script with given parameters
     * @param params - Parameters to pass to script
     * @return Script execution result
     * @throws ScriptException if script execution fails
     */
    public Object executeScript(Map<String, Object> params) throws ScriptException;
}

RangerGeolocationEnricher

Context enricher that adds geographical location information based on client IP address.

/**
 * Context enricher for geographical location information
 */
public class RangerGeolocationEnricher extends RangerAbstractContextEnricher {
    /**
     * Key for storing country information in context
     */
    public static final String GEO_COUNTRY_KEY = "GEO_COUNTRY";
    
    /**
     * Key for storing state/province information in context
     */
    public static final String GEO_STATE_KEY = "GEO_STATE";
    
    /**
     * Key for storing city information in context
     */
    public static final String GEO_CITY_KEY = "GEO_CITY";
    
    /**
     * Configuration key for geolocation database path
     */
    public static final String GEO_DB_PATH_CONFIG = "geo.db.path";
    
    /**
     * Configuration key for enabling geolocation enrichment
     */
    public static final String GEO_ENABLED_CONFIG = "geo.enabled";
    
    /**
     * Initialize the geolocation enricher
     */
    @Override
    public void init();
    
    /**
     * Enrich access request with geographical location information
     * @param request - Access request to enrich
     */
    @Override
    public void enrich(RangerAccessRequest request);
    
    /**
     * Get geographical location for an IP address
     * @param ipAddress - IP address to lookup
     * @return Geographical location information
     */
    public GeoLocation getLocationForIP(String ipAddress);
    
    /**
     * Check if geolocation database is available
     * @return True if geolocation database is loaded and available
     */
    public boolean isGeolocationAvailable();
    
    /**
     * Update geolocation database
     * @param dbPath - Path to new geolocation database file
     * @throws IOException if database cannot be loaded
     */
    public void updateGeolocationDatabase(String dbPath) throws IOException;
}

Context Enrichment Helper Classes

Helper classes and data structures used by context enrichers.

/**
 * Container for tag evaluation information
 */
public class RangerTagForEval {
    /**
     * Get the tag type
     * @return Tag type name
     */
    public String getType();
    
    /**
     * Get tag attributes
     * @return Map of attribute names to values
     */
    public Map<String, String> getAttributes();
    
    /**
     * Get tag matching information
     * @return Tag matching details
     */
    public RangerTagMatchInfo getMatchInfo();
    
    /**
     * Check if tag matches the resource
     * @param resource - Resource to check against
     * @return True if tag applies to resource
     */
    public boolean isApplicable(RangerAccessResource resource);
}

/**
 * Evaluator for tag attributes
 */
public class RangerTagAttributeEvaluator {
    /**
     * Evaluate tag attribute value
     * @param request - Access request
     * @param tag - Tag being evaluated
     * @return Evaluated attribute value
     */
    public String evaluateAttribute(RangerAccessRequest request, RangerTagForEval tag);
    
    /**
     * Check if attribute evaluation is needed
     * @return True if dynamic evaluation is required
     */
    public boolean needsEvaluation();
}

/**
 * Geographical location information
 */
public class GeoLocation {
    /**
     * Get country name
     * @return Country name
     */
    public String getCountry();
    
    /**
     * Get country code
     * @return ISO country code
     */
    public String getCountryCode();
    
    /**
     * Get state or province
     * @return State/province name
     */
    public String getState();
    
    /**
     * Get city name
     * @return City name
     */
    public String getCity();
    
    /**
     * Get latitude
     * @return Latitude coordinate
     */
    public Double getLatitude();
    
    /**
     * Get longitude
     * @return Longitude coordinate
     */
    public Double getLongitude();
}

Usage Examples:

import org.apache.ranger.plugin.contextenricher.*;
import org.apache.ranger.plugin.policyengine.RangerAccessRequest;

// Configure and use tag enricher
public class TagEnrichmentExample {
    public void setupTagEnricher() {
        // Create tag enricher configuration
        RangerContextEnricherDef enricherDef = new RangerContextEnricherDef();
        enricherDef.setName("tag-enricher");
        enricherDef.setEnricher("org.apache.ranger.plugin.contextenricher.RangerTagEnricher");
        
        Map<String, String> options = new HashMap<>();
        options.put("tag.source.type", "atlas");
        options.put("tag.source.url", "http://atlas:21000");
        options.put("tag.refresh.interval", "60000");
        enricherDef.setEnricherOptions(options);
        
        // Initialize tag enricher
        RangerTagEnricher tagEnricher = new RangerTagEnricher();
        tagEnricher.init(enricherDef, serviceDef, "MyApp");
        
        // Use enricher with access request
        RangerAccessRequestImpl request = new RangerAccessRequestImpl();
        request.setResource(resource);
        request.setUser("alice");
        request.setAccessType("read");
        
        // Enrich request with tags
        tagEnricher.enrich(request);
        
        // Access enriched context
        @SuppressWarnings("unchecked")
        Set<RangerTagForEval> tags = (Set<RangerTagForEval>) request.getContext()
            .get(RangerTagEnricher.TAG_ATTR_SET_KEY);
        
        if (tags != null) {
            for (RangerTagForEval tag : tags) {
                System.out.println("Tag: " + tag.getType() + 
                                   " with attributes: " + tag.getAttributes());
            }
        }
    }
}

// Configure and use user store enricher
public class UserStoreEnrichmentExample {
    public void setupUserStoreEnricher() {
        // Create user store enricher configuration
        RangerContextEnricherDef enricherDef = new RangerContextEnricherDef();
        enricherDef.setName("userstore-enricher");
        enricherDef.setEnricher("org.apache.ranger.plugin.contextenricher.RangerUserStoreEnricher");
        
        Map<String, String> options = new HashMap<>();
        options.put("userstore.source.type", "ldap");
        options.put("userstore.ldap.url", "ldap://ldap.company.com:389");
        options.put("userstore.refresh.interval", "300000");
        enricherDef.setEnricherOptions(options);
        
        // Initialize user store enricher
        RangerUserStoreEnricher userStoreEnricher = new RangerUserStoreEnricher();
        userStoreEnricher.init(enricherDef, serviceDef, "MyApp");
        
        // Use enricher with access request
        RangerAccessRequestImpl request = new RangerAccessRequestImpl();
        request.setUser("alice");
        request.setUserGroups(Set.of("analysts", "employees"));
        
        // Enrich request with user attributes
        userStoreEnricher.enrich(request);
        
        // Access enriched user attributes
        @SuppressWarnings("unchecked")
        Map<String, String> userAttrs = (Map<String, String>) request.getContext()
            .get(RangerUserStoreEnricher.USER_ATTRIBUTES_KEY);
        
        if (userAttrs != null) {
            System.out.println("User department: " + userAttrs.get("department"));
            System.out.println("User location: " + userAttrs.get("location"));
            System.out.println("User title: " + userAttrs.get("title"));
        }
    }
}

// Configure and use script enricher
public class ScriptEnrichmentExample {
    public void setupScriptEnricher() {
        // Create script enricher configuration
        RangerContextEnricherDef enricherDef = new RangerContextEnricherDef();
        enricherDef.setName("script-enricher");
        enricherDef.setEnricher("org.apache.ranger.plugin.contextenricher.RangerScriptEnricher");
        
        Map<String, String> options = new HashMap<>();
        options.put(RangerScriptEnricher.SCRIPT_ENGINE_TYPE, "javascript");
        options.put(RangerScriptEnricher.SCRIPT_CONTENT, 
            "var time = new Date().getHours();" +
            "request.getContext().put('TIME_OF_DAY', " +
            "time < 9 || time > 17 ? 'AFTER_HOURS' : 'BUSINESS_HOURS');" +
            "request.getContext().put('ACCESS_TIMESTAMP', new Date().getTime());");
        enricherDef.setEnricherOptions(options);
        
        // Initialize script enricher
        RangerScriptEnricher scriptEnricher = new RangerScriptEnricher();
        scriptEnricher.init(enricherDef, serviceDef, "MyApp");
        
        // Use enricher with access request
        RangerAccessRequestImpl request = new RangerAccessRequestImpl();
        request.setUser("alice");
        
        // Enrich request with script-generated context
        scriptEnricher.enrich(request);
        
        // Access enriched context
        String timeOfDay = (String) request.getContext().get("TIME_OF_DAY");
        Long timestamp = (Long) request.getContext().get("ACCESS_TIMESTAMP");
        
        System.out.println("Access during: " + timeOfDay);
        System.out.println("Access timestamp: " + new Date(timestamp));
    }
}

// Configure and use geolocation enricher
public class GeolocationEnrichmentExample {
    public void setupGeolocationEnricher() {
        // Create geolocation enricher configuration
        RangerContextEnricherDef enricherDef = new RangerContextEnricherDef();
        enricherDef.setName("geo-enricher");
        enricherDef.setEnricher("org.apache.ranger.plugin.contextenricher.RangerGeolocationEnricher");
        
        Map<String, String> options = new HashMap<>();
        options.put(RangerGeolocationEnricher.GEO_DB_PATH_CONFIG, "/opt/ranger/geo/GeoLite2-City.mmdb");
        options.put(RangerGeolocationEnricher.GEO_ENABLED_CONFIG, "true");
        enricherDef.setEnricherOptions(options);
        
        // Initialize geolocation enricher
        RangerGeolocationEnricher geoEnricher = new RangerGeolocationEnricher();
        geoEnricher.init(enricherDef, serviceDef, "MyApp");
        
        // Use enricher with access request
        RangerAccessRequestImpl request = new RangerAccessRequestImpl();
        request.setUser("alice");
        request.setClientIPAddress("192.168.1.100");
        
        // Enrich request with geographical information
        geoEnricher.enrich(request);
        
        // Access enriched geographical context
        String country = (String) request.getContext().get(RangerGeolocationEnricher.GEO_COUNTRY_KEY);
        String state = (String) request.getContext().get(RangerGeolocationEnricher.GEO_STATE_KEY);
        String city = (String) request.getContext().get(RangerGeolocationEnricher.GEO_CITY_KEY);
        
        System.out.println("Access from: " + city + ", " + state + ", " + country);
    }
}

Context Enrichment Pipeline

Context enrichers are executed in a pipeline during policy evaluation:

  1. Initialization Phase: All enrichers are initialized with their configuration
  2. Enrichment Phase: Each enricher adds context to the access request in order
  3. Policy Evaluation: Policies use enriched context for decision making
  4. Cleanup Phase: Enrichers clean up resources if needed

Enrichment Order and Dependencies

The order of context enrichment can be important:

  • Tag enrichers typically run first to add resource tags
  • User store enrichers add user/group attributes
  • Custom enrichers (script, geolocation) run last
  • Dependencies between enrichers can be configured in service definitions

Performance Considerations

Context enrichment impacts policy evaluation performance:

  • Caching: Enrichers should cache expensive lookups (user attributes, tags)
  • Lazy evaluation: Only enrich context that policies actually use
  • Batch operations: Use batch APIs when enriching multiple requests
  • Asynchronous updates: Update enricher data sources asynchronously when possible
  • Timeout handling: Implement timeouts for external data source lookups

Configuration and Customization

Context enrichers are highly configurable:

  • Service definition configuration: Defined in RangerServiceDef.contextEnrichers
  • Runtime options: Passed via enricher options map
  • External data sources: Support for LDAP, databases, REST APIs, files
  • Custom implementations: Extend RangerAbstractContextEnricher for custom logic

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-ranger--ranger-plugins-common

docs

admin-client.md

authentication-security.md

context-enrichment.md

index.md

plugin-services.md

policy-engine.md

policy-models.md

resource-matching.md

tile.json