hudson.security
Class SecurityRealm

java.lang.Object
  extended by hudson.model.AbstractDescribableImpl<SecurityRealm>
      extended by 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.



Copyright © 2004-2013 Hudson. All Rights Reserved.