Wildcards and macros in resource-based policies

USER macro

Let us use the following example to understand the usage of USER macro.

In the preceeding example of the USER macro policy in the HDFS service, the policy has /user/{USER} as the Resource Path. This Resource Path has the {USER} macro, which will be replaced by the username when an access request is authorized using this policy. In Allow Conditions, to give Read/Write/Execute access, there is a {USER} macro defined for the user value, and this macro will be expanded to the corresponding user who accesses the resource. Resource Path macro and the corresponding Allow Condition macro will determine the user's access to the particular resource path.

For example, if the user systest is reading data from /user/systest, this USER macro policy will allow read access. If the user systest tries to read data from /user/hive, access will be denied.

By defining this single policy, enterprises can take advantage of controlling access to the user data.

Customizability of USER macro in Ranger

Ranger requires that the {USER} string be used to represent an accessing user as the user in the policy item in a Ranger policy. However, Ranger provides a flexible way of customizing the string that is used as shorthand to represent the accessing user's name in the policy resource specification. By default, Ranger policy resource specification expects the '{' and '}' characters as delimiters for the string USER; however, Ranger supports a customizable way of specifying delimiter characters, escaping those delimiters, and the string USER itself by prefixing it with another user-specified string on a per resource-level basis in the service definition of each component supported by Ranger.

"resources": [
{
      "itemId": 1,
      "name": "path",
      "type": "path",
      "level": 10,
      "parent": "",
      "mandatory": true,
      "lookupSupported": true,
      "recursiveSupported": true,
      "excludesSupported": false,
      "matcher": "org.apache.ranger.plugin.resourcematcher.RangerPathResourceMatcher",
      "matcherOptions": {"wildcard": true, "ignoreCase": false}, "replaceTokens":true, "tokenDelimiterStart":"%", "tokenDelimiterEnd":"%", "tokenDelimiterPrefix":"rangerToken:"}
      "validationRegEx":"",
      "validationMessage": "",
      "uiHint":"",
      "label": "Resource Path",
      "description": "HDFS file or directory
path"
}
]

 resource: path=/home/%rangerToken:USER%
 user: {USER}
 permissions: all, delegateAdmin=true

Advanced use of USER macro

This feature, at its core, supports general-purpose identification of special patterns in the resource specification and their replacement at runtime with other strings to derive the name of the resource, before matching it with the resource being accessed by the user. Therefore, it is not limited to the replacement of string USER with the current user's name; it is just something that is offered out of the box.

In order for Ranger users to use the underlying core functionality, they need to be familiar with interfaces provided by Ranger for customizing Ranger, such as RangerContextEnricher, RangerAccessRequest, and RangerConditionEvaluator.

The following methods are provided to populate and reference context in the RangerAccessRequest object that represents access requests in the policy evaluation engine:

• RangerAccessRequestUtil.setTokenInContext(Map<String, Object> context, String tokenName, Object tokenValue);
• Object RangerAccessRequestUtil.getTokenFromContext(Map<String, Object> context, String tokenName);

An advanced Ranger user needs to provide the following to use the core functionality offered by this feature:

• Provide an implementation of RangerContextEnricher and include it in the service definition. The implementation of RangerContextEnricher.enrich() method needs to get the context of the RangerAccessRequest provided to it and use the RangerAccessRequestUtil.setTokenInContext() API to populate it with a specific tokenName (such as USER) and its value, derived based on some runtime information and enricher's configuration parameters.
• Customize the component's service definition with appropriate matcherOptions for each resource definition supported by it as described above in the customizability section.
• Provide an implementation of RangerConditionEvaluator and include it in the service definition. The implementation of the RangerConditionEvaluator.isMatched() API needs to retrieve the value of the tokenName from the request’s context using the RangerAccessRequestUtil.getTokenFromContext() API, and return the appropriate result.
• Author a Ranger policy with the resource specification containing the tokenName to implement appropriate access control for the resource name built at runtime by Ranger.

OWNER macro

Let us use the following example to understand the usage of OWNER macro.

When resources are created in respective services (HDFS, Hive, HBase, and so on), those resources are marked with the owner information. When the resource's owner accesses those resources, the owner should have all permissions on those resources.