hudson.security
Class SecurityRealm

java.lang.Object
  hudson.model.AbstractDescribableImpl<SecurityRealm>
      hudson.security.SecurityRealm

All Implemented Interfaces:

ExtensionPoint, Describable<SecurityRealm>

Direct Known Subclasses:

AbstractPasswordBasedSecurityRealm, LegacySecurityRealm, PAMSecurityRealm

public abstract class SecurityRealm
extends AbstractDescribableImpl<SecurityRealm>
implements ExtensionPoint

Pluggable security realm that connects external user database to Hudson.

< p/> If additional views/URLs need to be exposed, an active SecurityRealm is bound to CONTEXT_ROOT/securityRealm/ through Hudson.getSecurityRealm(), so you can define additional pages and operations on your SecurityRealm.

How do I implement this class?

For compatibility reasons, there are two somewhat different ways to implement a custom SecurityRealm.

< p/> One is to override the createSecurityComponents() and create key Spring Security components that control the authentication process. The default createFilter(FilterConfig) implementation then assembles them into a chain of Filters. All the incoming requests to Hudson go through this filter chain, and when the filter chain is done, SecurityContext.getAuthentication() would tell us who the current user is.

< p/> If your SecurityRealm needs to touch the default Filter chain configuration (e.g., adding new ones), then you can also override createFilter(FilterConfig) to do so.

< p/> This model is expected to fit most SecurityRealm implementations.

< p/> < p/> The other way of doing this is to ignore createSecurityComponents() completely (by returning SecurityRealm.SecurityComponents created by the default constructor) and just concentrate on createFilter(FilterConfig). As long as the resulting filter chain properly sets up Authentication object at the end of the processing, Hudson doesn't really need you to fit the standard Spring Security models like AuthenticationManager and UserDetailsService.

< p/> This model is for those "weird" implementations.

< p/>

Views

loginLink.jelly

This view renders the login link on the top right corner of every page, when the user is anonymous. For SecurityRealms that support user sign-up, this is a good place to show a "sign up" link. See HudsonPrivateSecurityRealm implementation for an example of this.

config.jelly

This view is used to render the configuration page in the system config screen.

Since:

1.160

Author:

Kohsuke Kawaguchi, Nikita Levyankov

See Also:

PluginServletFilter

Nested Class Summary

static class

SecurityRealm.SecurityComponents Just a tuple so that we can create various inter-related security related objects and return them all at once.

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

static org.springframework.security.GrantedAuthority	AUTHENTICATED_AUTHORITY GrantedAuthority that represents the built-in "authenticated" role, which is granted to anyone non-anonymous.
static DescriptorList<SecurityRealm>	LIST Deprecated. as of 1.286 Use all() for read access, and use Extension for registration.
static SecurityRealm	NO_AUTHENTICATION Singleton constant that represents "no authentication."

Constructor Summary

SecurityRealm()

Method Summary

static DescriptorExtensionList<SecurityRealm,Descriptor<SecurityRealm>>	all() Returns all the registered SecurityRealm descriptors.
boolean	allowsSignup() Returns true if this SecurityRealm allows online sign-up.
boolean	canLogOut() Returns true if this SecurityRealm supports explicit logout operation.
org.kohsuke.stapler.HttpResponse	commenceSignup(FederatedLoginService.FederatedIdentity identity) Starts the user registration process for a new user that has the given verified identity.
CliAuthenticator	createCliAuthenticator(CLICommand command) Creates a CliAuthenticator object that authenticates an invocation of a CLI command.
javax.servlet.Filter	createFilter(javax.servlet.FilterConfig filterConfig) Creates Filter that all the incoming HTTP requests will go through for authentication.
abstract SecurityRealm.SecurityComponents	createSecurityComponents() Creates fully-configured AuthenticationManager that performs authentication against the user realm.
void	doCaptcha(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Generates a captcha image.
void	doLogout(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Handles the logout processing.
String	getAuthenticationGatewayUrl() Returns the URL to submit a form for the authentication.
CaptchaSupport	getCaptchaSupport()
List<Descriptor<CaptchaSupport>>	getCaptchaSupportDescriptors()
javax.servlet.Filter[]	getCommonFilters()
Descriptor<SecurityRealm>	getDescriptor() Gets the descriptor for this instance.
String	getLoginUrl() Gets the target URL of the "login" link.
SecurityRealm.SecurityComponents	getSecurityComponents() Use this function to get the security components, without necessarily recreating them.
GroupDetails	loadGroupByGroupname(String groupname) If this SecurityRealm supports a look up of GroupDetails by their names, override this method to provide the look up.
org.springframework.security.userdetails.UserDetails	loadUserByUsername(String username) Shortcut for UserDetailsService.loadUserByUsername(String).
void	setCaptchaSupport(CaptchaSupport captchaSupport)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_AUTHENTICATION

public static final SecurityRealm NO_AUTHENTICATION

Singleton constant that represents "no authentication."

LIST

public static final DescriptorList<SecurityRealm> LIST

Deprecated. as of 1.286 Use all() for read access, and use Extension for registration.

All registered SecurityRealm implementations.

AUTHENTICATED_AUTHORITY

public static final org.springframework.security.GrantedAuthority AUTHENTICATED_AUTHORITY

GrantedAuthority that represents the built-in "authenticated" role, which is granted to anyone non-anonymous.

Constructor Detail

SecurityRealm

public SecurityRealm()

Method Detail

createSecurityComponents

public abstract SecurityRealm.SecurityComponents createSecurityComponents()

Creates fully-configured AuthenticationManager that performs authentication against the user realm. The implementation hides how such authentication manager is configured.

< p/> AuthenticationManager instantiation often depends on the user-specified parameters (for example, if the authentication is based on LDAP, the user needs to specify the host name of the LDAP server.) Such configuration is expected to be presented to the user via config.jelly and then captured as instance variables inside the SecurityRealm implementation.

< p/> Your SecurityRealm may also wants to alter Filter set up by overriding createFilter(FilterConfig).

createCliAuthenticator

public CliAuthenticator createCliAuthenticator(CLICommand command)

Creates a CliAuthenticator object that authenticates an invocation of a CLI command. See CliAuthenticator for more details.

Parameters:

command - The command about to be executed.

Returns:

never null. By default, this method returns a no-op authenticator that always authenticates the session as authenticated by the transport (which is often just Hudson.ANONYMOUS.)

getDescriptor

public Descriptor<SecurityRealm> getDescriptor()

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass()==b.getClass() then a.getDescriptor()==b.getDescriptor() must hold.

< p/> SecurityRealm is a singleton resource in Hudson, and therefore it's always configured through config.jelly and never with global.jelly.

Specified by:

getDescriptor in interface Describable<SecurityRealm>

Overrides:

getDescriptor in class AbstractDescribableImpl<SecurityRealm>

getAuthenticationGatewayUrl

public String getAuthenticationGatewayUrl()

Returns the URL to submit a form for the authentication. There's no need to override this, except for LegacySecurityRealm.

getLoginUrl

public String getLoginUrl()

Gets the target URL of the "login" link. There's no need to override this, except for LegacySecurityRealm. On legacy implementation this should point to loginEntry, which is protected by web.xml, so that the user can be eventually authenticated by the container.

< p/> Path is relative from the context root of the Hudson application. The URL returned by this method will get the "from" query parameter indicating the page that the user was at.

canLogOut

public boolean canLogOut()

Returns true if this SecurityRealm supports explicit logout operation.

< p/> If the method returns false, "logout" link will not be displayed. This is useful when authentication doesn't require an explicit login activity (such as NTLM authentication or Kerberos authentication, where Hudson has no ability to log off the current user.)

< p/> By default, this method returns true.

Since:

1.307

getCaptchaSupport

public CaptchaSupport getCaptchaSupport()

setCaptchaSupport

public void setCaptchaSupport(CaptchaSupport captchaSupport)

getCaptchaSupportDescriptors

public List<Descriptor<CaptchaSupport>> getCaptchaSupportDescriptors()

doLogout

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

Handles the logout processing.

< p/> The default implementation erases the session and do a few other clean up, then redirect the user to the URL specified by getPostLogOutUrl(StaplerRequest, Authentication).

Throws:

IOException

javax.servlet.ServletException

Since:

1.314

allowsSignup

public boolean allowsSignup()

Returns true if this SecurityRealm allows online sign-up. This creates a hyperlink that redirects users to CONTEXT_ROOT/signUp, which will be served by the signup.jelly view of this class.

< p/> If the implementation needs to redirect the user to a different URL for signing up, use the following jelly script as signup.jelly

< pre>

<st:redirect url="http://www.sun.com/" xmlns:st="jelly:stapler"/>

loadUserByUsername

public org.springframework.security.userdetails.UserDetails loadUserByUsername(String username)
                                                                        throws org.springframework.security.userdetails.UsernameNotFoundException,
                                                                               org.springframework.dao.DataAccessException

Shortcut for UserDetailsService.loadUserByUsername(String).

Returns:

never null.

Throws:

UserMayOrMayNotExistException - If the security realm cannot even tell if the user exists or not.

org.springframework.security.userdetails.UsernameNotFoundException

org.springframework.dao.DataAccessException

loadGroupByGroupname

public GroupDetails loadGroupByGroupname(String groupname)
                                  throws org.springframework.security.userdetails.UsernameNotFoundException,
                                         org.springframework.dao.DataAccessException

If this SecurityRealm supports a look up of GroupDetails by their names, override this method to provide the look up.

< p/> This information, when available, can be used by AuthorizationStrategys to improve the UI and error diagnostics for the user.

Throws:

org.springframework.security.userdetails.UsernameNotFoundException

org.springframework.dao.DataAccessException

commenceSignup

public org.kohsuke.stapler.HttpResponse commenceSignup(FederatedLoginService.FederatedIdentity identity)

Starts the user registration process for a new user that has the given verified identity.

< p/> If the user logs in through a FederatedLoginService, verified that the current user owns an identity, but no existing user account has claimed that identity, then this method is invoked.

< p/> The expected behaviour is to confirm that the user would like to create a new account, and associate this federated identity to the newly created account (via FederatedLoginService.FederatedIdentity.addToCurrentUser().

Throws:

UnsupportedOperationException - If this implementation doesn't support the signup through this mechanism. This is the default implementation.

Since:

1.394

doCaptcha

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

Generates a captcha image.

Throws:

IOException

getSecurityComponents

public SecurityRealm.SecurityComponents getSecurityComponents()

Use this function to get the security components, without necessarily recreating them.

createFilter

public javax.servlet.Filter createFilter(javax.servlet.FilterConfig filterConfig)
                                  throws javax.servlet.ServletException

Creates Filter that all the incoming HTTP requests will go through for authentication.

< p/> The default implementation uses getSecurityComponents() and builds a standard filter But subclasses can override this to completely change the filter sequence.

< p/> For other plugins that want to contribute Filter, see PluginServletFilter.

Throws:

javax.servlet.ServletException

Since:

1.271

getCommonFilters

public javax.servlet.Filter[] getCommonFilters()

all

public static DescriptorExtensionList<SecurityRealm,Descriptor<SecurityRealm>> all()

Returns all the registered SecurityRealm descriptors.