hudson.model

Class User

java.lang.Object

hudson.model.AbstractModelObject

hudson.model.User

All Implemented Interfaces:

DescriptorByNameOwner, ModelObject, Saveable, SearchableModelObject, SearchItem, AccessControlled, Comparable<User>, ModelObjectWithContextMenu, org.kohsuke.stapler.StaplerProxy

@ExportedBean
public class User
extends AbstractModelObject
implements AccessControlled, DescriptorByNameOwner, Saveable, Comparable<User>, ModelObjectWithContextMenu, org.kohsuke.stapler.StaplerProxy

Represents a user.

In Hudson, User objects are created in on-demand basis; for example, when a build is performed, its change log is computed and as a result commits from users who Hudson has never seen may be discovered. When this happens, new User object is created.

If the persisted record for an user exists, the information is loaded at that point, but if there's no such record, a fresh instance is created from thin air (this is where UserPropertyDescriptor.newInstance(User) is called to provide initial UserProperty objects.

Such newly created User objects will be simply GC-ed without ever leaving the persisted record, unless save() method is explicitly invoked (perhaps as a result of a browser submitting a configuration.)

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	User.AllUsers Per-Jenkins holder of all known Users.
static class	User.CanonicalIdResolver Resolves User IDs by ID, full names or other strings.
static class	User.FullNameIdResolver Resolve user ID from full name
static class	User.UserIDCanonicalIdResolver Tries to verify if an ID is valid.

Nested classes/interfaces inherited from interface jenkins.model.ModelObjectWithContextMenu

ModelObjectWithContextMenu.ContextMenu, ModelObjectWithContextMenu.ContextMenuVisibility, ModelObjectWithContextMenu.MenuItem

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	ALLOW_NON_EXISTENT_USER_TO_LOGIN Jenkins now refuses to let the user login if he/she doesn't exist in SecurityRealm, which was necessary to make sure users removed from the backend will get removed from the frontend.
static boolean	ALLOW_USER_CREATION_VIA_URL Jenkins historically created a (usually) ephemeral user record when an user with Overall/Administer permission accesses a /user/arbitraryName URL.
static boolean	SKIP_PERMISSION_CHECK Escape hatch for StaplerProxy-based access control
static XStream2	XSTREAM

Fields inherited from interface hudson.model.Saveable

NOOP

Method Summary

Modifier and Type	Method and Description
void	addProperty(UserProperty p) Updates the user object by adding a property.
boolean	canDelete() With ADMINISTER permission, can delete users with persisted data but can't delete self.
static void	clear() Deprecated.
int	compareTo(User that)
static User	current() Gets the User object representing the currently logged-in user, or null if the current user is anonymous.
void	delete() Deletes the data directory and removes this user from Hudson.
void	doConfigSubmit(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts submission from the configuration page.
ModelObjectWithContextMenu.ContextMenu	doContextMenu(org.kohsuke.stapler.StaplerRequest request, org.kohsuke.stapler.StaplerResponse response) Generates the context menu.
void	doDoDelete(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Deletes this user from Hudson.
void	doRssAll(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
void	doRssFailed(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
void	doRssLatest(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp)
void	doSubmitDescription(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Accepts the new description.
static User	get(Authentication a) Deprecated. use get2(Authentication)
static User	get(String idOrFullName) Deprecated. This method is deprecated, because it causes unexpected User creation by API usage code and causes performance degradation of used to retrieve users by ID. Use getById(java.lang.String, boolean) when you know you have an ID. Otherwise use getOrCreateByIdOrFullName(String) or get(String, boolean, Map).
static User	get(String idOrFullName, boolean create) Deprecated. use get(String, boolean, java.util.Map)
static User	get(String idOrFullName, boolean create, Map context) Gets the User object by its id or full name.
static User	get2(org.springframework.security.core.Authentication a) Gets the User object representing the supplied Authentication or null if the supplied Authentication is either anonymous or null
String	getAbsoluteUrl() The URL of the user page.
ACL	getACL() Obtains the ACL associated with this object.
static Collection<User>	getAll() Gets all the users.
List<UserProperty>	getAllProperties() List of all UserPropertys exposed primarily for the remoting API.
Api	getApi() Exposed remote API.
List<String>	getAuthorities() Checks for authorities (groups) associated with this user.
RunList	getBuilds() Gets the list of Builds that include changes by this user, by the timestamp order.
static User	getById(String id, boolean create) Gets the User object by its id
String	getDescription()
String	getDisplayName() Returns the user name.
Object	getDynamic(String token)
String	getFullName() Gets the human readable name of this user.
String	getId()
static User	getOrCreateByIdOrFullName(String idOrFullName) Get the user by ID or Full Name.
Set<AbstractProject<?,?>>	getProjects() Gets all the AbstractProjects that this user has committed to.
Map<Descriptor<UserProperty>,UserProperty>	getProperties() Gets the user properties configured for this user.
<T extends UserProperty> T	getProperty(Class<T> clazz) Gets the specific property, or null.
List<Action>	getPropertyActions() Return all properties that are also actions.
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
Object	getTarget()
List<Action>	getTransientActions() Return all transient actions associated with this user.
static User	getUnknown() Gets the fallback "unknown" user instance.
String	getUrl()
UserDetails	getUserDetailsForImpersonation() Deprecated. use getUserDetailsForImpersonation2()
org.springframework.security.core.userdetails.UserDetails	getUserDetailsForImpersonation2() This method checks with SecurityRealm if the user is a valid user that can login to the security realm.
File	getUserFolder() Returns the folder that store all the user information.
static IdStrategy	idStrategy() Returns the IdStrategy for use with User instances.
Authentication	impersonate() Deprecated. use impersonate2()
org.springframework.security.core.Authentication	impersonate(org.springframework.security.core.userdetails.UserDetails userDetails) Creates an Authentication object that represents this user using the given userDetails
org.springframework.security.core.Authentication	impersonate2() Creates an Authentication object that represents this user.
static boolean	isIdOrFullnameAllowed(String id) Is the ID allowed? Some are prohibited for security reasons.
static void	rekey() Called when changing the IdStrategy.
static void	reload() To be called from Jenkins.reload() only.
void	save() Save the user configuration.
void	setDescription(String description) Sets the description of the user.
void	setFullName(String name) Sets the human readable name of the user.
String	toString()

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface hudson.security.AccessControlled

checkAnyPermission, checkPermission, hasAnyPermission, hasPermission, hasPermission, hasPermission2

Methods inherited from interface hudson.model.DescriptorByNameOwner

getDescriptorByName

Field Detail

XSTREAM

public static final XStream2 XSTREAM

SKIP_PERMISSION_CHECK

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean SKIP_PERMISSION_CHECK

Escape hatch for StaplerProxy-based access control

ALLOW_NON_EXISTENT_USER_TO_LOGIN

public static boolean ALLOW_NON_EXISTENT_USER_TO_LOGIN

Jenkins now refuses to let the user login if he/she doesn't exist in SecurityRealm, which was necessary to make sure users removed from the backend will get removed from the frontend.

Unfortunately this infringed some legitimate use cases of creating Jenkins-local users for automation purposes. This escape hatch switch can be enabled to resurrect that behaviour.

See Also:

JENKINS-22346.

ALLOW_USER_CREATION_VIA_URL

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean ALLOW_USER_CREATION_VIA_URL

Jenkins historically created a (usually) ephemeral user record when an user with Overall/Administer permission accesses a /user/arbitraryName URL.

Unfortunately this constitutes a CSRF vulnerability, as malicious users can make admins create arbitrary numbers of ephemeral user records, so the behavior was changed in Jenkins 2.TODO / 2.32.2.

As some users may be relying on the previous behavior, setting this to true restores the previous behavior. This is not recommended.

SECURITY-406.

Method Detail

idStrategy

@NonNull
public static IdStrategy idStrategy()

Returns the IdStrategy for use with User instances. See SecurityRealm.getUserIdStrategy()

Returns:

the IdStrategy for use with User instances.

Since:

1.566

compareTo

public int compareTo(@NonNull
                     User that)

Specified by:

compareTo in interface Comparable<User>

getId

@Exported
public String getId()

getUrl

@NonNull
public String getUrl()

getSearchUrl

@NonNull
public String getSearchUrl()

Description copied from interface: SearchItem

Returns the URL of this item relative to the parent SearchItem.

Specified by:

getSearchUrl in interface SearchItem

Returns:

URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Jenkins.)

getAbsoluteUrl

@Exported(visibility=999)
 @NonNull
public String getAbsoluteUrl()

The URL of the user page.

getFullName

@Exported(visibility=999)
 @NonNull
public String getFullName()

Gets the human readable name of this user. This is configurable by the user.

setFullName

public void setFullName(String name)

Sets the human readable name of the user. If the input parameter is empty, the user's ID will be set.

getDescription

@Exported
 @CheckForNull
public String getDescription()

setDescription

public void setDescription(String description)

Sets the description of the user.

Since:

1.609

getProperties

public Map<Descriptor<UserProperty>,UserProperty> getProperties()

Gets the user properties configured for this user.

addProperty

public void addProperty(@NonNull
                        UserProperty p)
                 throws IOException

Updates the user object by adding a property.

Throws:

IOException

getAllProperties

@Exported(name="property",
          inline=true)
public List<UserProperty> getAllProperties()

List of all UserPropertys exposed primarily for the remoting API.

getProperty

public <T extends UserProperty> T getProperty(Class<T> clazz)

Gets the specific property, or null.

impersonate2

@NonNull
public org.springframework.security.core.Authentication impersonate2()
                                                                       throws org.springframework.security.core.userdetails.UsernameNotFoundException

Creates an Authentication object that represents this user.

This method checks with SecurityRealm if the user is a valid user that can login to the security realm. If SecurityRealm is a kind that does not support querying information about other users, this will use LastGrantedAuthoritiesProperty to pick up the granted authorities as of the last time the user has logged in.

Throws:

org.springframework.security.core.userdetails.UsernameNotFoundException - If this user is not a valid user in the backend SecurityRealm.

Since:

TODO

impersonate

@Deprecated
 @NonNull
public Authentication impersonate()
                                                 throws UsernameNotFoundException

Deprecated. use impersonate2()

Throws:

UsernameNotFoundException

Since:

1.419

getUserDetailsForImpersonation2

@NonNull
public org.springframework.security.core.userdetails.UserDetails getUserDetailsForImpersonation2()
                                                                                                   throws org.springframework.security.core.userdetails.UsernameNotFoundException

This method checks with SecurityRealm if the user is a valid user that can login to the security realm. If SecurityRealm is a kind that does not support querying information about other users, this will use LastGrantedAuthoritiesProperty to pick up the granted authorities as of the last time the user has logged in.

Returns:

userDetails for the user, in case he's not found but seems legitimate, we provide a userDetails with minimum access

Throws:

org.springframework.security.core.userdetails.UsernameNotFoundException - If this user is not a valid user in the backend SecurityRealm.

Since:

TODO

getUserDetailsForImpersonation

@Deprecated
 @NonNull
public UserDetails getUserDetailsForImpersonation()
                                                                 throws UsernameNotFoundException

Deprecated. use getUserDetailsForImpersonation2()

Throws:

UsernameNotFoundException

impersonate

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
 @NonNull
public org.springframework.security.core.Authentication impersonate(@NonNull
                                                                                                                                                     org.springframework.security.core.userdetails.UserDetails userDetails)

Creates an Authentication object that represents this user using the given userDetails

Parameters:

userDetails - Provided by getUserDetailsForImpersonation2().

See Also:

getUserDetailsForImpersonation2()

doSubmitDescription

public void doSubmitDescription(org.kohsuke.stapler.StaplerRequest req,
                                org.kohsuke.stapler.StaplerResponse rsp)
                         throws IOException

Accepts the new description.

Throws:

IOException

getUnknown

@NonNull
public static User getUnknown()

Gets the fallback "unknown" user instance.

This is used to avoid null User instance.

get

@Deprecated
 @Nullable
public static User get(String idOrFullName,
                                              boolean create)

Deprecated. use get(String, boolean, java.util.Map)

Gets the User object by its id or full name.

Parameters:

create - If true, this method will never return null for valid input (by creating a new User object if none exists.) If false, this method will return null if User object with the given name doesn't exist.

Returns:

Requested user. May be null if a user does not exist and create is false.

get

@Nullable
public static User get(String idOrFullName,
                                 boolean create,
                                 @NonNull
                                 Map context)

Gets the User object by its id or full name.

In order to resolve the user ID, the method invokes User.CanonicalIdResolver extension points. Note that it may cause significant performance degradation. If you are sure the passed value is a User ID, it is recommended to use getById(String, boolean).

Parameters:

create - If true, this method will never return null for valid input (by creating a new User object if none exists.) If false, this method will return null if User object with the given name doesn't exist.

context - contextual environment this user idOfFullName was retrieved from, that can help resolve the user ID

Returns:

An existing or created user. May be null if a user does not exist and create is false.

get

@Deprecated
 @NonNull
public static User get(String idOrFullName)

Deprecated. This method is deprecated, because it causes unexpected User creation by API usage code and causes performance degradation of used to retrieve users by ID. Use getById(java.lang.String, boolean) when you know you have an ID. Otherwise use getOrCreateByIdOrFullName(String) or get(String, boolean, Map).

Gets the User object by its id or full name.

Creates a user on-demand.

Use getById(java.lang.String, boolean) when you know you have an ID. In this method Jenkins will try to resolve the User by full name with help of various UserNameResolver. This is slow (see JENKINS-23281).

getOrCreateByIdOrFullName

@NonNull
public static User getOrCreateByIdOrFullName(@NonNull
                                                      String idOrFullName)

Get the user by ID or Full Name.

If the user does not exist, creates a new one on-demand.

Use getById(java.lang.String, boolean) when you know you have an ID. In this method Jenkins will try to resolve the User by full name with help of various UserNameResolver. This is slow (see JENKINS-23281).

Parameters:

idOrFullName - User ID or full name

Returns:

User instance. It will be created on-demand.

Since:

2.91

current

@CheckForNull
public static User current()

Gets the User object representing the currently logged-in user, or null if the current user is anonymous.

Since:

1.172

get2

@CheckForNull
public static User get2(@CheckForNull
                                      org.springframework.security.core.Authentication a)

Gets the User object representing the supplied Authentication or null if the supplied Authentication is either anonymous or null

Parameters:

a - the supplied Authentication .

Returns:

a User object for the supplied Authentication or null

Since:

TODO

get

@Deprecated
 @CheckForNull
public static User get(@CheckForNull
                                                  Authentication a)

Deprecated. use get2(Authentication)

Since:

1.609

getById

@Nullable
public static User getById(String id,
                                     boolean create)

Gets the User object by its id

Parameters:

id - the id of the user to retrieve and optionally create if it does not exist.

create - If true, this method will never return null for valid input (by creating a new User object if none exists.) If false, this method will return null if User object with the given id doesn't exist.

Returns:

the a User whose id is id, or null if create is false and the user does not exist.

Since:

1.651.2 / 2.3

getAll

@NonNull
public static Collection<User> getAll()

Gets all the users.

reload

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static void reload()
                                                                                          throws IOException

To be called from Jenkins.reload() only.

Throws:

IOException

rekey

public static void rekey()

Called when changing the IdStrategy.

Since:

1.566

getDisplayName

@NonNull
public String getDisplayName()

Returns the user name.

Specified by:

getDisplayName in interface ModelObject

getBuilds

@WithBridgeMethods(value=java.util.List.class)
 @NonNull
public RunList getBuilds()

Gets the list of Builds that include changes by this user, by the timestamp order.

getProjects

@NonNull
public Set<AbstractProject<?,?>> getProjects()

Gets all the AbstractProjects that this user has committed to.

Since:

1.191

toString

public String toString()

Overrides:

toString in class Object

clear

@Deprecated
public static void clear()

Deprecated.

Called by tests in the JTH. Otherwise this shouldn't be called. Even in the tests this usage is questionable.

getUserFolder

@CheckForNull
public File getUserFolder()

Returns the folder that store all the user information. Useful for plugins to save a user-specific file aside the config.xml. Exposes implementation details that may be subject to change.

Returns:

The folder containing the user configuration files or null if the user was not yet saved.

Since:

2.129

isIdOrFullnameAllowed

public static boolean isIdOrFullnameAllowed(@CheckForNull
                                            String id)

Is the ID allowed? Some are prohibited for security reasons. See SECURITY-166.

Note that this is only enforced when saving. These users are often created via the constructor (and even listed on /asynchPeople), but our goal is to prevent anyone from logging in as these users. Therefore, we prevent saving a User with one of these ids.

Parameters:

id - ID to be checked

Returns:

true if the username or fullname is valid. For null or blank IDs returns false.

Since:

1.600

save

public void save()
          throws IOException

Save the user configuration.

Specified by:

save in interface Saveable

Throws:

IOException - if the persistence failed.

delete

public void delete()
            throws IOException

Deletes the data directory and removes this user from Hudson.

Throws:

IOException - if we fail to delete.

getApi

public Api getApi()

Exposed remote API.

doConfigSubmit

@POST
public void doConfigSubmit(org.kohsuke.stapler.StaplerRequest req,
                                 org.kohsuke.stapler.StaplerResponse rsp)
                          throws IOException,
                                 javax.servlet.ServletException,
                                 Descriptor.FormException

Accepts submission from the configuration page.

Throws:

IOException

javax.servlet.ServletException

Descriptor.FormException

doDoDelete

public void doDoDelete(org.kohsuke.stapler.StaplerRequest req,
                       org.kohsuke.stapler.StaplerResponse rsp)
                throws IOException

Deletes this user from Hudson.

Throws:

IOException

doRssAll

public void doRssAll(org.kohsuke.stapler.StaplerRequest req,
                     org.kohsuke.stapler.StaplerResponse rsp)
              throws IOException,
                     javax.servlet.ServletException

Throws:

IOException

javax.servlet.ServletException

doRssFailed

public void doRssFailed(org.kohsuke.stapler.StaplerRequest req,
                        org.kohsuke.stapler.StaplerResponse rsp)
                 throws IOException,
                        javax.servlet.ServletException

Throws:

IOException

javax.servlet.ServletException

doRssLatest

public void doRssLatest(org.kohsuke.stapler.StaplerRequest req,
                        org.kohsuke.stapler.StaplerResponse rsp)
                 throws IOException,
                        javax.servlet.ServletException

Throws:

IOException

javax.servlet.ServletException

getACL

@NonNull
public ACL getACL()

Description copied from interface: AccessControlled

Obtains the ACL associated with this object.

Specified by:

getACL in interface AccessControlled

Returns:

never null.

canDelete

public boolean canDelete()

With ADMINISTER permission, can delete users with persisted data but can't delete self.

getAuthorities

@NonNull
public List<String> getAuthorities()

Checks for authorities (groups) associated with this user. If the caller lacks Jenkins.ADMINISTER, or any problems arise, returns an empty list. SecurityRealm.AUTHENTICATED_AUTHORITY2 and the username, if present, are omitted.

Returns:

a possibly empty list

Since:

1.498

getDynamic

public Object getDynamic(String token)

getPropertyActions

public List<Action> getPropertyActions()

Return all properties that are also actions.

Returns:

the list can be empty but never null. read only.

getTransientActions

public List<Action> getTransientActions()

Return all transient actions associated with this user.

Returns:

the list can be empty but never null. read only.

doContextMenu

public ModelObjectWithContextMenu.ContextMenu doContextMenu(org.kohsuke.stapler.StaplerRequest request,
                                                            org.kohsuke.stapler.StaplerResponse response)
                                                     throws Exception

Description copied from interface: ModelObjectWithContextMenu

Generates the context menu. The typical implementation is return new ContextMenu().from(this,request,response);, which implements the default behaviour. See ModelObjectWithContextMenu.ContextMenu.from(ModelObjectWithContextMenu, StaplerRequest, StaplerResponse) for more details of what it does. This should suit most implementations.

Specified by:

doContextMenu in interface ModelObjectWithContextMenu

Throws:

Exception

getTarget

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Object getTarget()

Specified by:

getTarget in interface org.kohsuke.stapler.StaplerProxy