Mapping Kerberos Principals to Short Names

Kerberos user principals typically have the format username@REALM, whereas Hadoop usernames are typically just username. To translate Kerberos principals to Hadoop usernames, Hadoop uses rules defined in the hadoop.security.auth_to_local property. The default setting strips the @REALM portion from the Kerberos principal, where REALM is the Kerberos realm defined by the default_realm setting in the NameNode krb5.conf file.

If you configure your cluster's Kerberos realm to trust other realms, such as a trust between your cluster's realm and a central Active Directory or MIT Kerberos realm, you must identify the trusted realms in Cloudera Manager so it can automatically generate the appropriate rules. If you do not do so, user accounts in those realms cannot access the cluster.

To specify trusted realms using Cloudera Manager:

  1. Navigate to the HDFS Service > Configuration tab.
  2. In the Search field, type Kerberos Realms to find the Trusted Kerberos Realms and Additional Rules to Map Kerberos Principals to Short Names settings (in the Service-Wide > Security category).
  3. Add realms that are trusted by the cluster's Kerberos realm. Realm names, including Active Directory realms, must be specified in uppercase letters (for example, CORP.EXAMPLE.COM). To add multiple realms, use the button.
  4. Click Save Changes.

The auto-generated mapping rules strip the Kerberos realm (for example, @CORP.EXAMPLE.COM) for each realm specified in the Trusted Kerberos Realms setting. To customize the mapping rules, specify additional rules in the Additional Rules to Map Kerberos Principals to Short Names setting, one rule per line. Only enter rules in this field; Cloudera Manager automatically surrounds the rules with the appropriate XML tags for the generated core-site.xml file. For more information on creating custom rules, including how to translate mixed-case Kerberos principals to lowercase Hadoop usernames, see Mapping Rule Syntax.

If you specify custom mapping rules for a Kerberos realm using the Additional Rules to Map Kerberos Principals to Short Names setting, ensure that the same realm is not specified in the Trusted Kerberos Realms setting. If it is, the auto-generated rule (which only strips the realm from the principal and does no additional transformations) takes precedent, and the custom rule is ignored.

For these changes to take effect, you must restart the cluster and re-deploy the client configuration. On the Cloudera Manager Home page, click the cluster-wide button and select Deploy Client Configuration.

Using Auth-to-Local Rules to Isolate Cluster Users

By default, the Hadoop auth-to-local rules map a principal of the form <username>/<hostname>@<REALM> to <username>. This means if there are multiple clusters in the same realm, then principals associated with hosts of one cluster would map to the same user in all other clusters.

For example, if you have two clusters, cluster1-host-[1..4].example.com and cluster2-host- [1..4].example.com, that are part of the same Kerberos realm, EXAMPLE.COM, then the cluster2 principal, hdfs/cluster2-host1.example.com@EXAMPLE.COM, will map to the hdfs user even on cluster1 hosts.

To prevent this, use auth-to-local rules as follows to ensure only principals containing hostnames of cluster1 are mapped to legitimate users.

  1. Navigate to the HDFS Service > Configuration tab.
  2. In the Search field, type Additional Rules to find the Additional Rules to Map Kerberos Principals to Short Names settings (in the Service-Wide > Security category).
  3. Additional mapping rules can be added to the Additional Rules to Map Kerberos Principals to Short Names property. These rules will be inserted before the rules generated from the list of trusted realms (configured above) and before the default rule. 
    RULE:[2:$1/$2@$0](hdfs/cluster1-host1.example.com@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/hdfs/
RULE:[2:$1/$2@$0](hdfs/cluster1-host2.example.com@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/hdfs/
RULE:[2:$1/$2@$0](hdfs/cluster1-host3.example.com@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/hdfs/
RULE:[2:$1/$2@$0](hdfs/cluster1-host4.example.com@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/hdfs/
RULE:[2:$1/$2@$0](hdfs.*@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/nobody/

    In the example, the principal hdfs/<hostname>@REALM is mapped to the hdfs user if <hostname> is one of the cluster hosts. Otherwise it gets mapped to nobody, thus ensuring that principals from other clusters do not have access to cluster1.

    If the cluster hosts can be represented with a regular expression, that expression can be used to make the configuration easier and more conducive to scaling. For example:

    RULE:[2:$1/$2@$0](hdfs/cluster1-host[1-4].example.com@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/hdfs/
RULE:[2:$1/$2@$0](hdfs.*@EXAMPLE.COM)s/(.*)@EXAMPLE.COM/nobody/
  4. Click Save Changes.
  5. Restart the HDFS service and any dependent services.