Package org.apache.hadoop.security

Class UserGroupInformation

java.lang.Object
org.apache.hadoop.security.UserGroupInformation
@Public @Evolving public class UserGroupInformation extends Object
User and group information for Hadoop. This class wraps around a JAAS Subject and provides methods to determine the user's username and groups. It supports both the Windows, Unix and Kerberos login modules.

  • Field Details

    • HADOOP_TOKEN_FILE_LOCATION

      public static final String HADOOP_TOKEN_FILE_LOCATION
      Environment variable pointing to the token cache file
      See Also:

    • HADOOP_TOKEN

      public static final String HADOOP_TOKEN
      Environment variable pointing to the base64 tokens.
      See Also:

  • Method Details

    • setShouldRenewImmediatelyForTests

      @VisibleForTesting public static void setShouldRenewImmediatelyForTests(boolean immediate)
      For the purposes of unit tests, we want to test login from keytab and don't want to wait until the renew window (controlled by TICKET_RENEW_WINDOW).
      Parameters:
      immediate - true if we should login without waiting for ticket window

    • reattachMetrics

      public static void reattachMetrics()
      Reattach the class's metrics to a new metric system.

    • isInitialized

      public static boolean isInitialized()

    • setConfiguration

      @Public @Evolving public static void setConfiguration(Configuration conf)
      Set the static configuration for UGI. In particular, set the security authentication mechanism and the group look up service.
      Parameters:
      conf - the configuration to use

    • reset

      @Private @VisibleForTesting public static void reset()

    • isSecurityEnabled

      public static boolean isSecurityEnabled()
      Determine if UserGroupInformation is using Kerberos to determine user identities or is relying on simple authentication
      Returns:
      true if UGI is working in a secure environment

    • isLoginSuccess

      public boolean isLoginSuccess()
      This method checks for a successful Kerberos login and returns true by default if it is not using Kerberos.
      Returns:
      true on successful login

    • hasKerberosCredentials

      public boolean hasKerberosCredentials()
      checks if logged in using kerberos
      Returns:
      true if the subject logged via keytab or has a Kerberos TGT

    • getCurrentUser

      @Public @Evolving public static UserGroupInformation getCurrentUser() throws IOException
      Return the current user, including any doAs in the current stack.
      Returns:
      the current user
      Throws:
      IOException - if login fails

    • getBestUGI

      public static UserGroupInformation getBestUGI(String ticketCachePath, String user) throws IOException
      Find the most appropriate UserGroupInformation to use
      Parameters:
      ticketCachePath - The Kerberos ticket cache path, or NULL if none is specfied
      user - The user name, or NULL if none is specified.
      Returns:
      The most appropriate UserGroupInformation
      Throws:
      IOException - raised on errors performing I/O.

    • getUGIFromTicketCache

      @Public @Evolving public static UserGroupInformation getUGIFromTicketCache(String ticketCache, String user) throws IOException
      Create a UserGroupInformation from a Kerberos ticket cache.
      Parameters:
      user - The principal name to load from the ticket cache
      ticketCache - the path to the ticket cache file
      Returns:
      UserGroupInformation.
      Throws:
      IOException - if the kerberos login fails

    • getUGIFromSubject

      public static UserGroupInformation getUGIFromSubject(Subject subject) throws IOException
      Create a UserGroupInformation from a Subject with Kerberos principal.
      Parameters:
      subject - The KerberosPrincipal to use in UGI. The creator of subject is responsible for renewing credentials.
      Returns:
      UserGroupInformation
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - if the kerberos login fails

    • getLoginUser

      @Public @Evolving public static UserGroupInformation getLoginUser() throws IOException
      Get the currently logged in user. If no explicit login has occurred, the user will automatically be logged in with either kerberos credentials if available, or as the local OS user, based on security settings.
      Returns:
      the logged in user
      Throws:
      IOException - if login fails

    • trimLoginMethod

      public static String trimLoginMethod(String userName)
      remove the login method that is followed by a space from the username e.g. "jack (auth:SIMPLE)" -> "jack"
      Parameters:
      userName - userName.
      Returns:
      userName without login method

    • loginUserFromSubject

      @Public @Evolving public static void loginUserFromSubject(Subject subject) throws IOException
      Log in a user using the given subject
      Parameters:
      subject - the subject to use when logging in a user, or null to create a new subject. If subject is not null, the creator of subject is responsible for renewing credentials.
      Throws:
      IOException - if login fails

    • setLoginUser

      @Private @Unstable @VisibleForTesting public static void setLoginUser(UserGroupInformation ugi)

    • isFromKeytab

      public boolean isFromKeytab()
      Is this user logged in from a keytab file managed by the UGI?
      Returns:
      true if the credentials are from a keytab file.

    • shouldRelogin

      @Private @Unstable public boolean shouldRelogin()

    • loginUserFromKeytab

      @Public @Evolving public static void loginUserFromKeytab(String user, String path) throws IOException
      Log a user in from a keytab file. Loads a user identity from a keytab file and logs them in. They become the currently logged-in user.
      Parameters:
      user - the principal name to load from the keytab
      path - the path to the keytab file
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - if it's a kerberos login exception.

    • logoutUserFromKeytab

      @Public @Evolving public void logoutUserFromKeytab() throws IOException
      Log the current user out who previously logged in using keytab. This method assumes that the user logged in by calling loginUserFromKeytab(String, String).
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - if a failure occurred in logout, or if the user did not log in by invoking loginUserFromKeyTab() before.

    • checkTGTAndReloginFromKeytab

      public void checkTGTAndReloginFromKeytab() throws IOException
      Re-login a user from keytab if TGT is expired or is close to expiry.
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - if it's a kerberos login exception.

    • reloginFromKeytab

      @Public @Evolving public void reloginFromKeytab() throws IOException
      Re-Login a user in from a keytab file. Loads a user identity from a keytab file and logs them in. They become the currently logged-in user. This method assumes that loginUserFromKeytab(String, String) had happened already. The Subject field of this UserGroupInformation object is updated to have the new credentials.
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - on a failure

    • forceReloginFromKeytab

      @Public @Evolving public void forceReloginFromKeytab() throws IOException
      Force re-Login a user in from a keytab file irrespective of the last login time. Loads a user identity from a keytab file and logs them in. They become the currently logged-in user. This method assumes that loginUserFromKeytab(String, String) had happened already. The Subject field of this UserGroupInformation object is updated to have the new credentials.
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - on a failure

    • forceReloginFromTicketCache

      @Public @Evolving public void forceReloginFromTicketCache() throws IOException
      Force re-Login a user in from the ticket cache irrespective of the last login time. This method assumes that login had happened already. The Subject field of this UserGroupInformation object is updated to have the new credentials.
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - on a failure

    • reloginFromTicketCache

      @Public @Evolving public void reloginFromTicketCache() throws IOException
      Re-Login a user in from the ticket cache. This method assumes that login had happened already. The Subject field of this UserGroupInformation object is updated to have the new credentials.
      Throws:
      IOException - raised on errors performing I/O.
      KerberosAuthException - on a failure

    • loginUserFromKeytabAndReturnUGI

      public static UserGroupInformation loginUserFromKeytabAndReturnUGI(String user, String path) throws IOException
      Log a user in from a keytab file. Loads a user identity from a keytab file and login them in. This new user does not affect the currently logged-in user.
      Parameters:
      user - the principal name to load from the keytab
      path - the path to the keytab file
      Returns:
      UserGroupInformation.
      Throws:
      IOException - if the keytab file can't be read

    • isLoginKeytabBased

      @Public @Evolving public static boolean isLoginKeytabBased() throws IOException
      Did the login happen via keytab.
      Returns:
      true or false
      Throws:
      IOException - raised on errors performing I/O.

    • isLoginTicketBased

      public static boolean isLoginTicketBased() throws IOException
      Did the login happen via ticket cache.
      Returns:
      true or false
      Throws:
      IOException - raised on errors performing I/O.

    • createRemoteUser

      @Public @Evolving public static UserGroupInformation createRemoteUser(String user)
      Create a user from a login name. It is intended to be used for remote users in RPC, since it won't have any credentials.
      Parameters:
      user - the full user principal name, must not be empty or null
      Returns:
      the UserGroupInformation for the remote user.

    • createRemoteUser

      @Public @Evolving public static UserGroupInformation createRemoteUser(String user, SaslRpcServer.AuthMethod authMethod)
      Create a user from a login name. It is intended to be used for remote users in RPC, since it won't have any credentials.
      Parameters:
      user - the full user principal name, must not be empty or null
      authMethod - authMethod.
      Returns:
      the UserGroupInformation for the remote user.

    • createProxyUser

      @Public @Evolving public static UserGroupInformation createProxyUser(String user, UserGroupInformation realUser)
      Create a proxy user using username of the effective user and the ugi of the real user.
      Parameters:
      user - user.
      realUser - realUser.
      Returns:
      proxyUser ugi

    • getRealUser

      @Public @Evolving public UserGroupInformation getRealUser()
      get RealUser (vs. EffectiveUser)
      Returns:
      realUser running over proxy user

    • getRealUserOrSelf

      public static UserGroupInformation getRealUserOrSelf(UserGroupInformation user)
      If this is a proxy user, get the real user. Otherwise, return this user.
      Parameters:
      user - the user to check
      Returns:
      the real user or self

    • createUserForTesting

      @Public @Evolving public static UserGroupInformation createUserForTesting(String user, String[] userGroups)
      Create a UGI for testing HDFS and MapReduce
      Parameters:
      user - the full user principal name
      userGroups - the names of the groups that the user belongs to
      Returns:
      a fake user for running unit tests

    • createProxyUserForTesting

      public static UserGroupInformation createProxyUserForTesting(String user, UserGroupInformation realUser, String[] userGroups)
      Create a proxy user UGI for testing HDFS and MapReduce
      Parameters:
      user - the full user principal name for effective user
      realUser - UGI of the real user
      userGroups - the names of the groups that the user belongs to
      Returns:
      a fake user for running unit tests

    • getShortUserName

      public String getShortUserName()
      Get the user's login name.
      Returns:
      the user's name up to the first '/' or '@'.

    • getPrimaryGroupName

      public String getPrimaryGroupName() throws IOException
      Throws:
      IOException

    • getUserName

      @Public @Evolving public String getUserName()
      Get the user's full principal name.
      Returns:
      the user's full principal name.

    • addTokenIdentifier

      public boolean addTokenIdentifier(TokenIdentifier tokenId)
      Add a TokenIdentifier to this UGI. The TokenIdentifier has typically been authenticated by the RPC layer as belonging to the user represented by this UGI.
      Parameters:
      tokenId - tokenIdentifier to be added
      Returns:
      true on successful add of new tokenIdentifier

    • getTokenIdentifiers

      public Set<TokenIdentifier> getTokenIdentifiers()
      Get the set of TokenIdentifiers belonging to this UGI
      Returns:
      the set of TokenIdentifiers belonging to this UGI

    • addToken

      public boolean addToken(Token<? extends TokenIdentifier> token)
      Add a token to this UGI
      Parameters:
      token - Token to be added
      Returns:
      true on successful add of new token

    • addToken

      public boolean addToken(Text alias, Token<? extends TokenIdentifier> token)
      Add a named token to this UGI
      Parameters:
      alias - Name of the token
      token - Token to be added
      Returns:
      true on successful add of new token

    • removeToken

      public void removeToken(Text alias)
      Remove a named token from this UGI.
      Parameters:
      alias - Name of the token

    • getTokens

      public Collection<Token<? extends TokenIdentifier>> getTokens()
      Obtain the collection of tokens associated with this user.
      Returns:
      an unmodifiable collection of tokens associated with user

    • getCredentials

      public Credentials getCredentials()
      Obtain the tokens in credentials form associated with this user.
      Returns:
      Credentials of tokens associated with this user

    • addCredentials

      public void addCredentials(Credentials credentials)
      Add the given Credentials to this user.
      Parameters:
      credentials - of tokens and secrets

    • getGroupNames

      public String[] getGroupNames()
      Get the group names for this user. getGroupsSet() is less expensive alternative when checking for a contained element.
      Returns:
      the list of users with the primary group first. If the command fails, it returns an empty list.

    • getGroups

      @Deprecated public List<String> getGroups()
      Deprecated.
      Use getGroupsSet() instead.
      Get the group names for this user. getGroupsSet() is less expensive alternative when checking for a contained element.
      Returns:
      the list of users with the primary group first. If the command fails, it returns an empty list.

    • getGroupsSet

      public Set<String> getGroupsSet()
      Get the groups names for the user as a Set.
      Returns:
      the set of users with the primary group first. If the command fails, it returns an empty set.

    • toString

      public String toString()
      Return the username.
      Overrides:
      toString in class Object

    • setAuthenticationMethod

      public void setAuthenticationMethod(UserGroupInformation.AuthenticationMethod authMethod)
      Sets the authentication method in the subject
      Parameters:
      authMethod - authMethod.

    • setAuthenticationMethod

      public void setAuthenticationMethod(SaslRpcServer.AuthMethod authMethod)
      Sets the authentication method in the subject
      Parameters:
      authMethod - authMethod.

    • getAuthenticationMethod

      public UserGroupInformation.AuthenticationMethod getAuthenticationMethod()
      Get the authentication method from the subject
      Returns:
      AuthenticationMethod in the subject, null if not present.

    • getRealAuthenticationMethod

      public UserGroupInformation.AuthenticationMethod getRealAuthenticationMethod()
      Get the authentication method from the real user's subject. If there is no real user, return the given user's authentication method.
      Returns:
      AuthenticationMethod in the subject, null if not present.

    • getRealAuthenticationMethod

      public static UserGroupInformation.AuthenticationMethod getRealAuthenticationMethod(UserGroupInformation ugi)
      Returns the authentication method of a ugi. If the authentication method is PROXY, returns the authentication method of the real user.
      Parameters:
      ugi - ugi.
      Returns:
      AuthenticationMethod

    • equals

      public boolean equals(Object o)
      Compare the subjects to see if they are equal to each other.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Return the hash of the subject.
      Overrides:
      hashCode in class Object

    • getSubject

      protected Subject getSubject()
      Get the underlying subject from this ugi.
      Returns:
      the subject that represents this user.

    • doAs

      @Public @Evolving public <T> T doAs(PrivilegedAction<T> action)
      Run the given action as the user.
      Type Parameters:
      T - the return type of the run method
      Parameters:
      action - the method to execute
      Returns:
      the value from the run method

    • doAs

      @Public @Evolving public <T> T doAs(PrivilegedExceptionAction<T> action) throws IOException, InterruptedException
      Run the given action as the user, potentially throwing an exception.
      Type Parameters:
      T - the return type of the run method
      Parameters:
      action - the method to execute
      Returns:
      the value from the run method
      Throws:
      IOException - if the action throws an IOException
      Error - if the action throws an Error
      RuntimeException - if the action throws a RuntimeException
      InterruptedException - if the action throws an InterruptedException
      UndeclaredThrowableException - if the action throws something else

    • logUserInfo

      @LimitedPrivate({"HDFS","KMS"}) @Unstable public static void logUserInfo(org.slf4j.Logger log, String caption, UserGroupInformation ugi)
      Log current UGI and token information into specified log.
      Parameters:
      ugi - - UGI
      log - log.
      caption - caption.

    • logAllUserInfo

      @LimitedPrivate({"HDFS","KMS"}) @Unstable public static void logAllUserInfo(org.slf4j.Logger log, UserGroupInformation ugi) throws IOException
      Log all (current, real, login) UGI and token info into specified log.
      Parameters:
      ugi - - UGI
      log - - log.
      Throws:
      IOException - raised on errors performing I/O.

    • logAllUserInfo

      public static void logAllUserInfo(UserGroupInformation ugi) throws IOException
      Log all (current, real, login) UGI and token info into UGI debug log.
      Parameters:
      ugi - - UGI
      Throws:
      IOException - raised on errors performing I/O.

    • main

      public static void main(String[] args) throws Exception
      A test method to print out the current user's UGI.
      Parameters:
      args - if there are two arguments, read the user from the keytab and print it out.
      Throws:
      Exception - Exception.