org.apache.hadoop.security
Class UserGroupInformation

java.lang.Object
  extended by 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