001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.security;
019
020import static org.apache.hadoop.fs.CommonConfigurationKeys.HADOOP_USER_GROUP_METRICS_PERCENTILES_INTERVALS;
021import static org.apache.hadoop.fs.CommonConfigurationKeysPublic.HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN;
022import static org.apache.hadoop.fs.CommonConfigurationKeysPublic.HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN_DEFAULT;
023import static org.apache.hadoop.fs.CommonConfigurationKeysPublic.HADOOP_TOKEN_FILES;
024import static org.apache.hadoop.util.PlatformName.IBM_JAVA;
025
026import java.io.File;
027import java.io.FileNotFoundException;
028import java.io.IOException;
029import java.lang.reflect.UndeclaredThrowableException;
030import java.security.AccessControlContext;
031import java.security.AccessController;
032import java.security.Principal;
033import java.security.PrivilegedAction;
034import java.security.PrivilegedActionException;
035import java.security.PrivilegedExceptionAction;
036import java.util.ArrayList;
037import java.util.Arrays;
038import java.util.Collection;
039import java.util.Collections;
040import java.util.HashMap;
041import java.util.HashSet;
042import java.util.Iterator;
043import java.util.List;
044import java.util.Map;
045import java.util.Set;
046
047import javax.security.auth.Subject;
048import javax.security.auth.callback.CallbackHandler;
049import javax.security.auth.kerberos.KerberosPrincipal;
050import javax.security.auth.kerberos.KerberosTicket;
051import javax.security.auth.login.AppConfigurationEntry;
052import javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag;
053import javax.security.auth.login.LoginContext;
054import javax.security.auth.login.LoginException;
055import javax.security.auth.spi.LoginModule;
056
057import org.apache.hadoop.classification.InterfaceAudience;
058import org.apache.hadoop.classification.InterfaceStability;
059import org.apache.hadoop.conf.Configuration;
060import org.apache.hadoop.io.Text;
061import org.apache.hadoop.metrics2.annotation.Metric;
062import org.apache.hadoop.metrics2.annotation.Metrics;
063import org.apache.hadoop.metrics2.lib.DefaultMetricsSystem;
064import org.apache.hadoop.metrics2.lib.MetricsRegistry;
065import org.apache.hadoop.metrics2.lib.MutableQuantiles;
066import org.apache.hadoop.metrics2.lib.MutableRate;
067import org.apache.hadoop.security.SaslRpcServer.AuthMethod;
068import org.apache.hadoop.security.authentication.util.KerberosUtil;
069import org.apache.hadoop.security.token.Token;
070import org.apache.hadoop.security.token.TokenIdentifier;
071import org.apache.hadoop.util.Shell;
072import org.apache.hadoop.util.StringUtils;
073import org.apache.hadoop.util.Time;
074
075import com.google.common.annotations.VisibleForTesting;
076import org.slf4j.Logger;
077import org.slf4j.LoggerFactory;
078
079/**
080 * User and group information for Hadoop.
081 * This class wraps around a JAAS Subject and provides methods to determine the
082 * user's username and groups. It supports both the Windows, Unix and Kerberos 
083 * login modules.
084 */
085@InterfaceAudience.LimitedPrivate({"HDFS", "MapReduce", "HBase", "Hive", "Oozie"})
086@InterfaceStability.Evolving
087public class UserGroupInformation {
088  private static final Logger LOG = LoggerFactory.getLogger(
089      UserGroupInformation.class);
090
091  /**
092   * Percentage of the ticket window to use before we renew ticket.
093   */
094  private static final float TICKET_RENEW_WINDOW = 0.80f;
095  private static boolean shouldRenewImmediatelyForTests = false;
096  static final String HADOOP_USER_NAME = "HADOOP_USER_NAME";
097  static final String HADOOP_PROXY_USER = "HADOOP_PROXY_USER";
098
099  /**
100   * For the purposes of unit tests, we want to test login
101   * from keytab and don't want to wait until the renew
102   * window (controlled by TICKET_RENEW_WINDOW).
103   * @param immediate true if we should login without waiting for ticket window
104   */
105  @VisibleForTesting
106  public static void setShouldRenewImmediatelyForTests(boolean immediate) {
107    shouldRenewImmediatelyForTests = immediate;
108  }
109
110  /** 
111   * UgiMetrics maintains UGI activity statistics
112   * and publishes them through the metrics interfaces.
113   */
114  @Metrics(about="User and group related metrics", context="ugi")
115  static class UgiMetrics {
116    final MetricsRegistry registry = new MetricsRegistry("UgiMetrics");
117
118    @Metric("Rate of successful kerberos logins and latency (milliseconds)")
119    MutableRate loginSuccess;
120    @Metric("Rate of failed kerberos logins and latency (milliseconds)")
121    MutableRate loginFailure;
122    @Metric("GetGroups") MutableRate getGroups;
123    MutableQuantiles[] getGroupsQuantiles;
124
125    static UgiMetrics create() {
126      return DefaultMetricsSystem.instance().register(new UgiMetrics());
127    }
128
129    static void reattach() {
130      metrics = UgiMetrics.create();
131    }
132
133    void addGetGroups(long latency) {
134      getGroups.add(latency);
135      if (getGroupsQuantiles != null) {
136        for (MutableQuantiles q : getGroupsQuantiles) {
137          q.add(latency);
138        }
139      }
140    }
141  }
142  
143  /**
144   * A login module that looks at the Kerberos, Unix, or Windows principal and
145   * adds the corresponding UserName.
146   */
147  @InterfaceAudience.Private
148  public static class HadoopLoginModule implements LoginModule {
149    private Subject subject;
150
151    @Override
152    public boolean abort() throws LoginException {
153      return true;
154    }
155
156    private <T extends Principal> T getCanonicalUser(Class<T> cls) {
157      for(T user: subject.getPrincipals(cls)) {
158        return user;
159      }
160      return null;
161    }
162
163    @Override
164    public boolean commit() throws LoginException {
165      if (LOG.isDebugEnabled()) {
166        LOG.debug("hadoop login commit");
167      }
168      // if we already have a user, we are done.
169      if (!subject.getPrincipals(User.class).isEmpty()) {
170        if (LOG.isDebugEnabled()) {
171          LOG.debug("using existing subject:"+subject.getPrincipals());
172        }
173        return true;
174      }
175      Principal user = null;
176      // if we are using kerberos, try it out
177      if (isAuthenticationMethodEnabled(AuthenticationMethod.KERBEROS)) {
178        user = getCanonicalUser(KerberosPrincipal.class);
179        if (LOG.isDebugEnabled()) {
180          LOG.debug("using kerberos user:"+user);
181        }
182      }
183      //If we don't have a kerberos user and security is disabled, check
184      //if user is specified in the environment or properties
185      if (!isSecurityEnabled() && (user == null)) {
186        String envUser = System.getenv(HADOOP_USER_NAME);
187        if (envUser == null) {
188          envUser = System.getProperty(HADOOP_USER_NAME);
189        }
190        user = envUser == null ? null : new User(envUser);
191      }
192      // use the OS user
193      if (user == null) {
194        user = getCanonicalUser(OS_PRINCIPAL_CLASS);
195        if (LOG.isDebugEnabled()) {
196          LOG.debug("using local user:"+user);
197        }
198      }
199      // if we found the user, add our principal
200      if (user != null) {
201        if (LOG.isDebugEnabled()) {
202          LOG.debug("Using user: \"" + user + "\" with name " + user.getName());
203        }
204
205        User userEntry = null;
206        try {
207          userEntry = new User(user.getName());
208        } catch (Exception e) {
209          throw (LoginException)(new LoginException(e.toString()).initCause(e));
210        }
211        if (LOG.isDebugEnabled()) {
212          LOG.debug("User entry: \"" + userEntry.toString() + "\"" );
213        }
214
215        subject.getPrincipals().add(userEntry);
216        return true;
217      }
218      LOG.error("Can't find user in " + subject);
219      throw new LoginException("Can't find user name");
220    }
221
222    @Override
223    public void initialize(Subject subject, CallbackHandler callbackHandler,
224                           Map<String, ?> sharedState, Map<String, ?> options) {
225      this.subject = subject;
226    }
227
228    @Override
229    public boolean login() throws LoginException {
230      if (LOG.isDebugEnabled()) {
231        LOG.debug("hadoop login");
232      }
233      return true;
234    }
235
236    @Override
237    public boolean logout() throws LoginException {
238      if (LOG.isDebugEnabled()) {
239        LOG.debug("hadoop logout");
240      }
241      return true;
242    }
243  }
244
245  /**
246   * Reattach the class's metrics to a new metric system.
247   */
248  public static void reattachMetrics() {
249    UgiMetrics.reattach();
250  }
251
252  /** Metrics to track UGI activity */
253  static UgiMetrics metrics = UgiMetrics.create();
254  /** The auth method to use */
255  private static AuthenticationMethod authenticationMethod;
256  /** Server-side groups fetching service */
257  private static Groups groups;
258  /** Min time (in seconds) before relogin for Kerberos */
259  private static long kerberosMinSecondsBeforeRelogin;
260  /** The configuration to use */
261  private static Configuration conf;
262
263  
264  /**Environment variable pointing to the token cache file*/
265  public static final String HADOOP_TOKEN_FILE_LOCATION = 
266    "HADOOP_TOKEN_FILE_LOCATION";
267  
268  /** 
269   * A method to initialize the fields that depend on a configuration.
270   * Must be called before useKerberos or groups is used.
271   */
272  private static void ensureInitialized() {
273    if (conf == null) {
274      synchronized(UserGroupInformation.class) {
275        if (conf == null) { // someone might have beat us
276          initialize(new Configuration(), false);
277        }
278      }
279    }
280  }
281
282  /**
283   * Initialize UGI and related classes.
284   * @param conf the configuration to use
285   */
286  private static synchronized void initialize(Configuration conf,
287                                              boolean overrideNameRules) {
288    authenticationMethod = SecurityUtil.getAuthenticationMethod(conf);
289    if (overrideNameRules || !HadoopKerberosName.hasRulesBeenSet()) {
290      try {
291        HadoopKerberosName.setConfiguration(conf);
292      } catch (IOException ioe) {
293        throw new RuntimeException(
294            "Problem with Kerberos auth_to_local name configuration", ioe);
295      }
296    }
297    try {
298        kerberosMinSecondsBeforeRelogin = 1000L * conf.getLong(
299                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN,
300                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN_DEFAULT);
301    }
302    catch(NumberFormatException nfe) {
303        throw new IllegalArgumentException("Invalid attribute value for " +
304                HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN + " of " +
305                conf.get(HADOOP_KERBEROS_MIN_SECONDS_BEFORE_RELOGIN));
306    }
307    // If we haven't set up testing groups, use the configuration to find it
308    if (!(groups instanceof TestingGroups)) {
309      groups = Groups.getUserToGroupsMappingService(conf);
310    }
311    UserGroupInformation.conf = conf;
312
313    if (metrics.getGroupsQuantiles == null) {
314      int[] intervals = conf.getInts(HADOOP_USER_GROUP_METRICS_PERCENTILES_INTERVALS);
315      if (intervals != null && intervals.length > 0) {
316        final int length = intervals.length;
317        MutableQuantiles[] getGroupsQuantiles = new MutableQuantiles[length];
318        for (int i = 0; i < length; i++) {
319          getGroupsQuantiles[i] = metrics.registry.newQuantiles(
320            "getGroups" + intervals[i] + "s",
321            "Get groups", "ops", "latency", intervals[i]);
322        }
323        metrics.getGroupsQuantiles = getGroupsQuantiles;
324      }
325    }
326  }
327
328  /**
329   * Set the static configuration for UGI.
330   * In particular, set the security authentication mechanism and the
331   * group look up service.
332   * @param conf the configuration to use
333   */
334  @InterfaceAudience.Public
335  @InterfaceStability.Evolving
336  public static void setConfiguration(Configuration conf) {
337    initialize(conf, true);
338  }
339  
340  @InterfaceAudience.Private
341  @VisibleForTesting
342  public static void reset() {
343    authenticationMethod = null;
344    conf = null;
345    groups = null;
346    kerberosMinSecondsBeforeRelogin = 0;
347    setLoginUser(null);
348    HadoopKerberosName.setRules(null);
349  }
350  
351  /**
352   * Determine if UserGroupInformation is using Kerberos to determine
353   * user identities or is relying on simple authentication
354   * 
355   * @return true if UGI is working in a secure environment
356   */
357  public static boolean isSecurityEnabled() {
358    return !isAuthenticationMethodEnabled(AuthenticationMethod.SIMPLE);
359  }
360  
361  @InterfaceAudience.Private
362  @InterfaceStability.Evolving
363  private static boolean isAuthenticationMethodEnabled(AuthenticationMethod method) {
364    ensureInitialized();
365    return (authenticationMethod == method);
366  }
367  
368  /**
369   * Information about the logged in user.
370   */
371  private static UserGroupInformation loginUser = null;
372  private static String keytabPrincipal = null;
373  private static String keytabFile = null;
374
375  private final Subject subject;
376  // All non-static fields must be read-only caches that come from the subject.
377  private final User user;
378  private final boolean isKeytab;
379  private final boolean isKrbTkt;
380  
381  private static String OS_LOGIN_MODULE_NAME;
382  private static Class<? extends Principal> OS_PRINCIPAL_CLASS;
383  
384  private static final boolean windows =
385      System.getProperty("os.name").startsWith("Windows");
386  private static final boolean is64Bit =
387      System.getProperty("os.arch").contains("64") ||
388      System.getProperty("os.arch").contains("s390x");
389  private static final boolean aix = System.getProperty("os.name").equals("AIX");
390
391  /* Return the OS login module class name */
392  private static String getOSLoginModuleName() {
393    if (IBM_JAVA) {
394      if (windows) {
395        return is64Bit ? "com.ibm.security.auth.module.Win64LoginModule"
396            : "com.ibm.security.auth.module.NTLoginModule";
397      } else if (aix) {
398        return is64Bit ? "com.ibm.security.auth.module.AIX64LoginModule"
399            : "com.ibm.security.auth.module.AIXLoginModule";
400      } else {
401        return "com.ibm.security.auth.module.LinuxLoginModule";
402      }
403    } else {
404      return windows ? "com.sun.security.auth.module.NTLoginModule"
405        : "com.sun.security.auth.module.UnixLoginModule";
406    }
407  }
408
409  /* Return the OS principal class */
410  @SuppressWarnings("unchecked")
411  private static Class<? extends Principal> getOsPrincipalClass() {
412    ClassLoader cl = ClassLoader.getSystemClassLoader();
413    try {
414      String principalClass = null;
415      if (IBM_JAVA) {
416        if (is64Bit) {
417          principalClass = "com.ibm.security.auth.UsernamePrincipal";
418        } else {
419          if (windows) {
420            principalClass = "com.ibm.security.auth.NTUserPrincipal";
421          } else if (aix) {
422            principalClass = "com.ibm.security.auth.AIXPrincipal";
423          } else {
424            principalClass = "com.ibm.security.auth.LinuxPrincipal";
425          }
426        }
427      } else {
428        principalClass = windows ? "com.sun.security.auth.NTUserPrincipal"
429            : "com.sun.security.auth.UnixPrincipal";
430      }
431      return (Class<? extends Principal>) cl.loadClass(principalClass);
432    } catch (ClassNotFoundException e) {
433      LOG.error("Unable to find JAAS classes:" + e.getMessage());
434    }
435    return null;
436  }
437  static {
438    OS_LOGIN_MODULE_NAME = getOSLoginModuleName();
439    OS_PRINCIPAL_CLASS = getOsPrincipalClass();
440  }
441
442  private static class RealUser implements Principal {
443    private final UserGroupInformation realUser;
444    
445    RealUser(UserGroupInformation realUser) {
446      this.realUser = realUser;
447    }
448    
449    @Override
450    public String getName() {
451      return realUser.getUserName();
452    }
453    
454    public UserGroupInformation getRealUser() {
455      return realUser;
456    }
457    
458    @Override
459    public boolean equals(Object o) {
460      if (this == o) {
461        return true;
462      } else if (o == null || getClass() != o.getClass()) {
463        return false;
464      } else {
465        return realUser.equals(((RealUser) o).realUser);
466      }
467    }
468    
469    @Override
470    public int hashCode() {
471      return realUser.hashCode();
472    }
473    
474    @Override
475    public String toString() {
476      return realUser.toString();
477    }
478  }
479  
480  /**
481   * A JAAS configuration that defines the login modules that we want
482   * to use for login.
483   */
484  private static class HadoopConfiguration 
485      extends javax.security.auth.login.Configuration {
486    private static final String SIMPLE_CONFIG_NAME = "hadoop-simple";
487    private static final String USER_KERBEROS_CONFIG_NAME = 
488      "hadoop-user-kerberos";
489    private static final String KEYTAB_KERBEROS_CONFIG_NAME = 
490      "hadoop-keytab-kerberos";
491
492    private static final Map<String, String> BASIC_JAAS_OPTIONS =
493      new HashMap<String,String>();
494    static {
495      String jaasEnvVar = System.getenv("HADOOP_JAAS_DEBUG");
496      if (jaasEnvVar != null && "true".equalsIgnoreCase(jaasEnvVar)) {
497        BASIC_JAAS_OPTIONS.put("debug", "true");
498      }
499    }
500    
501    private static final AppConfigurationEntry OS_SPECIFIC_LOGIN =
502      new AppConfigurationEntry(OS_LOGIN_MODULE_NAME,
503                                LoginModuleControlFlag.REQUIRED,
504                                BASIC_JAAS_OPTIONS);
505    private static final AppConfigurationEntry HADOOP_LOGIN =
506      new AppConfigurationEntry(HadoopLoginModule.class.getName(),
507                                LoginModuleControlFlag.REQUIRED,
508                                BASIC_JAAS_OPTIONS);
509    private static final Map<String,String> USER_KERBEROS_OPTIONS = 
510      new HashMap<String,String>();
511    static {
512      if (IBM_JAVA) {
513        USER_KERBEROS_OPTIONS.put("useDefaultCcache", "true");
514      } else {
515        USER_KERBEROS_OPTIONS.put("doNotPrompt", "true");
516        USER_KERBEROS_OPTIONS.put("useTicketCache", "true");
517      }
518      String ticketCache = System.getenv("KRB5CCNAME");
519      if (ticketCache != null) {
520        if (IBM_JAVA) {
521          // The first value searched when "useDefaultCcache" is used.
522          System.setProperty("KRB5CCNAME", ticketCache);
523        } else {
524          USER_KERBEROS_OPTIONS.put("ticketCache", ticketCache);
525        }
526      }
527      USER_KERBEROS_OPTIONS.put("renewTGT", "true");
528      USER_KERBEROS_OPTIONS.putAll(BASIC_JAAS_OPTIONS);
529    }
530    private static final AppConfigurationEntry USER_KERBEROS_LOGIN =
531      new AppConfigurationEntry(KerberosUtil.getKrb5LoginModuleName(),
532                                LoginModuleControlFlag.OPTIONAL,
533                                USER_KERBEROS_OPTIONS);
534    private static final Map<String,String> KEYTAB_KERBEROS_OPTIONS = 
535      new HashMap<String,String>();
536    static {
537      if (IBM_JAVA) {
538        KEYTAB_KERBEROS_OPTIONS.put("credsType", "both");
539      } else {
540        KEYTAB_KERBEROS_OPTIONS.put("doNotPrompt", "true");
541        KEYTAB_KERBEROS_OPTIONS.put("useKeyTab", "true");
542        KEYTAB_KERBEROS_OPTIONS.put("storeKey", "true");
543      }
544      KEYTAB_KERBEROS_OPTIONS.put("refreshKrb5Config", "true");
545      KEYTAB_KERBEROS_OPTIONS.putAll(BASIC_JAAS_OPTIONS);      
546    }
547    private static final AppConfigurationEntry KEYTAB_KERBEROS_LOGIN =
548      new AppConfigurationEntry(KerberosUtil.getKrb5LoginModuleName(),
549                                LoginModuleControlFlag.REQUIRED,
550                                KEYTAB_KERBEROS_OPTIONS);
551    
552    private static final AppConfigurationEntry[] SIMPLE_CONF = 
553      new AppConfigurationEntry[]{OS_SPECIFIC_LOGIN, HADOOP_LOGIN};
554    
555    private static final AppConfigurationEntry[] USER_KERBEROS_CONF =
556      new AppConfigurationEntry[]{OS_SPECIFIC_LOGIN, USER_KERBEROS_LOGIN,
557                                  HADOOP_LOGIN};
558
559    private static final AppConfigurationEntry[] KEYTAB_KERBEROS_CONF =
560      new AppConfigurationEntry[]{KEYTAB_KERBEROS_LOGIN, HADOOP_LOGIN};
561
562    @Override
563    public AppConfigurationEntry[] getAppConfigurationEntry(String appName) {
564      if (SIMPLE_CONFIG_NAME.equals(appName)) {
565        return SIMPLE_CONF;
566      } else if (USER_KERBEROS_CONFIG_NAME.equals(appName)) {
567        return USER_KERBEROS_CONF;
568      } else if (KEYTAB_KERBEROS_CONFIG_NAME.equals(appName)) {
569        if (IBM_JAVA) {
570          KEYTAB_KERBEROS_OPTIONS.put("useKeytab",
571              prependFileAuthority(keytabFile));
572        } else {
573          KEYTAB_KERBEROS_OPTIONS.put("keyTab", keytabFile);
574        }
575        KEYTAB_KERBEROS_OPTIONS.put("principal", keytabPrincipal);
576        return KEYTAB_KERBEROS_CONF;
577      }
578      return null;
579    }
580  }
581
582  private static String prependFileAuthority(String keytabPath) {
583    return keytabPath.startsWith("file://") ? keytabPath
584        : "file://" + keytabPath;
585  }
586
587  /**
588   * Represents a javax.security configuration that is created at runtime.
589   */
590  private static class DynamicConfiguration
591      extends javax.security.auth.login.Configuration {
592    private AppConfigurationEntry[] ace;
593    
594    DynamicConfiguration(AppConfigurationEntry[] ace) {
595      this.ace = ace;
596    }
597    
598    @Override
599    public AppConfigurationEntry[] getAppConfigurationEntry(String appName) {
600      return ace;
601    }
602  }
603
604  private static LoginContext
605  newLoginContext(String appName, Subject subject,
606    javax.security.auth.login.Configuration loginConf)
607      throws LoginException {
608    // Temporarily switch the thread's ContextClassLoader to match this
609    // class's classloader, so that we can properly load HadoopLoginModule
610    // from the JAAS libraries.
611    Thread t = Thread.currentThread();
612    ClassLoader oldCCL = t.getContextClassLoader();
613    t.setContextClassLoader(HadoopLoginModule.class.getClassLoader());
614    try {
615      return new LoginContext(appName, subject, null, loginConf);
616    } finally {
617      t.setContextClassLoader(oldCCL);
618    }
619  }
620
621  private LoginContext getLogin() {
622    return user.getLogin();
623  }
624  
625  private void setLogin(LoginContext login) {
626    user.setLogin(login);
627  }
628
629  /**
630   * Create a UserGroupInformation for the given subject.
631   * This does not change the subject or acquire new credentials.
632   * @param subject the user's subject
633   */
634  UserGroupInformation(Subject subject) {
635    this.subject = subject;
636    this.user = subject.getPrincipals(User.class).iterator().next();
637    this.isKeytab = KerberosUtil.hasKerberosKeyTab(subject);
638    this.isKrbTkt = KerberosUtil.hasKerberosTicket(subject);
639  }
640
641  /**
642   * Copies the Subject of this UGI and creates a new UGI with the new subject.
643   * This can be used to add credentials (e.g. tokens) to different copies of
644   * the same UGI, allowing multiple users with different tokens to reuse the
645   * UGI without re-authenticating with Kerberos.
646   * @return clone of the UGI with a new subject.
647   */
648  @InterfaceAudience.Public
649  @InterfaceStability.Evolving
650  public UserGroupInformation copySubjectAndUgi() {
651    Subject subj = getSubject();
652    // The ctor will set other fields automatically from the principals.
653    return new UserGroupInformation(new Subject(false, subj.getPrincipals(),
654        cloneCredentials(subj.getPublicCredentials()),
655        cloneCredentials(subj.getPrivateCredentials())));
656  }
657
658  private static Set<Object> cloneCredentials(Set<Object> old) {
659    Set<Object> set = new HashSet<>();
660    // Make sure Hadoop credentials objects do not reuse the maps.
661    for (Object o : old) {
662      set.add(o instanceof Credentials ? new Credentials((Credentials)o) : o);
663    }
664    return set;
665  }
666
667  /**
668   * checks if logged in using kerberos
669   * @return true if the subject logged via keytab or has a Kerberos TGT
670   */
671  public boolean hasKerberosCredentials() {
672    return isKeytab || isKrbTkt;
673  }
674
675  /**
676   * Return the current user, including any doAs in the current stack.
677   * @return the current user
678   * @throws IOException if login fails
679   */
680  @InterfaceAudience.Public
681  @InterfaceStability.Evolving
682  public synchronized
683  static UserGroupInformation getCurrentUser() throws IOException {
684    AccessControlContext context = AccessController.getContext();
685    Subject subject = Subject.getSubject(context);
686    if (subject == null || subject.getPrincipals(User.class).isEmpty()) {
687      return getLoginUser();
688    } else {
689      return new UserGroupInformation(subject);
690    }
691  }
692
693  /**
694   * Find the most appropriate UserGroupInformation to use
695   *
696   * @param ticketCachePath    The Kerberos ticket cache path, or NULL
697   *                           if none is specfied
698   * @param user               The user name, or NULL if none is specified.
699   *
700   * @return                   The most appropriate UserGroupInformation
701   */ 
702  public static UserGroupInformation getBestUGI(
703      String ticketCachePath, String user) throws IOException {
704    if (ticketCachePath != null) {
705      return getUGIFromTicketCache(ticketCachePath, user);
706    } else if (user == null) {
707      return getCurrentUser();
708    } else {
709      return createRemoteUser(user);
710    }    
711  }
712
713  /**
714   * Create a UserGroupInformation from a Kerberos ticket cache.
715   * 
716   * @param user                The principal name to load from the ticket
717   *                            cache
718   * @param ticketCachePath     the path to the ticket cache file
719   *
720   * @throws IOException        if the kerberos login fails
721   */
722  @InterfaceAudience.Public
723  @InterfaceStability.Evolving
724  public static UserGroupInformation getUGIFromTicketCache(
725            String ticketCache, String user) throws IOException {
726    if (!isAuthenticationMethodEnabled(AuthenticationMethod.KERBEROS)) {
727      return getBestUGI(null, user);
728    }
729    try {
730      Map<String,String> krbOptions = new HashMap<String,String>();
731      if (IBM_JAVA) {
732        krbOptions.put("useDefaultCcache", "true");
733        // The first value searched when "useDefaultCcache" is used.
734        System.setProperty("KRB5CCNAME", ticketCache);
735      } else {
736        krbOptions.put("doNotPrompt", "true");
737        krbOptions.put("useTicketCache", "true");
738        krbOptions.put("useKeyTab", "false");
739        krbOptions.put("ticketCache", ticketCache);
740      }
741      krbOptions.put("renewTGT", "false");
742      krbOptions.putAll(HadoopConfiguration.BASIC_JAAS_OPTIONS);
743      AppConfigurationEntry ace = new AppConfigurationEntry(
744          KerberosUtil.getKrb5LoginModuleName(),
745          LoginModuleControlFlag.REQUIRED,
746          krbOptions);
747      DynamicConfiguration dynConf =
748          new DynamicConfiguration(new AppConfigurationEntry[]{ ace });
749      LoginContext login = newLoginContext(
750          HadoopConfiguration.USER_KERBEROS_CONFIG_NAME, null, dynConf);
751      login.login();
752
753      Subject loginSubject = login.getSubject();
754      Set<Principal> loginPrincipals = loginSubject.getPrincipals();
755      if (loginPrincipals.isEmpty()) {
756        throw new RuntimeException("No login principals found!");
757      }
758      if (loginPrincipals.size() != 1) {
759        LOG.warn("found more than one principal in the ticket cache file " +
760          ticketCache);
761      }
762      User ugiUser = new User(loginPrincipals.iterator().next().getName(),
763          AuthenticationMethod.KERBEROS, login);
764      loginSubject.getPrincipals().add(ugiUser);
765      UserGroupInformation ugi = new UserGroupInformation(loginSubject);
766      ugi.setLogin(login);
767      ugi.setAuthenticationMethod(AuthenticationMethod.KERBEROS);
768      return ugi;
769    } catch (LoginException le) {
770      throw new IOException("failure to login using ticket cache file " +
771          ticketCache, le);
772    }
773  }
774
775  /**
776   * Create a UserGroupInformation from a Subject with Kerberos principal.
777   *
778   * @param user                The KerberosPrincipal to use in UGI
779   *
780   * @throws IOException        if the kerberos login fails
781   */
782  public static UserGroupInformation getUGIFromSubject(Subject subject)
783      throws IOException {
784    if (subject == null) {
785      throw new IOException("Subject must not be null");
786    }
787
788    if (subject.getPrincipals(KerberosPrincipal.class).isEmpty()) {
789      throw new IOException("Provided Subject must contain a KerberosPrincipal");
790    }
791
792    KerberosPrincipal principal =
793        subject.getPrincipals(KerberosPrincipal.class).iterator().next();
794
795    User ugiUser = new User(principal.getName(),
796        AuthenticationMethod.KERBEROS, null);
797    subject.getPrincipals().add(ugiUser);
798    UserGroupInformation ugi = new UserGroupInformation(subject);
799    ugi.setLogin(null);
800    ugi.setAuthenticationMethod(AuthenticationMethod.KERBEROS);
801    return ugi;
802  }
803
804  /**
805   * Get the currently logged in user.
806   * @return the logged in user
807   * @throws IOException if login fails
808   */
809  @InterfaceAudience.Public
810  @InterfaceStability.Evolving
811  public synchronized 
812  static UserGroupInformation getLoginUser() throws IOException {
813    if (loginUser == null) {
814      loginUserFromSubject(null);
815    }
816    return loginUser;
817  }
818
819  /**
820   * remove the login method that is followed by a space from the username
821   * e.g. "jack (auth:SIMPLE)" -> "jack"
822   *
823   * @param userName
824   * @return userName without login method
825   */
826  public static String trimLoginMethod(String userName) {
827    int spaceIndex = userName.indexOf(' ');
828    if (spaceIndex >= 0) {
829      userName = userName.substring(0, spaceIndex);
830    }
831    return userName;
832  }
833
834  /**
835   * Log in a user using the given subject
836   * @parma subject the subject to use when logging in a user, or null to 
837   * create a new subject.
838   * @throws IOException if login fails
839   */
840  @InterfaceAudience.Public
841  @InterfaceStability.Evolving
842  public synchronized 
843  static void loginUserFromSubject(Subject subject) throws IOException {
844    ensureInitialized();
845    try {
846      if (subject == null) {
847        subject = new Subject();
848      }
849      LoginContext login =
850          newLoginContext(authenticationMethod.getLoginAppName(), 
851                          subject, new HadoopConfiguration());
852      login.login();
853      UserGroupInformation realUser = new UserGroupInformation(subject);
854      realUser.setLogin(login);
855      realUser.setAuthenticationMethod(authenticationMethod);
856      realUser = new UserGroupInformation(login.getSubject());
857      // If the HADOOP_PROXY_USER environment variable or property
858      // is specified, create a proxy user as the logged in user.
859      String proxyUser = System.getenv(HADOOP_PROXY_USER);
860      if (proxyUser == null) {
861        proxyUser = System.getProperty(HADOOP_PROXY_USER);
862      }
863      loginUser = proxyUser == null ? realUser : createProxyUser(proxyUser, realUser);
864
865      String tokenFileLocation = System.getProperty(HADOOP_TOKEN_FILES);
866      if (tokenFileLocation == null) {
867        tokenFileLocation = conf.get(HADOOP_TOKEN_FILES);
868      }
869      if (tokenFileLocation != null) {
870        for (String tokenFileName:
871             StringUtils.getTrimmedStrings(tokenFileLocation)) {
872          if (tokenFileName.length() > 0) {
873            File tokenFile = new File(tokenFileName);
874            if (tokenFile.exists() && tokenFile.isFile()) {
875              Credentials cred = Credentials.readTokenStorageFile(
876                  tokenFile, conf);
877              loginUser.addCredentials(cred);
878            } else {
879              LOG.info("tokenFile("+tokenFileName+") does not exist");
880            }
881          }
882        }
883      }
884
885      String fileLocation = System.getenv(HADOOP_TOKEN_FILE_LOCATION);
886      if (fileLocation != null) {
887        // Load the token storage file and put all of the tokens into the
888        // user. Don't use the FileSystem API for reading since it has a lock
889        // cycle (HADOOP-9212).
890        File source = new File(fileLocation);
891        LOG.debug("Reading credentials from location set in {}: {}",
892            HADOOP_TOKEN_FILE_LOCATION,
893            source.getCanonicalPath());
894        if (!source.isFile()) {
895          throw new FileNotFoundException("Source file "
896              + source.getCanonicalPath() + " from "
897              + HADOOP_TOKEN_FILE_LOCATION
898              + " not found");
899        }
900        Credentials cred = Credentials.readTokenStorageFile(
901            source, conf);
902        LOG.debug("Loaded {} tokens", cred.numberOfTokens());
903        loginUser.addCredentials(cred);
904      }
905      loginUser.spawnAutoRenewalThreadForUserCreds();
906    } catch (LoginException le) {
907      LOG.debug("failure to login", le);
908      throw new IOException("failure to login: " + le, le);
909    }
910    if (LOG.isDebugEnabled()) {
911      LOG.debug("UGI loginUser:"+loginUser);
912    } 
913  }
914
915  @InterfaceAudience.Private
916  @InterfaceStability.Unstable
917  @VisibleForTesting
918  public synchronized static void setLoginUser(UserGroupInformation ugi) {
919    // if this is to become stable, should probably logout the currently
920    // logged in ugi if it's different
921    loginUser = ugi;
922  }
923  
924  /**
925   * Is this user logged in from a keytab file?
926   * @return true if the credentials are from a keytab file.
927   */
928  public boolean isFromKeytab() {
929    return isKeytab;
930  }
931  
932  /**
933   * Get the Kerberos TGT
934   * @return the user's TGT or null if none was found
935   */
936  private synchronized KerberosTicket getTGT() {
937    Set<KerberosTicket> tickets = subject
938        .getPrivateCredentials(KerberosTicket.class);
939    for (KerberosTicket ticket : tickets) {
940      if (SecurityUtil.isOriginalTGT(ticket)) {
941        return ticket;
942      }
943    }
944    return null;
945  }
946  
947  private long getRefreshTime(KerberosTicket tgt) {
948    long start = tgt.getStartTime().getTime();
949    long end = tgt.getEndTime().getTime();
950    return start + (long) ((end - start) * TICKET_RENEW_WINDOW);
951  }
952
953  /**Spawn a thread to do periodic renewals of kerberos credentials*/
954  private void spawnAutoRenewalThreadForUserCreds() {
955    if (isSecurityEnabled()) {
956      //spawn thread only if we have kerb credentials
957      if (user.getAuthenticationMethod() == AuthenticationMethod.KERBEROS &&
958          !isKeytab) {
959        Thread t = new Thread(new Runnable() {
960          
961          @Override
962          public void run() {
963            String cmd = conf.get("hadoop.kerberos.kinit.command",
964                                  "kinit");
965            KerberosTicket tgt = getTGT();
966            if (tgt == null) {
967              return;
968            }
969            long nextRefresh = getRefreshTime(tgt);
970            while (true) {
971              try {
972                long now = Time.now();
973                if(LOG.isDebugEnabled()) {
974                  LOG.debug("Current time is " + now);
975                  LOG.debug("Next refresh is " + nextRefresh);
976                }
977                if (now < nextRefresh) {
978                  Thread.sleep(nextRefresh - now);
979                }
980                Shell.execCommand(cmd, "-R");
981                if(LOG.isDebugEnabled()) {
982                  LOG.debug("renewed ticket");
983                }
984                reloginFromTicketCache();
985                tgt = getTGT();
986                if (tgt == null) {
987                  LOG.warn("No TGT after renewal. Aborting renew thread for " +
988                           getUserName());
989                  return;
990                }
991                nextRefresh = Math.max(getRefreshTime(tgt),
992                                       now + kerberosMinSecondsBeforeRelogin);
993              } catch (InterruptedException ie) {
994                LOG.warn("Terminating renewal thread");
995                return;
996              } catch (IOException ie) {
997                LOG.warn("Exception encountered while running the" +
998                    " renewal command. Aborting renew thread. " + ie);
999                return;
1000              }
1001            }
1002          }
1003        });
1004        t.setDaemon(true);
1005        t.setName("TGT Renewer for " + getUserName());
1006        t.start();
1007      }
1008    }
1009  }
1010  /**
1011   * Log a user in from a keytab file. Loads a user identity from a keytab
1012   * file and logs them in. They become the currently logged-in user.
1013   * @param user the principal name to load from the keytab
1014   * @param path the path to the keytab file
1015   * @throws IOException if the keytab file can't be read
1016   */
1017  @InterfaceAudience.Public
1018  @InterfaceStability.Evolving
1019  public synchronized
1020  static void loginUserFromKeytab(String user,
1021                                  String path
1022                                  ) throws IOException {
1023    if (!isSecurityEnabled())
1024      return;
1025
1026    keytabFile = path;
1027    keytabPrincipal = user;
1028    Subject subject = new Subject();
1029    LoginContext login; 
1030    long start = 0;
1031    try {
1032      login = newLoginContext(HadoopConfiguration.KEYTAB_KERBEROS_CONFIG_NAME,
1033            subject, new HadoopConfiguration());
1034      start = Time.now();
1035      login.login();
1036      metrics.loginSuccess.add(Time.now() - start);
1037      loginUser = new UserGroupInformation(subject);
1038      loginUser.setLogin(login);
1039      loginUser.setAuthenticationMethod(AuthenticationMethod.KERBEROS);
1040    } catch (LoginException le) {
1041      if (start > 0) {
1042        metrics.loginFailure.add(Time.now() - start);
1043      }
1044      throw new IOException("Login failure for " + user + " from keytab " + 
1045                            path+ ": " + le, le);
1046    }
1047    LOG.info("Login successful for user " + keytabPrincipal
1048        + " using keytab file " + keytabFile);
1049  }
1050
1051  /**
1052   * Log the current user out who previously logged in using keytab.
1053   * This method assumes that the user logged in by calling
1054   * {@link #loginUserFromKeytab(String, String)}.
1055   *
1056   * @throws IOException if a failure occurred in logout, or if the user did
1057   * not log in by invoking loginUserFromKeyTab() before.
1058   */
1059  @InterfaceAudience.Public
1060  @InterfaceStability.Evolving
1061  public void logoutUserFromKeytab() throws IOException {
1062    if (!isSecurityEnabled() ||
1063        user.getAuthenticationMethod() != AuthenticationMethod.KERBEROS) {
1064      return;
1065    }
1066    LoginContext login = getLogin();
1067    if (login == null || keytabFile == null) {
1068      throw new IOException("loginUserFromKeytab must be done first");
1069    }
1070
1071    try {
1072      if (LOG.isDebugEnabled()) {
1073        LOG.debug("Initiating logout for " + getUserName());
1074      }
1075      synchronized (UserGroupInformation.class) {
1076        login.logout();
1077      }
1078    } catch (LoginException le) {
1079      throw new IOException("Logout failure for " + user + " from keytab " +
1080          keytabFile + ": " + le,
1081          le);
1082    }
1083
1084    LOG.info("Logout successful for user " + keytabPrincipal
1085        + " using keytab file " + keytabFile);
1086  }
1087  
1088  /**
1089   * Re-login a user from keytab if TGT is expired or is close to expiry.
1090   * 
1091   * @throws IOException
1092   */
1093  public synchronized void checkTGTAndReloginFromKeytab() throws IOException {
1094    if (!isSecurityEnabled()
1095        || user.getAuthenticationMethod() != AuthenticationMethod.KERBEROS
1096        || !isKeytab)
1097      return;
1098    KerberosTicket tgt = getTGT();
1099    if (tgt != null && !shouldRenewImmediatelyForTests &&
1100        Time.now() < getRefreshTime(tgt)) {
1101      return;
1102    }
1103    reloginFromKeytab();
1104  }
1105
1106  /**
1107   * Re-Login a user in from a keytab file. Loads a user identity from a keytab
1108   * file and logs them in. They become the currently logged-in user. This
1109   * method assumes that {@link #loginUserFromKeytab(String, String)} had 
1110   * happened already.
1111   * The Subject field of this UserGroupInformation object is updated to have
1112   * the new credentials.
1113   * @throws IOException on a failure
1114   */
1115  @InterfaceAudience.Public
1116  @InterfaceStability.Evolving
1117  public synchronized void reloginFromKeytab()
1118  throws IOException {
1119    if (!isSecurityEnabled() ||
1120         user.getAuthenticationMethod() != AuthenticationMethod.KERBEROS ||
1121         !isKeytab)
1122      return;
1123    
1124    long now = Time.now();
1125    if (!shouldRenewImmediatelyForTests && !hasSufficientTimeElapsed(now)) {
1126      return;
1127    }
1128
1129    KerberosTicket tgt = getTGT();
1130    //Return if TGT is valid and is not going to expire soon.
1131    if (tgt != null && !shouldRenewImmediatelyForTests &&
1132        now < getRefreshTime(tgt)) {
1133      return;
1134    }
1135    
1136    LoginContext login = getLogin();
1137    if (login == null || keytabFile == null) {
1138      throw new IOException("loginUserFromKeyTab must be done first");
1139    }
1140    
1141    long start = 0;
1142    // register most recent relogin attempt
1143    user.setLastLogin(now);
1144    try {
1145      if (LOG.isDebugEnabled()) {
1146        LOG.debug("Initiating logout for " + getUserName());
1147      }
1148      synchronized (UserGroupInformation.class) {
1149        // clear up the kerberos state. But the tokens are not cleared! As per
1150        // the Java kerberos login module code, only the kerberos credentials
1151        // are cleared
1152        login.logout();
1153        // login and also update the subject field of this instance to
1154        // have the new credentials (pass it to the LoginContext constructor)
1155        login = newLoginContext(
1156            HadoopConfiguration.KEYTAB_KERBEROS_CONFIG_NAME, getSubject(),
1157            new HadoopConfiguration());
1158        if (LOG.isDebugEnabled()) {
1159          LOG.debug("Initiating re-login for " + keytabPrincipal);
1160        }
1161        start = Time.now();
1162        login.login();
1163        metrics.loginSuccess.add(Time.now() - start);
1164        setLogin(login);
1165      }
1166    } catch (LoginException le) {
1167      if (start > 0) {
1168        metrics.loginFailure.add(Time.now() - start);
1169      }
1170      throw new IOException("Login failure for " + keytabPrincipal + 
1171          " from keytab " + keytabFile + ": " + le, le);
1172    } 
1173  }
1174
1175  /**
1176   * Re-Login a user in from the ticket cache.  This
1177   * method assumes that login had happened already.
1178   * The Subject field of this UserGroupInformation object is updated to have
1179   * the new credentials.
1180   * @throws IOException on a failure
1181   */
1182  @InterfaceAudience.Public
1183  @InterfaceStability.Evolving
1184  public synchronized void reloginFromTicketCache()
1185  throws IOException {
1186    if (!isSecurityEnabled() || 
1187        user.getAuthenticationMethod() != AuthenticationMethod.KERBEROS ||
1188        !isKrbTkt)
1189      return;
1190    LoginContext login = getLogin();
1191    if (login == null) {
1192      throw new IOException("login must be done first");
1193    }
1194    long now = Time.now();
1195    if (!hasSufficientTimeElapsed(now)) {
1196      return;
1197    }
1198    // register most recent relogin attempt
1199    user.setLastLogin(now);
1200    try {
1201      if (LOG.isDebugEnabled()) {
1202        LOG.debug("Initiating logout for " + getUserName());
1203      }
1204      //clear up the kerberos state. But the tokens are not cleared! As per 
1205      //the Java kerberos login module code, only the kerberos credentials
1206      //are cleared
1207      login.logout();
1208      //login and also update the subject field of this instance to 
1209      //have the new credentials (pass it to the LoginContext constructor)
1210      login = 
1211        newLoginContext(HadoopConfiguration.USER_KERBEROS_CONFIG_NAME, 
1212            getSubject(), new HadoopConfiguration());
1213      if (LOG.isDebugEnabled()) {
1214        LOG.debug("Initiating re-login for " + getUserName());
1215      }
1216      login.login();
1217      setLogin(login);
1218    } catch (LoginException le) {
1219      throw new IOException("Login failure for " + getUserName() + ": " + le,
1220          le);
1221    } 
1222  }
1223
1224
1225  /**
1226   * Log a user in from a keytab file. Loads a user identity from a keytab
1227   * file and login them in. This new user does not affect the currently
1228   * logged-in user.
1229   * @param user the principal name to load from the keytab
1230   * @param path the path to the keytab file
1231   * @throws IOException if the keytab file can't be read
1232   */
1233  public synchronized
1234  static UserGroupInformation loginUserFromKeytabAndReturnUGI(String user,
1235                                  String path
1236                                  ) throws IOException {
1237    if (!isSecurityEnabled())
1238      return UserGroupInformation.getCurrentUser();
1239    String oldKeytabFile = null;
1240    String oldKeytabPrincipal = null;
1241
1242    long start = 0;
1243    try {
1244      oldKeytabFile = keytabFile;
1245      oldKeytabPrincipal = keytabPrincipal;
1246      keytabFile = path;
1247      keytabPrincipal = user;
1248      Subject subject = new Subject();
1249      
1250      LoginContext login = newLoginContext(
1251          HadoopConfiguration.KEYTAB_KERBEROS_CONFIG_NAME, subject,
1252          new HadoopConfiguration());
1253       
1254      start = Time.now();
1255      login.login();
1256      metrics.loginSuccess.add(Time.now() - start);
1257      UserGroupInformation newLoginUser = new UserGroupInformation(subject);
1258      newLoginUser.setLogin(login);
1259      newLoginUser.setAuthenticationMethod(AuthenticationMethod.KERBEROS);
1260      
1261      return newLoginUser;
1262    } catch (LoginException le) {
1263      if (start > 0) {
1264        metrics.loginFailure.add(Time.now() - start);
1265      }
1266      throw new IOException("Login failure for " + user + " from keytab " + 
1267                            path + ": " + le, le);
1268    } finally {
1269      if(oldKeytabFile != null) keytabFile = oldKeytabFile;
1270      if(oldKeytabPrincipal != null) keytabPrincipal = oldKeytabPrincipal;
1271    }
1272  }
1273
1274  private boolean hasSufficientTimeElapsed(long now) {
1275    if (now - user.getLastLogin() < kerberosMinSecondsBeforeRelogin ) {
1276      LOG.warn("Not attempting to re-login since the last re-login was " +
1277          "attempted less than " + (kerberosMinSecondsBeforeRelogin/1000) +
1278          " seconds before. Last Login=" + user.getLastLogin());
1279      return false;
1280    }
1281    return true;
1282  }
1283  
1284  /**
1285   * Did the login happen via keytab
1286   * @return true or false
1287   */
1288  @InterfaceAudience.Public
1289  @InterfaceStability.Evolving
1290  public synchronized static boolean isLoginKeytabBased() throws IOException {
1291    return getLoginUser().isKeytab;
1292  }
1293
1294  /**
1295   * Did the login happen via ticket cache
1296   * @return true or false
1297   */
1298  public static boolean isLoginTicketBased()  throws IOException {
1299    return getLoginUser().isKrbTkt;
1300  }
1301
1302  /**
1303   * Create a user from a login name. It is intended to be used for remote
1304   * users in RPC, since it won't have any credentials.
1305   * @param user the full user principal name, must not be empty or null
1306   * @return the UserGroupInformation for the remote user.
1307   */
1308  @InterfaceAudience.Public
1309  @InterfaceStability.Evolving
1310  public static UserGroupInformation createRemoteUser(String user) {
1311    return createRemoteUser(user, AuthMethod.SIMPLE);
1312  }
1313  
1314  /**
1315   * Create a user from a login name. It is intended to be used for remote
1316   * users in RPC, since it won't have any credentials.
1317   * @param user the full user principal name, must not be empty or null
1318   * @return the UserGroupInformation for the remote user.
1319   */
1320  @InterfaceAudience.Public
1321  @InterfaceStability.Evolving
1322  public static UserGroupInformation createRemoteUser(String user, AuthMethod authMethod) {
1323    if (user == null || user.isEmpty()) {
1324      throw new IllegalArgumentException("Null user");
1325    }
1326    Subject subject = new Subject();
1327    subject.getPrincipals().add(new User(user));
1328    UserGroupInformation result = new UserGroupInformation(subject);
1329    result.setAuthenticationMethod(authMethod);
1330    return result;
1331  }
1332
1333  /**
1334   * existing types of authentications' methods
1335   */
1336  @InterfaceAudience.Public
1337  @InterfaceStability.Evolving
1338  public static enum AuthenticationMethod {
1339    // currently we support only one auth per method, but eventually a 
1340    // subtype is needed to differentiate, ex. if digest is token or ldap
1341    SIMPLE(AuthMethod.SIMPLE,
1342        HadoopConfiguration.SIMPLE_CONFIG_NAME),
1343    KERBEROS(AuthMethod.KERBEROS,
1344        HadoopConfiguration.USER_KERBEROS_CONFIG_NAME),
1345    TOKEN(AuthMethod.TOKEN),
1346    CERTIFICATE(null),
1347    KERBEROS_SSL(null),
1348    PROXY(null);
1349    
1350    private final AuthMethod authMethod;
1351    private final String loginAppName;
1352    
1353    private AuthenticationMethod(AuthMethod authMethod) {
1354      this(authMethod, null);
1355    }
1356    private AuthenticationMethod(AuthMethod authMethod, String loginAppName) {
1357      this.authMethod = authMethod;
1358      this.loginAppName = loginAppName;
1359    }
1360    
1361    public AuthMethod getAuthMethod() {
1362      return authMethod;
1363    }
1364    
1365    String getLoginAppName() {
1366      if (loginAppName == null) {
1367        throw new UnsupportedOperationException(
1368            this + " login authentication is not supported");
1369      }
1370      return loginAppName;
1371    }
1372    
1373    public static AuthenticationMethod valueOf(AuthMethod authMethod) {
1374      for (AuthenticationMethod value : values()) {
1375        if (value.getAuthMethod() == authMethod) {
1376          return value;
1377        }
1378      }
1379      throw new IllegalArgumentException(
1380          "no authentication method for " + authMethod);
1381    }
1382  };
1383
1384  /**
1385   * Create a proxy user using username of the effective user and the ugi of the
1386   * real user.
1387   * @param user
1388   * @param realUser
1389   * @return proxyUser ugi
1390   */
1391  @InterfaceAudience.Public
1392  @InterfaceStability.Evolving
1393  public static UserGroupInformation createProxyUser(String user,
1394      UserGroupInformation realUser) {
1395    if (user == null || user.isEmpty()) {
1396      throw new IllegalArgumentException("Null user");
1397    }
1398    if (realUser == null) {
1399      throw new IllegalArgumentException("Null real user");
1400    }
1401    Subject subject = new Subject();
1402    Set<Principal> principals = subject.getPrincipals();
1403    principals.add(new User(user));
1404    principals.add(new RealUser(realUser));
1405    UserGroupInformation result =new UserGroupInformation(subject);
1406    result.setAuthenticationMethod(AuthenticationMethod.PROXY);
1407    return result;
1408  }
1409
1410  /**
1411   * get RealUser (vs. EffectiveUser)
1412   * @return realUser running over proxy user
1413   */
1414  @InterfaceAudience.Public
1415  @InterfaceStability.Evolving
1416  public UserGroupInformation getRealUser() {
1417    for (RealUser p: subject.getPrincipals(RealUser.class)) {
1418      return p.getRealUser();
1419    }
1420    return null;
1421  }
1422
1423
1424  
1425  /**
1426   * This class is used for storing the groups for testing. It stores a local
1427   * map that has the translation of usernames to groups.
1428   */
1429  private static class TestingGroups extends Groups {
1430    private final Map<String, List<String>> userToGroupsMapping = 
1431      new HashMap<String,List<String>>();
1432    private Groups underlyingImplementation;
1433    
1434    private TestingGroups(Groups underlyingImplementation) {
1435      super(new org.apache.hadoop.conf.Configuration());
1436      this.underlyingImplementation = underlyingImplementation;
1437    }
1438    
1439    @Override
1440    public List<String> getGroups(String user) throws IOException {
1441      List<String> result = userToGroupsMapping.get(user);
1442      
1443      if (result == null) {
1444        result = underlyingImplementation.getGroups(user);
1445      }
1446
1447      return result;
1448    }
1449
1450    private void setUserGroups(String user, String[] groups) {
1451      userToGroupsMapping.put(user, Arrays.asList(groups));
1452    }
1453  }
1454
1455  /**
1456   * Create a UGI for testing HDFS and MapReduce
1457   * @param user the full user principal name
1458   * @param userGroups the names of the groups that the user belongs to
1459   * @return a fake user for running unit tests
1460   */
1461  @InterfaceAudience.Public
1462  @InterfaceStability.Evolving
1463  public static UserGroupInformation createUserForTesting(String user, 
1464                                                          String[] userGroups) {
1465    ensureInitialized();
1466    UserGroupInformation ugi = createRemoteUser(user);
1467    // make sure that the testing object is setup
1468    if (!(groups instanceof TestingGroups)) {
1469      groups = new TestingGroups(groups);
1470    }
1471    // add the user groups
1472    ((TestingGroups) groups).setUserGroups(ugi.getShortUserName(), userGroups);
1473    return ugi;
1474  }
1475
1476
1477  /**
1478   * Create a proxy user UGI for testing HDFS and MapReduce
1479   * 
1480   * @param user
1481   *          the full user principal name for effective user
1482   * @param realUser
1483   *          UGI of the real user
1484   * @param userGroups
1485   *          the names of the groups that the user belongs to
1486   * @return a fake user for running unit tests
1487   */
1488  public static UserGroupInformation createProxyUserForTesting(String user,
1489      UserGroupInformation realUser, String[] userGroups) {
1490    ensureInitialized();
1491    UserGroupInformation ugi = createProxyUser(user, realUser);
1492    // make sure that the testing object is setup
1493    if (!(groups instanceof TestingGroups)) {
1494      groups = new TestingGroups(groups);
1495    }
1496    // add the user groups
1497    ((TestingGroups) groups).setUserGroups(ugi.getShortUserName(), userGroups);
1498    return ugi;
1499  }
1500  
1501  /**
1502   * Get the user's login name.
1503   * @return the user's name up to the first '/' or '@'.
1504   */
1505  public String getShortUserName() {
1506    for (User p: subject.getPrincipals(User.class)) {
1507      return p.getShortName();
1508    }
1509    return null;
1510  }
1511
1512  public String getPrimaryGroupName() throws IOException {
1513    List<String> groups = getGroups();
1514    if (groups.isEmpty()) {
1515      throw new IOException("There is no primary group for UGI " + this);
1516    }
1517    return groups.get(0);
1518  }
1519
1520  /**
1521   * Get the user's full principal name.
1522   * @return the user's full principal name.
1523   */
1524  @InterfaceAudience.Public
1525  @InterfaceStability.Evolving
1526  public String getUserName() {
1527    return user.getName();
1528  }
1529
1530  /**
1531   * Add a TokenIdentifier to this UGI. The TokenIdentifier has typically been
1532   * authenticated by the RPC layer as belonging to the user represented by this
1533   * UGI.
1534   * 
1535   * @param tokenId
1536   *          tokenIdentifier to be added
1537   * @return true on successful add of new tokenIdentifier
1538   */
1539  public synchronized boolean addTokenIdentifier(TokenIdentifier tokenId) {
1540    return subject.getPublicCredentials().add(tokenId);
1541  }
1542
1543  /**
1544   * Get the set of TokenIdentifiers belonging to this UGI
1545   * 
1546   * @return the set of TokenIdentifiers belonging to this UGI
1547   */
1548  public synchronized Set<TokenIdentifier> getTokenIdentifiers() {
1549    return subject.getPublicCredentials(TokenIdentifier.class);
1550  }
1551  
1552  /**
1553   * Add a token to this UGI
1554   * 
1555   * @param token Token to be added
1556   * @return true on successful add of new token
1557   */
1558  public boolean addToken(Token<? extends TokenIdentifier> token) {
1559    return (token != null) ? addToken(token.getService(), token) : false;
1560  }
1561
1562  /**
1563   * Add a named token to this UGI
1564   * 
1565   * @param alias Name of the token
1566   * @param token Token to be added
1567   * @return true on successful add of new token
1568   */
1569  public boolean addToken(Text alias, Token<? extends TokenIdentifier> token) {
1570    synchronized (subject) {
1571      getCredentialsInternal().addToken(alias, token);
1572      return true;
1573    }
1574  }
1575  
1576  /**
1577   * Obtain the collection of tokens associated with this user.
1578   * 
1579   * @return an unmodifiable collection of tokens associated with user
1580   */
1581  public Collection<Token<? extends TokenIdentifier>> getTokens() {
1582    synchronized (subject) {
1583      return Collections.unmodifiableCollection(
1584          new ArrayList<Token<?>>(getCredentialsInternal().getAllTokens()));
1585    }
1586  }
1587
1588  /**
1589   * Obtain the tokens in credentials form associated with this user.
1590   * 
1591   * @return Credentials of tokens associated with this user
1592   */
1593  public Credentials getCredentials() {
1594    synchronized (subject) {
1595      Credentials creds = new Credentials(getCredentialsInternal());
1596      Iterator<Token<?>> iter = creds.getAllTokens().iterator();
1597      while (iter.hasNext()) {
1598        if (iter.next() instanceof Token.PrivateToken) {
1599          iter.remove();
1600        }
1601      }
1602      return creds;
1603    }
1604  }
1605  
1606  /**
1607   * Add the given Credentials to this user.
1608   * @param credentials of tokens and secrets
1609   */
1610  public void addCredentials(Credentials credentials) {
1611    synchronized (subject) {
1612      getCredentialsInternal().addAll(credentials);
1613    }
1614  }
1615
1616  private synchronized Credentials getCredentialsInternal() {
1617    final Credentials credentials;
1618    final Set<Credentials> credentialsSet =
1619      subject.getPrivateCredentials(Credentials.class);
1620    if (!credentialsSet.isEmpty()){
1621      credentials = credentialsSet.iterator().next();
1622    } else {
1623      credentials = new Credentials();
1624      subject.getPrivateCredentials().add(credentials);
1625    }
1626    return credentials;
1627  }
1628
1629  /**
1630   * Get the group names for this user. {@ #getGroups(String)} is less
1631   * expensive alternative when checking for a contained element.
1632   * @return the list of users with the primary group first. If the command
1633   *    fails, it returns an empty list.
1634   */
1635  public String[] getGroupNames() {
1636    List<String> groups = getGroups();
1637    return groups.toArray(new String[groups.size()]);
1638  }
1639
1640  /**
1641   * Get the group names for this user.
1642   * @return the list of users with the primary group first. If the command
1643   *    fails, it returns an empty list.
1644   */
1645  public List<String> getGroups() {
1646    ensureInitialized();
1647    try {
1648      return groups.getGroups(getShortUserName());
1649    } catch (IOException ie) {
1650      if (LOG.isDebugEnabled()) {
1651        LOG.debug("Failed to get groups for user " + getShortUserName()
1652            + " by " + ie);
1653        LOG.trace("TRACE", ie);
1654      }
1655      return Collections.emptyList();
1656    }
1657  }
1658
1659  /**
1660   * Return the username.
1661   */
1662  @Override
1663  public String toString() {
1664    StringBuilder sb = new StringBuilder(getUserName());
1665    sb.append(" (auth:"+getAuthenticationMethod()+")");
1666    if (getRealUser() != null) {
1667      sb.append(" via ").append(getRealUser().toString());
1668    }
1669    return sb.toString();
1670  }
1671
1672  /**
1673   * Sets the authentication method in the subject
1674   * 
1675   * @param authMethod
1676   */
1677  public synchronized 
1678  void setAuthenticationMethod(AuthenticationMethod authMethod) {
1679    user.setAuthenticationMethod(authMethod);
1680  }
1681
1682  /**
1683   * Sets the authentication method in the subject
1684   * 
1685   * @param authMethod
1686   */
1687  public void setAuthenticationMethod(AuthMethod authMethod) {
1688    user.setAuthenticationMethod(AuthenticationMethod.valueOf(authMethod));
1689  }
1690
1691  /**
1692   * Get the authentication method from the subject
1693   * 
1694   * @return AuthenticationMethod in the subject, null if not present.
1695   */
1696  public synchronized AuthenticationMethod getAuthenticationMethod() {
1697    return user.getAuthenticationMethod();
1698  }
1699
1700  /**
1701   * Get the authentication method from the real user's subject.  If there
1702   * is no real user, return the given user's authentication method.
1703   * 
1704   * @return AuthenticationMethod in the subject, null if not present.
1705   */
1706  public synchronized AuthenticationMethod getRealAuthenticationMethod() {
1707    UserGroupInformation ugi = getRealUser();
1708    if (ugi == null) {
1709      ugi = this;
1710    }
1711    return ugi.getAuthenticationMethod();
1712  }
1713
1714  /**
1715   * Returns the authentication method of a ugi. If the authentication method is
1716   * PROXY, returns the authentication method of the real user.
1717   * 
1718   * @param ugi
1719   * @return AuthenticationMethod
1720   */
1721  public static AuthenticationMethod getRealAuthenticationMethod(
1722      UserGroupInformation ugi) {
1723    AuthenticationMethod authMethod = ugi.getAuthenticationMethod();
1724    if (authMethod == AuthenticationMethod.PROXY) {
1725      authMethod = ugi.getRealUser().getAuthenticationMethod();
1726    }
1727    return authMethod;
1728  }
1729
1730  /**
1731   * Compare the subjects to see if they are equal to each other.
1732   */
1733  @Override
1734  public boolean equals(Object o) {
1735    if (o == this) {
1736      return true;
1737    } else if (o == null || getClass() != o.getClass()) {
1738      return false;
1739    } else {
1740      return subject == ((UserGroupInformation) o).subject;
1741    }
1742  }
1743
1744  /**
1745   * Return the hash of the subject.
1746   */
1747  @Override
1748  public int hashCode() {
1749    return System.identityHashCode(subject);
1750  }
1751
1752  /**
1753   * Get the underlying subject from this ugi.
1754   * @return the subject that represents this user.
1755   */
1756  protected Subject getSubject() {
1757    return subject;
1758  }
1759
1760  /**
1761   * Run the given action as the user.
1762   * @param <T> the return type of the run method
1763   * @param action the method to execute
1764   * @return the value from the run method
1765   */
1766  @InterfaceAudience.Public
1767  @InterfaceStability.Evolving
1768  public <T> T doAs(PrivilegedAction<T> action) {
1769    logPrivilegedAction(subject, action);
1770    return Subject.doAs(subject, action);
1771  }
1772  
1773  /**
1774   * Run the given action as the user, potentially throwing an exception.
1775   * @param <T> the return type of the run method
1776   * @param action the method to execute
1777   * @return the value from the run method
1778   * @throws IOException if the action throws an IOException
1779   * @throws Error if the action throws an Error
1780   * @throws RuntimeException if the action throws a RuntimeException
1781   * @throws InterruptedException if the action throws an InterruptedException
1782   * @throws UndeclaredThrowableException if the action throws something else
1783   */
1784  @InterfaceAudience.Public
1785  @InterfaceStability.Evolving
1786  public <T> T doAs(PrivilegedExceptionAction<T> action
1787                    ) throws IOException, InterruptedException {
1788    try {
1789      logPrivilegedAction(subject, action);
1790      return Subject.doAs(subject, action);
1791    } catch (PrivilegedActionException pae) {
1792      Throwable cause = pae.getCause();
1793      if (LOG.isDebugEnabled()) {
1794        LOG.debug("PrivilegedActionException as:" + this + " cause:" + cause);
1795      }
1796      if (cause == null) {
1797        throw new RuntimeException("PrivilegedActionException with no " +
1798                "underlying cause. UGI [" + this + "]" +": " + pae, pae);
1799      } else if (cause instanceof IOException) {
1800        throw (IOException) cause;
1801      } else if (cause instanceof Error) {
1802        throw (Error) cause;
1803      } else if (cause instanceof RuntimeException) {
1804        throw (RuntimeException) cause;
1805      } else if (cause instanceof InterruptedException) {
1806        throw (InterruptedException) cause;
1807      } else {
1808        throw new UndeclaredThrowableException(cause);
1809      }
1810    }
1811  }
1812
1813  private void logPrivilegedAction(Subject subject, Object action) {
1814    if (LOG.isDebugEnabled()) {
1815      // would be nice if action included a descriptive toString()
1816      String where = new Throwable().getStackTrace()[2].toString();
1817      LOG.debug("PrivilegedAction as:"+this+" from:"+where);
1818    }
1819  }
1820
1821  private void print() throws IOException {
1822    System.out.println("User: " + getUserName());
1823    System.out.print("Group Ids: ");
1824    System.out.println();
1825    String[] groups = getGroupNames();
1826    System.out.print("Groups: ");
1827    for(int i=0; i < groups.length; i++) {
1828      System.out.print(groups[i] + " ");
1829    }
1830    System.out.println();    
1831  }
1832
1833  /**
1834   * A test method to print out the current user's UGI.
1835   * @param args if there are two arguments, read the user from the keytab
1836   * and print it out.
1837   * @throws Exception
1838   */
1839  public static void main(String [] args) throws Exception {
1840  System.out.println("Getting UGI for current user");
1841    UserGroupInformation ugi = getCurrentUser();
1842    ugi.print();
1843    System.out.println("UGI: " + ugi);
1844    System.out.println("Auth method " + ugi.user.getAuthenticationMethod());
1845    System.out.println("Keytab " + ugi.isKeytab);
1846    System.out.println("============================================================");
1847    
1848    if (args.length == 2) {
1849      System.out.println("Getting UGI from keytab....");
1850      loginUserFromKeytab(args[0], args[1]);
1851      getCurrentUser().print();
1852      System.out.println("Keytab: " + ugi);
1853      System.out.println("Auth method " + loginUser.user.getAuthenticationMethod());
1854      System.out.println("Keytab " + loginUser.isKeytab);
1855    }
1856  }
1857}