org.apache.hadoop.security

Class UserGroupInformation

java.lang.Object

org.apache.hadoop.security.UserGroupInformation

@InterfaceAudience.Public
 @InterfaceStability.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UserGroupInformation.AuthenticationMethod existing types of authentications' methods

Field Summary

Fields

Modifier and Type	Field and Description
static String	HADOOP_TOKEN_FILE_LOCATION Environment variable pointing to the token cache file

Method Summary

Modifier and Type	Method and Description
void	addCredentials(Credentials credentials) Add the given Credentials to this user.
boolean	addToken(Text alias, Token<? extends TokenIdentifier> token) Add a named token to this UGI
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	createRemoteUser(String user, org.apache.hadoop.security.SaslRpcServer.AuthMethod authMethod) 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.
void	forceReloginFromKeytab() Force re-Login a user in from a keytab file irrespective of the last login time.
UserGroupInformation.AuthenticationMethod	getAuthenticationMethod() Get the authentication method from the subject
static UserGroupInformation	getBestUGI(String ticketCachePath, String user) Find the most appropriate UserGroupInformation to use
Credentials	getCredentials() Obtain the tokens in credentials form associated with this user.
static UserGroupInformation	getCurrentUser() Return the current user, including any doAs in the current stack.
String[]	getGroupNames() Get the group names for this user.
List<String>	getGroups() Get the group names for this user.
static UserGroupInformation	getLoginUser() Get the currently logged in user.
String	getPrimaryGroupName()
UserGroupInformation.AuthenticationMethod	getRealAuthenticationMethod() Get the authentication method from the real user's subject.
static UserGroupInformation.AuthenticationMethod	getRealAuthenticationMethod(UserGroupInformation ugi) Returns the authentication method of a ugi.
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.
static UserGroupInformation	getUGIFromSubject(Subject subject) Create a UserGroupInformation from a Subject with Kerberos principal.
static UserGroupInformation	getUGIFromTicketCache(String ticketCache, String user) Create a UserGroupInformation from a Kerberos ticket cache.
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 managed by the UGI?
static boolean	isInitialized()
static boolean	isLoginKeytabBased() Did the login happen via keytab
static boolean	isLoginTicketBased() Did the login happen via ticket cache
static boolean	isSecurityEnabled() Determine if UserGroupInformation is using Kerberos to determine user identities or is relying on simple authentication
static void	logAllUserInfo(UserGroupInformation ugi) Log all (current, real, login) UGI and token info into UGI debug log.
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	loginUserFromSubject(Subject subject) Log in a user using the given subject
void	logoutUserFromKeytab() Log the current user out who previously logged in using keytab.
static void	main(String[] args) A test method to print out the current user's UGI.
static void	reattachMetrics() Reattach the class's metrics to a new metric system.
void	reloginFromKeytab() Re-Login a user in from a keytab file.
void	reloginFromTicketCache() Re-Login a user in from the ticket cache.
void	setAuthenticationMethod(org.apache.hadoop.security.SaslRpcServer.AuthMethod authMethod) Sets the authentication method in the subject
void	setAuthenticationMethod(UserGroupInformation.AuthenticationMethod authMethod) Sets the authentication method in the subject
static void	setConfiguration(Configuration conf) Set the static configuration for UGI.
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).
String	toString() Return the username.
static String	trimLoginMethod(String userName) remove the login method that is followed by a space from the username e.g.

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

setShouldRenewImmediatelyForTests

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

@InterfaceAudience.Public
 @InterfaceStability.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

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

@InterfaceAudience.Public
 @InterfaceStability.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

getUGIFromTicketCache

@InterfaceAudience.Public
 @InterfaceStability.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

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.

Throws:

IOException

KerberosAuthException - if the kerberos login fails

getLoginUser

@InterfaceAudience.Public
 @InterfaceStability.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 -

Returns:

userName without login method

loginUserFromSubject

@InterfaceAudience.Public
 @InterfaceStability.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

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.

loginUserFromKeytab

@InterfaceAudience.Public
 @InterfaceStability.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

KerberosAuthException - if it's a kerberos login exception.

logoutUserFromKeytab

@InterfaceAudience.Public
 @InterfaceStability.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

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

KerberosAuthException - if it's a kerberos login exception.

reloginFromKeytab

@InterfaceAudience.Public
 @InterfaceStability.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

KerberosAuthException - on a failure

forceReloginFromKeytab

@InterfaceAudience.Public
 @InterfaceStability.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

KerberosAuthException - on a failure

reloginFromTicketCache

@InterfaceAudience.Public
 @InterfaceStability.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

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

Throws:

IOException - if the keytab file can't be read

isLoginKeytabBased

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public static boolean isLoginKeytabBased()
                                                                                          throws IOException

Did the login happen via keytab

Returns:

true or false

Throws:

IOException

isLoginTicketBased

public static boolean isLoginTicketBased()
                                  throws IOException

Did the login happen via ticket cache

Returns:

true or false

Throws:

IOException

createRemoteUser

@InterfaceAudience.Public
 @InterfaceStability.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

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public static UserGroupInformation createRemoteUser(String user,
                                                                                                            org.apache.hadoop.security.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

Returns:

the UserGroupInformation for the remote user.

createProxyUser

@InterfaceAudience.Public
 @InterfaceStability.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 -

realUser -

Returns:

proxyUser ugi

getRealUser

@InterfaceAudience.Public
 @InterfaceStability.Evolving
public UserGroupInformation getRealUser()

get RealUser (vs. EffectiveUser)

Returns:

realUser running over proxy user

createUserForTesting

@InterfaceAudience.Public
 @InterfaceStability.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

@InterfaceAudience.Public
 @InterfaceStability.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

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. getGroups() 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

public List<String> getGroups()

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 -

setAuthenticationMethod

public void setAuthenticationMethod(org.apache.hadoop.security.SaslRpcServer.AuthMethod 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.

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 -

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

@InterfaceAudience.Public
 @InterfaceStability.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

@InterfaceAudience.Public
 @InterfaceStability.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

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

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