Create Mappings Between Principals and UNIX Usernames

HDP uses a rule-based system to create mappings between service principals and their related UNIX usernames. The rules are specified in the core-site.xml configuration file as the value to the optional key hadoop.security.auth_to_local.

The default rule is simply named DEFAULT. It translates all principals in your default domain to their first component. For example, myusername@APACHE.ORG and myusername/admin@APACHE.ORG both become myusername, assuming your default domain is APACHE.ORG.

While mapping the Kerberos principals, if the Kerberos principal names are in the UPPERCASE or CaMeLcase, the names will not be recognized on the Linux machine (as Linux users are always in lower case). You must add the extra switch "/L" in the rule definition to force the conversion to lower case.

Creating Rules

To accommodate more complex translations, you can create a hierarchical set of rules to add to the default. Each rule is divided into three parts: base, filter, and substitution.

The Base:
The base begins with the number of components in the principal name (excluding the realm), followed by a colon, and the pattern for building the username from the sections of the principal name. In the pattern section $0 translates to the realm, $1 translates to the first component, and $2 to the second component.
```
[1:$1@$0] translates myusername@APACHE.ORG to myusername@APACHE.ORG 
[2:$1] translates myusername/admin@APACHE.ORG to myusername 
[2:$1%$2] translates myusername/admin@APACHE.ORG to “myusername%admin"
```
The Filter:
The filter consists of a regular expression (regex) in a parentheses. It must match the generated string for the rule to apply.
```
(.*%admin) matches any string that ends in %admin 
(.*@SOME.DOMAIN) matches any string that ends in @SOME.DOMAIN
```

The Substitution:

The substitution is a sed rule that translates a regex into a fixed string.

s/@ACME\.COM// removes the first instance of @ACME.DOMAIN
s/@[A-Z]*\.COM// remove the first instance of @ followed by a name followed by COM. 
s/X/Y/g replace all of X's in the name with Y

If your default realm was APACHE.ORG, but you also wanted to take all principals from ACME.COM that had a single component joe@ACME.COM, the following rule would do this:

To translate names with a second component, you could use these rules:

RULE:[1:$1@$0](.@ACME.COM)s/@.//
RULE:[2:$1@$0](.@ACME.COM)s/@.// DEFAULT

To treat all principals from APACHE.ORG with the extension /admin as admin, your rules would look like this:

RULE[2:$1%$2@$0](.%admin@APACHE.ORG)s/./admin/
DEFAULT

To force username conversion from CaMeLcase or UPPERCASE to lowercase, you could model the following auth_to_local rule examples which have the lowercase switch added:

RULE:[1:$1]/L
RULE:[2:$1]/L
RULE:[2:$1;$2](^.*;admin$)s/;admin$///L
RULE:[2:$1;$2](^.*;guest$)s/;guest$//g/L

RULE:[1:$1]/L
RULE:[2:$1]/L
RULE:[2:$1;$2](^.*;admin$)s/;admin$///L
RULE:[2:$1;$2](^.*;guest$)s/;guest$//g/L

And based on these rules, here are the expected output for the following inputs:

"JOE@FOO.COM" to "joe" "Joe/root@FOO.COM" to "joe" "Joe/admin@FOO.COM" to "joe" "Joe/guestguest@FOO.COM" to "joe"