public abstract class SecurityRealm extends AbstractDescribableImpl<SecurityRealm> implements ExtensionPoint
If additional views/URLs need to be exposed,
an active SecurityRealm
is bound to CONTEXT_ROOT/securityRealm/
through Jenkins.getSecurityRealm()
, so you can define additional pages and
operations on your SecurityRealm
.
For compatibility reasons, there are two somewhat different ways to implement a custom SecurityRealm.
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 Filter
s. 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.
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.
This model is expected to fit most SecurityRealm
implementations.
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,
Jenkins doesn't really need you to fit the standard Spring Security models like AuthenticationManager
and
UserDetailsService
.
This model is for those "weird" implementations.
SecurityRealm
s that support user sign-up, this is a good place
to show a "sign up" link. See HudsonPrivateSecurityRealm
implementation
for an example of this.
PluginServletFilter
Modifier and Type | Class and Description |
---|---|
static class |
SecurityRealm.SecurityComponents
Just a tuple so that we can create various inter-related security related objects and
return them all at once.
|
ExtensionPoint.LegacyInstancesAreScopedToHudson
Modifier and Type | Field and Description |
---|---|
static GrantedAuthority |
AUTHENTICATED_AUTHORITY
Deprecated.
|
static org.springframework.security.core.GrantedAuthority |
AUTHENTICATED_AUTHORITY2
GrantedAuthority that represents the built-in "authenticated" role, which is granted to
anyone non-anonymous. |
static DescriptorList<SecurityRealm> |
LIST
|
static SecurityRealm |
NO_AUTHENTICATION
Singleton constant that represents "no authentication."
|
Constructor and Description |
---|
SecurityRealm() |
Modifier and Type | Method and Description |
---|---|
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.
|
protected List<javax.servlet.Filter> |
commonFilters() |
CliAuthenticator |
createCliAuthenticator(CLICommand command)
Deprecated.
No longer used.
|
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() |
Descriptor<SecurityRealm> |
getDescriptor()
By default looks for a nested class (conventionally named
DescriptorImpl ) implementing Descriptor and marked with Extension . |
static String |
getFrom()
Perform a calculation where we should go back after successful login
|
IdStrategy |
getGroupIdStrategy()
Returns the
IdStrategy that should be used for turning GroupDetails.getName()
into an ID. |
String |
getLoginUrl()
Gets the target URL of the "login" link.
|
protected String |
getPostLogOutUrl(org.kohsuke.stapler.StaplerRequest req,
Authentication auth)
|
protected String |
getPostLogOutUrl2(org.kohsuke.stapler.StaplerRequest req,
org.springframework.security.core.Authentication auth)
Controls where the user is sent to after a logout.
|
SecurityRealm.SecurityComponents |
getSecurityComponents()
Use this function to get the security components, without necessarily
recreating them.
|
IdStrategy |
getUserIdStrategy()
Returns the
IdStrategy that should be used for turning
UserDetails.getUsername() into an ID. |
GroupDetails |
loadGroupByGroupname(String groupname)
Deprecated.
|
GroupDetails |
loadGroupByGroupname(String groupname,
boolean fetchMembers)
Deprecated.
|
GroupDetails |
loadGroupByGroupname2(String groupname,
boolean fetchMembers)
If this
SecurityRealm supports a look up of GroupDetails by their names, override this method
to provide the look up. |
UserDetails |
loadUserByUsername(String username)
Deprecated.
|
org.springframework.security.core.userdetails.UserDetails |
loadUserByUsername2(String username)
Shortcut for
UserDetailsService.loadUserByUsername(String) . |
void |
setCaptchaSupport(CaptchaSupport captchaSupport) |
protected boolean |
validateCaptcha(String text)
Validates the captcha.
|
public static final SecurityRealm NO_AUTHENTICATION
@Deprecated public static final DescriptorList<SecurityRealm> LIST
SecurityRealm
implementations.public static final org.springframework.security.core.GrantedAuthority AUTHENTICATED_AUTHORITY2
GrantedAuthority
that represents the built-in "authenticated" role, which is granted to
anyone non-anonymous.@Deprecated public static final GrantedAuthority AUTHENTICATED_AUTHORITY
AUTHENTICATED_AUTHORITY2
public abstract SecurityRealm.SecurityComponents createSecurityComponents()
AuthenticationManager
that performs authentication
against the user realm. The implementation hides how such authentication manager
is configured.
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.
Your SecurityRealm
may also wants to alter Filter
set up by
overriding createFilter(FilterConfig)
.
public IdStrategy getUserIdStrategy()
IdStrategy
that should be used for turning
UserDetails.getUsername()
into an ID.
Mostly this should be IdStrategy.CaseInsensitive
but there may be occasions when either
IdStrategy.CaseSensitive
or IdStrategy.CaseSensitiveEmailAddress
are the correct approach.IdStrategy
that should be used for turning
UserDetails.getUsername()
into an ID.public IdStrategy getGroupIdStrategy()
IdStrategy
that should be used for turning GroupDetails.getName()
into an ID.
Note: Mostly this should be the same as getUserIdStrategy()
but some security realms may have legitimate
reasons for a different strategy.IdStrategy
that should be used for turning GroupDetails.getName()
into an ID.@Deprecated public CliAuthenticator createCliAuthenticator(CLICommand command)
public Descriptor<SecurityRealm> getDescriptor()
DescriptorImpl
) implementing Descriptor
and marked with Extension
.
Gets the descriptor for this instance.
Descriptor
is a singleton for every concrete Describable
implementation, so if a.getClass() == b.getClass()
then by default
a.getDescriptor() == b.getDescriptor()
as well.
(In rare cases a single implementation class may be used for instances with distinct descriptors.)
SecurityRealm
is a singleton resource in Hudson, and therefore
it's always configured through config.jelly
and never with
global.jelly
.
getDescriptor
in interface Describable<SecurityRealm>
getDescriptor
in class AbstractDescribableImpl<SecurityRealm>
public String getAuthenticationGatewayUrl()
LegacySecurityRealm
.AuthenticationProcessingFilter2
public String getLoginUrl()
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.
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.
public boolean canLogOut()
SecurityRealm
supports explicit logout operation.
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.)
By default, this method returns true.
protected String getPostLogOutUrl2(org.kohsuke.stapler.StaplerRequest req, org.springframework.security.core.Authentication auth)
req
- StaplerRequest
that represents the current request. Primarily so that
you can get the context path. By the time this method is called, the session
is already invalidated. Never null.auth
- The Authentication
object that represents the user that was logging in.
This parameter allows you to redirect people to different pages depending on who they are.doLogout(StaplerRequest, StaplerResponse)
@Deprecated protected String getPostLogOutUrl(org.kohsuke.stapler.StaplerRequest req, Authentication auth)
getPostLogOutUrl2(org.kohsuke.stapler.StaplerRequest, org.springframework.security.core.Authentication)
public CaptchaSupport getCaptchaSupport()
public void setCaptchaSupport(CaptchaSupport captchaSupport)
public List<Descriptor<CaptchaSupport>> getCaptchaSupportDescriptors()
public void doLogout(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException, javax.servlet.ServletException
The default implementation erases the session and do a few other clean up, then
redirect the user to the URL specified by getPostLogOutUrl2(StaplerRequest, Authentication)
.
IOException
javax.servlet.ServletException
public boolean allowsSignup()
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.
If the implementation needs to redirect the user to a different URL
for signing up, use the following jelly script as signup.jelly
<xmp>
<st:redirect url="http://www.sun.com/" xmlns:st="jelly:stapler"/>
</xmp>
public org.springframework.security.core.userdetails.UserDetails loadUserByUsername2(String username) throws org.springframework.security.core.userdetails.UsernameNotFoundException
UserDetailsService.loadUserByUsername(String)
.UserMayOrMayNotExistException2
- If the security realm cannot even tell if the user exists or not.org.springframework.security.core.userdetails.UsernameNotFoundException
@Deprecated public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException
loadUserByUsername2(java.lang.String)
public GroupDetails loadGroupByGroupname2(String groupname, boolean fetchMembers) throws org.springframework.security.core.userdetails.UsernameNotFoundException
SecurityRealm
supports a look up of GroupDetails
by their names, override this method
to provide the look up.
This information, when available, can be used by AuthorizationStrategy
s to improve the UI and
error diagnostics for the user.
groupname
- the name of the group to fetchfetchMembers
- if true
then try and fetch the members of the group if it exists. Trying does not
imply that the members will be fetched and GroupDetails.getMembers()
may still return null
UserMayOrMayNotExistException2
- if no conclusive result could be determined regarding the group existence.org.springframework.security.core.userdetails.UsernameNotFoundException
- if the group does not exist.@Deprecated public GroupDetails loadGroupByGroupname(String groupname) throws UsernameNotFoundException, DataAccessException
loadGroupByGroupname2(java.lang.String, boolean)
@Deprecated public GroupDetails loadGroupByGroupname(String groupname, boolean fetchMembers) throws UsernameNotFoundException, DataAccessException
loadGroupByGroupname2(java.lang.String, boolean)
UsernameNotFoundException
DataAccessException
public org.kohsuke.stapler.HttpResponse commenceSignup(FederatedLoginService.FederatedIdentity identity)
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.
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()
.
UnsupportedOperationException
- If this implementation doesn't support the signup through this mechanism.
This is the default implementation.public final void doCaptcha(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) throws IOException
IOException
protected final boolean validateCaptcha(String text)
public SecurityRealm.SecurityComponents getSecurityComponents()
public javax.servlet.Filter createFilter(javax.servlet.FilterConfig filterConfig)
Filter
that all the incoming HTTP requests will go through
for authentication.
The default implementation uses getSecurityComponents()
and builds
a standard filter chain.
But subclasses can override this to completely change the filter sequence.
For other plugins that want to contribute Filter
, see
PluginServletFilter
.
protected final List<javax.servlet.Filter> commonFilters()
@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class) public static String getFrom()
public static DescriptorExtensionList<SecurityRealm,Descriptor<SecurityRealm>> all()
SecurityRealm
descriptors.Copyright © 2004–2021. All rights reserved.