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