## org.apache.hadoop.security
Class UserGroupInformation

    java.lang.Object
      org.apache.hadoop.security.UserGroupInformation

    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.

Nested Class Summary
`static class` `UserGroupInformation.AuthenticationMethod` existing types of authentications' methods
`static class` `UserGroupInformation.HadoopLoginModule` A login module that looks at the Kerberos, Unix, or Windows principal and adds the corresponding UserName.

Field Summary
`static String` `HADOOP_TOKEN_FILE_LOCATION` Environment variable pointing to the token cache file

Method Summary
`boolean` `addToken(Token<? extends TokenIdentifier> token)` Add a token to this UGI
`boolean` `addTokenIdentifier(TokenIdentifier tokenId)` Add a TokenIdentifier to this UGI.
`void` `checkTGTAndReloginFromKeytab()` Re-login a user from keytab if TGT is expired or is close to expiry.
`static UserGroupInformation` `createProxyUser(String user, UserGroupInformation realUser)` Create a proxy user using username of the effective user and the ugi of the real user.
`static UserGroupInformation` `createProxyUserForTesting(String user, UserGroupInformation realUser, String[] userGroups)` Create a proxy user UGI for testing HDFS and MapReduce
`static UserGroupInformation` `createRemoteUser(String user)` Create a user from a login name.
`static UserGroupInformation` `createUserForTesting(String user, String[] userGroups)` Create a UGI for testing HDFS and MapReduce

`

`<T> T`

`

`doAs(PrivilegedAction<T> action)`
Run the given action as the user.

`

`<T> T`

`

`doAs(PrivilegedExceptionAction<T> action)`
Run the given action as the user, potentially throwing an exception.

`boolean` `equals(Object o)` Compare the subjects to see if they are equal to each other.
`UserGroupInformation.AuthenticationMethod` `getAuthenticationMethod()` Get the authentication method from the subject
`static UserGroupInformation` `getCurrentUser()` Return the current user, including any doAs in the current stack.
`String[]` `getGroupNames()` Get the group names for this user.
`static UserGroupInformation` `getLoginUser()` Get the currently logged in user.
`UserGroupInformation` `getRealUser()` get RealUser (vs.
`String` `getShortUserName()` Get the user's login name.
`protected Subject` `getSubject()` Get the underlying subject from this ugi.
`Set<TokenIdentifier>` `getTokenIdentifiers()` Get the set of TokenIdentifiers belonging to this UGI
`Collection<Token<? extends TokenIdentifier>>` `getTokens()` Obtain the collection of tokens associated with this user.
`String` `getUserName()` Get the user's full principal name.
`int` `hashCode()` Return the hash of the subject.
`boolean` `hasKerberosCredentials()` checks if logged in using kerberos
`boolean` `isFromKeytab()` Is this user logged in from a keytab file?
`static boolean` `isLoginKeytabBased()` Did the login happen via keytab
`static boolean` `isSecurityEnabled()` Determine if UserGroupInformation is using Kerberos to determine user identities or is relying on simple authentication
`static void` `loginUserFromKeytab(String user, String path)` Log a user in from a keytab file.
`static UserGroupInformation` `loginUserFromKeytabAndReturnUGI(String user, String path)` Log a user in from a keytab file.
`static void` `main(String[] args)` A test method to print out the current user's UGI.
`void` `reloginFromKeytab()` Re-Login a user in from a keytab file.
`void` `reloginFromTicketCache()` Re-Login a user in from the ticket cache.
`void` `setAuthenticationMethod(UserGroupInformation.AuthenticationMethod authMethod)` Sets the authentication method in the subject
`static void` `setConfiguration(Configuration conf)` Set the static configuration for UGI.
`String` `toString()` Return the username.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### HADOOP_TOKEN_FILE_LOCATION

    public static final String HADOOP_TOKEN_FILE_LOCATION

  Environment variable pointing to the token cache file

  See Also:
    Constant Field Values

Method Detail

### setConfiguration

    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

### 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

### 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 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

### getLoginUser

    public static UserGroupInformation getLoginUser()
                                             throws IOException

  Get the currently logged in user.

  Returns:
    the logged in user
  Throws:
    `IOException` - if login fails

### isFromKeytab

    public boolean isFromKeytab()

  Is this user logged in from a keytab file?

  Returns:
    true if the credentials are from a keytab file.

### loginUserFromKeytab

    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` - if the keytab file can't be read

### reloginFromTicketCache

    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` - 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
  Throws:
    `IOException` - if the keytab file can't be read

### checkTGTAndReloginFromKeytab

    public void checkTGTAndReloginFromKeytab()
                                      throws IOException

  Re-login a user from keytab if TGT is expired or is close to expiry.

  Throws:
    `IOException`

### reloginFromKeytab

    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` - on a failure

### isLoginKeytabBased

    public static boolean isLoginKeytabBased()
                                      throws IOException

  Did the login happen via keytab

  Returns:
    true or false
  Throws:
    `IOException`

### createRemoteUser

    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.

### createProxyUser

    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` -
    `realUser` -
  Returns:
    proxyUser ugi

### getRealUser

    public UserGroupInformation getRealUser()

  get RealUser (vs. EffectiveUser)

  Returns:
    realUser running over proxy user

### createUserForTesting

    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 '@'.

### getUserName

    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

### 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

### getGroupNames

    public String[] getGroupNames()

  Get the group names for this user.

  Returns:
    the list of users with the primary group first. If the command fails, it returns an empty list.

### 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` -

### getAuthenticationMethod

    public UserGroupInformation.AuthenticationMethod getAuthenticationMethod()

  Get the authentication method from the subject

  Returns:
    AuthenticationMethod in the subject, null if not present.

### 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 <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 <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

### 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`

Copyright © 2009 The Apache Software Foundation