jespa.http

Class HttpSecurityService

java.lang.Object

jespa.http.HttpSecurityService

Direct Known Subclasses:

DuoHttpSecurityService, HttpSecurityFilter

public class HttpSecurityService
extends java.lang.Object

This class implements a variety of HTTP security features including authentication and authorization using a SecurityProvider. Any SecurityProvider that supports authentication can be used with the HttpSecurityService including the Jespa NtlmSecurityProvider and LdapSecurityProvider.

IMPORTANT: If you are using the NtlmSecurityProvider, this class will not work until you create a Computer account as described in the Installation section in the Jespa Operator's Manual.

IMPORTANT: You must route requests through the HttpSecurityService doFilter method. Do not try to use it as a parallel service. Some developers have incorrectly tried to call doFilter in a transient, on-demand convention, allowing control to return to the caller before executing the primary function of the request. Trying to do this will almost certainly result in unexpected behavior. The HttpSecurityService handles concurrent authentication states, proactive POST re-authentication, suppressing redundant authentications and several other tricky details.

IMPORTANT: Browsers can proactively initiate authentication for POST requests. This means that you should not try to selectively call doFilter. Aside from perhaps some GET requests for non-sensitive static content like CSS, you should route all HTTP requests through this class very early in the call stack.

Note: Even though the method signatures match that of the Filter interface, this class does not implement the Filter interface. The init method accepts a simple Map of properties. This allows developers to create custom HTTP security solutions that do not implement the Filter interface but can easily do so if desired. This class can also be directly instantiated such as within a Servlet. The HttpSecurityFilter class is a minimal implementation of a Servlet Filter that extends this class.

Properties

The behavior of this class is driven by the key and value properties supplied to the init method.

The most important property is provider.classname which determines the underlying SecurityProvider to be used.

SecurityProvider behavior is also driven entirely by properties. All properties that being with "jespa." will be stripped of this prefix and passed to the designated SecurityProvider constructor. All other properties are used only by the HttpSecurityService.

The following table describes all properties used by HttpSecurityService and are therefore not specific to the SecurityProvider that is used:

Properties of the HttpSecurityService

Name	Description	Example
properties.path	The path to a text file containing properties and values described in this section. If the path refers to a readable file, the properties will be read and overwrite any properties in the Map supplied to init(). If the file is modified during the runtime of the program, the properties file will be automatically reloaded. The onPropertiesUpdate(java.util.Map) method will be called whenever the properties file is loaded or reloaded. This path may be a relative path relative to the context root or an absolute path prefixed with file:/ like file://path/to/busicoS19.prp or file:/C:\path\to\busicoS19.prp. Note: The file:/ is simply an escape sequence that indicates to the HttpSecurityService that the file is an absolute path. The prefix is removed and the remaining path is used with the conventional file interface. This parameter is not required. By default, properties are supplied through the Map passed to init().	/WEB-INF/example_ntlm.prp
provider.classname	The name of the jespa.security.SecurityProvider subclass that should be used. This parameter is not required. By default, the jespa.ntlm.NtlmSecurityProvider will be used.	jespa.ntlm.NtlmSecurityProvider
fallback.location	The absolute path or URL to which the client should be redirected if it cannot participate in authentication. For example, if this property is set and the user clicks "Cancel" after being presented with the Network Password Dialog, they should be redirected to this URL. This value is ultimately used to set the window.location on the client using JavaScript (the value is not escaped). This parameter is not required. If it is not specified and authentication cannot proceed, the client will resceive a 401 Unauthorized or 403 Forbidden response which browsers handle in different ways and may be a simple as to display a blank page.	/ErrorSupport.html
excludes	A comma separated list of paths relative to the webapp base that should be excluded from protection by this Filter. Caution: The paths in this list effectively bypass the Filter. These paths will be completely unprotected! Warning: These expressions have no knowledge of path separators. Wildcard characters are not limited to matching path labels and may traverse separators. For example, the expression /images/*.png would match the path /images/secret/d8siek20.png. Note: To include a literal comma in a path, put the element in quotes. To include a literal quote in a path, put the element in quotes and escape the literal quote by preceeding it with another quote. For example, the path /action.jsp,,"cart", would require an excludes element of "/action.jsp,,""cart"",". See The Excludes List section in the Jespa Operator's Manual for example wildcard expressions.	/account/login,/contact.html
http.parameter.username.name	The name of an HTTP request parameter used to submit a username for performing an HTTP parameter-based login. See the HTTPS Form Based Logins section below for details.	username
http.parameter.password.name	The name of an HTTP request parameter used to submit a password for performing an HTTP parameter-based login. See the HTTPS Form Based Logins section below for details.	password
http.parameter.logout.name	The name of an HTTP request parameter that triggers the Filter to destroy the SecurityProvider's session state and effectively log out the client. No additional code is required to facilitate a logout (although you may need to be conscientious about ignoring this parameter throughout your application). Note that the actual parameter value is ignored. For example, if this property is set to "logout", an HTTP request like https://www.example.com/Login.jsp?logout=1 might be used to logout the user and present them with a login form so that they can enter alternative credentials.	logout
http.parameter.anonymous.name	The name of an HTTP request parameter that bypasses authentication and installs an anonymous identity. Caution: This feature allows any client to completely bypass authentication. Before you enable this feature, please carefully read the Anonymous Access section below.	anon
groups.allowed	A comma separated list of group and account names that identify the users who are permitted access through the HttpSecurityService. If this parameter is not set, the default behavior is to permit access. See the Group Based Access Control section below for details.	EXMAPLE\Engineers,EXAMPLE\Managers
groups.denied	A comma separated list of group and account names that identify the users who are explicitly not permitted access through the HttpSecurityService. This parameter makes it easy to deny users who would otherwise be permitted access by the groups.allowed list. See the Group Based Access Control section below for details.	EXAMPLE\Sales
jespa.log.path	The absoltute path to a file into which the Jespa library should log information. Note: The Jespa log path and level values are global and static and therefore these may affect or be affected by other components in the same application that also use or set these values. For example, if you have two filter sections in a web.xml with different jespa.log.* values, the last filter to load will set the logging values for both filters. See the LogStream class for more information about logging in Jespa. This parameter is not required. If no path is supplied, log messages will be written to the default LogStream which, unless specified elsewhere, is System.err.	/tmp/jespa.log
jespa.log.level	A small integer that indicates the level of information that the Jespa library should log. Values are 0 - nothing; 1 - critical; 2 - basic (can be logged under load); 3 - more detail; 4+ - for debugging only. See also the note for jespa.log.path. This parameter is not required. The default value is 1.
bindings.targetSpns.policy	Controls how the HSS behaves if the client does not submit a valid SPN. Possible values are: 0 Disabled - No SPN checking is performed. 1 Allowed (default) - SPNs are checked but clients will not be rejected. The result is logged with a log.level of 3 or higher. 2 Required - SPNs must match an SPN in the bindings.targetSpns list or an SPN created from SubjectAltName entries in the server HTTPS certificate if any. If the client did not provide a matching SPN, the HSS will generate a SecurityProviderException, call onException() accordingly, dispose the SecurityProvider and return 401 Unauthorized.	2
bindings.targetSpns	A comma separated list of SPNs that this server accepts. An SPN is just a scheme and host like HTTP/www.example.com (the scheme is always HTTP even if TLS is being used). If TLS is being used (it should be) and the server certificate has dNSName or iPAddress SubjectAltName entries (it should), they will be used to generate SPNs automatically in which case it should not be necessary to set this property at all (but it can be set to add additional SPNs). Note: This feature requires that the SecurityProvider being used implements the targetSpn property correctly (to retrieve the SPN submitted by the client during authentication if any).	HTTP/as5.example.com,HTTP/10.2.3.4
bindings.cert.hash.policy	Controls how the HSS behaves if the client does not submit valid channel bindings. Possible values are: 0 Disabled - No channel bindings checking is performed. 1 Allowed - Channel bindings are checked but clients will not be rejected. The result is logged with a log.level of 3 or higher. 2 Required - The client must submit channel bindings as specified by the bindings.cert.* properties. If the client did not provide matching channel bindings, the HSS will generate a SecurityProviderException, call onException() accordingly, dispose the SecurityProvider and return 401 Unauthorized.	2
bindings.cert.hash	Explicitly sets the channel bindings hash to a specific value in hex. If this property is set, all other bindings.cert.* properties will be ignored. Values for this property may be observed in the Jespa log file (although if a MITM attack was affected the value could be incorrect).	531B8FFAC96ED512AD94EAB3687658A3
bindings.cert.keystore.path	The path to the keystore file containing the certificate from which to calculate the channel bindings hash. If this property is not set, the HSS will not use a keystore and all other bindings.cert.keystore.* properties will be ignored.	etc/alma92as5.p12
bindings.cert.keystore.type	The type of the keystore containing the certificate from which to calculate the channel bindings hash. The default value is PKCS12.	JKS
bindings.cert.keystore.provider	The provider of the keystore containing the certificate from which to calculate the channel bindings hash. The default value is SunJSSE.	SUN
bindings.cert.keystore.password	The password of the keystore containing the certificate from which to calculate the channel bindings hash. If this property is not set (which is not equivalent to an empty value), a value of null will be used with KeyStore.load() to indicate that a password is not required.	alma92as5
bindings.cert.pem.path	The path to a PEM file containing the PEM encoded certificate from which to calculate the channel bindings hash.	etc/alma92as5.pem
bindings.cert.pem	The PEM encoded certificate from which to calculate the channel bindings hash. Linebreaks will be ignored so that the entire certificate can be set on one line such as within a properties file like: -----BEGIN CERTIFICATE-----MIICmDC...77txZ2sZ8=-----END CERTIFICATE-----
bindings.cert.url	An HTTPS URL serving the certificate from which to calculate the channel bindings hash. If other bindings.cert.* properties are not set, the HSS will query this URL (using a "dummy" TLS trust manager) to retrieve the server certificate and calculate the channel bindings hash. Note: While using only this property is convenient, it is not the most secure option. If a MITM attack occurs when the channel bindings are initialized, the incorrect hash could be generated. Properly secured installations should use the bindings.cert.keystore.* or bindings.cert.pem* properties instead. If this value is not set, the value returned by HttpServletRequest.getRequestURL().toString() will be used (but only once each time the HSS is (re)initialized).	https://ext2.example.com

The HttpSecurityService also examines the SecurityProvider properties flags.capabilities.accept.ntlmssp and flags.capabilities.accept.spnego to determine if the SecurityProvider supports NTLM and/or SPNEGO. If the flags.capabilities.accept.ntlmssp property is not true, the HttpSecurityService will not challenge the client with WWW-Authenticate: NTLM. If the flags.capabilities.accept.spnego property is not true, the HttpSecurityService will not challenge the client with WWW-Authenticate: Negotiate (although currently no Jespa SecurityProvider supports SPNEGO anyway).

SPN and Channel Bindings (EPA)

SPN and channel bindings, which Microsoft calls Extended Protection for Authentication (EPA), are security measures that stop relay attacks and MITM attacks.

By default, without any bindings.* properties set, the HSS will automatically retrieve SPNs and calculate channel bindings from the server certificate.

However, the default policy is to not reject clients and only log the results. Also, automatically retrieving the TLS certificate is not the most secure option as an attacker could intercept this request during (re)initialization and defeat the channel bindings protection. The most secure option is to change the policy to require both SPN and channel bindings and to use the bindings.cert.keystore.* properties to explicitly and safely provide access to the server certifiate.

SPN Bindings

When performing Windows built-in SSO, all popular browsers submit a service principal name (SPN) identifying the scheme and hostname of the service they are authenticating with. If this SPN does not match a protocol and hostname that the server expects, it can reject the client. This feature will block a relay attack.

IMPORTANT: The default SPN bindings policy is 1 (Allowed). IOPLEX recommends that this value be changed to 2 (Required). To be confident that this change will not incorrectly reject clients, watch the Jespa log file (with log.level = 2), confirm that SPNs are matching properly and make adjustments if necessary.

Note: The curl program is known to not submit an SPN when usng NTLM (although it does submit channel bindings, see below).

See also the bindings.targetSpns* properties above.

Channel Bindings

When TLS is used, all popular browsers submit a hash of the TLS server certificate known as "channel bindings" or a "channel binding token (CBT)". If the channel bindings do not match the hash of the real certificate, the server can reject the client. This feature will block MITM attacks.

IMPORTANT: The default channel bindings policy is 1 (Allowed). IOPLEX recommends that this value be changed to 2 (Required). To be confident that this change will not incorrectly reject clients, watch the Jespa log file (with log.level = 2), confirm that channel bindings are matching properly and make adjustments if necessary.

See also the bindings.keystore.* properties above.

Loading the Channel Bindings Certificate

The certificate from which the channel bindings hash is calculated is just the server certificate. This certificate can be loaded using one of serveral different possible methods:

• If the bindings.cert.keystore.path property is set, the certificate will be loaded from it (in combination with the other bindings.cert.keystore.* properties).
• Otherwise, if the bindings.cert.pem.path property is set, and it refers to a valid PEM file, the first certificate with extKeyUsage serverAuth (OID 1.3.6.1.5.5.7.3.1) will be loaded from it.
• Otherwise, if the bindings.cert.pem property is set, the certificate will be decoded from the value.
• Otherwise, the HSS will attempt to retrieve the server certificate directly from the server (using a "dummy" TLS trust manager) and use it calculate the channel bindings hash. The URL used is either the bindings.cert.url property or, if this property is not set, the URL of the first client request that might contain channel bindings.

See also the bindings.cert.* properties above.

HTTPS Form Based Logins

The HttpSecurityService supports HTTP parameter-based username and password logins such as for use with a traditional HTML form.

Caution: It is insecure to use parameter-based logins without HTTPS.

To enabled this feature, simply set the http.parameter.username.name and http.parameter.password.name properties to the names of the username and password form field elements. Any request that submits those HTTP parameters will first be authenticated using the supplied credentials. No additional code is required to facilitate a login (although you may need to be conscientious about ignoring these parameters throughout your application).

Both properties must be set for the HttpSecurityService to perform HTTP parameter based logins.

Once authenticated, the client's identity will be maintained in HTTP session state. To "logout", see the http.parameter.logout.name property.

Anonymous Access

The HttpSecurityService may be configured to allow clients to bypass authentication and assume an anonymous identity.

Caution: This feature allows any client to effectively bypass authentication. If this feature is enabled, the developer is responsible for controlling access to all content accessed through the HttpSecurityService.

To enabled this feature, simply set the http.parameter.anonymous.name property to the name of an HTTP request parameter that will indicate to the HttpSecurityService that the client would like to access content anonymously. Note that the actual parameter value is ignored.

For example, if this property is set to "anon", an HTTP request like http://www.example.com/Whoami.jsp?anon=1 would bypass authentication and install the anonymous identity.

If the anonymous identity is installed, the getRemoteUser, getUserPrincipal, getAccount and getAuthType methods will return null. Additionally the isUserInRole method will always return false.

If this feature is enabled, access control becomes the responsibility of the developer. In particular, if getRemoteUser (or getUserPrincipal) returns null, the client has not authenticated and therefore they are "anonymous".

Note: Even though an anonymous client is not considered authenticated, SecurityProvider state is still stored in the HTTP session. Meaning once the anonymous identity is installed, the client will remain anonymous until they logout or explicitly login using alternative credentials.

Group Based Access Control

The HttpSecurityService supports group based access control. This feature is exposed in two ways:

1. The HttpServletRequest.isUserInRole method accepts group names and will determine if the current authenticated user is in the named group. If the NtlmSecurityProvider is used (and it is by default), a standard Windows access control check is performed. Specifically, the supplied name is translated into a SID and compared with the fully expanded list of group SIDs associated with the user's account.
2. The groups.allowed and groups.denied properties control who can authenticate through the HttpSecurityService (technically the client is authenticated but the authentication context is immediately disposed if they fail the groups.allowed or groups.denied access checks). This second case is described further below.

To enable group based access control as described in case 2 above, set the groups.allowed property to a comma separated list of group names. Only users within those groups will be permitted to authenticate with the HttpSecurityService and access content through it. If no groups.allowed property is specified, the default behavior is to permit access.

For example, if the HttpSecurityFilter is used with the NtlmSecurityProvider, the following init-param would restrict access to filtered content to only users in the named Windows groups.

  <init-param>
      <param-name>groups.allowed</param-name>
      <param-value>EXMAPLE\Engineers,EXAMPLE\Managers,EXAMPLE\Wiki Admins</param-value>
  </init-param>

Note: Most SecurityProviders also support specific account names and not just group names. For example, if a name like abaker@example.com were used in the list above, that specific user would also be allowed access.

Windows group and account names should be qualified with a domain like EXAMPLE\Engineers and not just Engineers to eliminate the possibility of unexpected behavior in a multi-domain environment.

The groups.denied property is also a comma separated list of group names. If a user is found to be in the any one of these groups, they will immediately be denied access without further checking. The groups.denied list is checked before the groups.allowed list.

Note: The groups.denied list is intended to add exceptions to the groups.allowed list. A typical problem with access control occurs when you wish to permit access to a large group but not to a few people who also happen to be in that group. The groups.denied list makes this much easier.

If a user is denied access due to either of these lists, they may still be able to access content in the excludes list (see the excludes option above) or if anonymous access is enabled and the client is anonymous and the underlying code permits access to that content by anonymous users (see the Anonymous Access section).

The NTLM Security Provider

The following table describes properties that are specific to the NtlmSecurityProvider. These properties will be passed to the NtlmSecurityProvider constructor in a properties map (minus the "jespa." prefix) and therefore the NtlmSecurityProvider documentation should be considered authoritative. These properties are reiterated here only for convenience or because the description includes special information in the context of the HttpSecurityService.

Properties specific to NtlmSecurityProvider

Name	Description	Example
jespa.bindstr	The fully qualified DNS domain name of the Active Directory domain against which the NtlmSecurityProvider should try to authenticate clients. This property is required. This property may also be a fully qualified DNS hostname of a specific AD server. This property must not be an IP address. If an IP address is used, a STATUS_INVALID_COMPUTER_NAME error will occur. If the domain or specific server identified by this property is not in the same (sub)domain as the HTTP service account, a STATUS_NO_TRUST_SAM_ACCOUNT error will occur. The specific AD server that the Jespa library will use is determined using DNS SRV queries. If a hostname of a specific AD server is supplied, that server must still be in the list of servers advertised by DNS as authorities for the target domain (unless DNS SRV lookups are disabled using the authority.dns.names.resolve property).	example.com
jespa.service.acctname	The name of the Computer account used for NETLOGON communication. See the Jespa Operator's Manual for details regarding how to create a Computer account and set it's password. As shown in the example to the right, the Computer account name should be the name followed by a $ sign followed by an @ sign followed by the DNS domain name (the backslash form like EXAMPLE\jespa1$ should also work). This property is required. Note: The service account must be a Computer account. A regular User account will not work.	JESPA1$@EXAMPLE.COM
jespa.service.password	The password of the above mentioned Computer account. This property is required.	a89609c53443ce1c72e59275a8a1e1ce
jespa.dns.servers	A comma separated list of IP addresses for Microsoft DNS servers that are authorities for the DNS SRV records used to locate AD services. See the DNS Requirements and Properties section in the Jespa Operator's Manual for details about this property and other DNS properties supported by the HttpSecurityService.	192.168.10.10,192.168.20.20
jespa.dns.site	The Active Directory Sites & Services site that the service is in. See the Active Directory Sites & Services section in the Jespa Operator's Manual for details about this property and other DNS properties supported by the HttpSecurityService.	Paris
jespa.account.canonicalForm	A small integer indicating the canonical form of the name returned by HttpServletRequest.getRemoteUser() and the SecurityPrincipal.getName() and toString methods of the Principal returned by HttpServletRequest.getUserPrincipal(). The four possible canonical forms are: 0 - None - The account name is not guaranteed to be in any particular form. If this property is not specified, this is the default value. 2 - Username - the username without a domain like alice. 3 - Backslash - the NetBIOS domain name and username separated by a backslash like EXAMPLE\alice. 4 - Principal - the username and DNS domain name separated by an at sign like alice@example.com. Note that this form is not the email address of the user. This property is not required. However, it almost certainly should be set to 3 (Backslash) or 4 (Principal) to provide a consistent name that is not ambiguous in multi-domain environments.	3
jespa.localhost.netbios.name	This property is deprecated and should not be used.

Implementation Details

HTTP authentication requires multiple requests before the desired content is returned. Most mechanisms require only two requests. NTLM requires three as illustrated by the following make-shift flow diagram.

C: GET /jespa/Whoami.jsp
S: 401 Unauthorized
   WWW-Authenticate: NTLM 
 
C: GET /jespa/Whoami.jsp
   Authorization: NTLM TlRMTVNTUAABAAAAB4IIAAAAAAAAAAAAAAAAAAAAAAA=
S: 401 Unauthorized
   WWW-Authenticate: NTLM TlRMTVNTUAACAAAAAAAAA...AC4AZgBvAG8ALgBuAGUAdAAAAAAA

C: GET /jespa/Whoami.jsp
   Authorization: NTLM TlRMTVNTUAADAAAAGAAYAFgA...AAAYABgAcAwATPGDh0OrwyZcJ9CEoJw==
S: 200 OK

NTLM over HTTP is a three-request "handshake"

Note that this means doFilter will be called multiple times before the FilterChain.doFilter method is called. This is important to keep in mind if you are creating a custom HTTP security solution.

After authentication has completed, the HttpSecurityService stores a byte[] array attribute in the HTTP session. The key is "jespa.provider.state". The presence of this attribute suppresses redundant authentications. If it is removed, the client will be required to reauthenticate.

Note: The "jespa.provider.state" attribute may not suppress all redundant authentications. Some browsers will preemtively reauthenticate POST requests (IE6 and IE8 are known to do this). Meaning, the client will submit the Authorization: NTLM TlRMTVNTUAABAAA... but without the POST parameters. In this case the HttpSecurityService will complete the authentication, receive the POST parameters in the third request and continue as usual.

JCIFS Properties No Longer Supported: Jespa 1.2.5 or later will ignore properties prefixed with "jcifs.". The only way to set JCIFS properties is by calling jcifs.Config.setProperty directly from within your code or through a JCIFS properties file specified on the commandline on startup. See the Setting Client Properties page on the JCIFS website for details.

Constructor Summary

Constructors

Constructor and Description
HttpSecurityService()

Method Summary

Modifier and Type	Method and Description
void	destroy() This method closes the log stream opened if the jespa.log.path property is set.
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain) The HttpSecurityService request handler.
protected int	getBindingsCertHashPolicy(SecurityProvider ctx, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, int defaultPolicy) This protected method is called by doFilter after authentication to determine how the channel bindings checking should be performed for this client.
protected int	getBindingsTargetSpnsPolicy(SecurityProvider ctx, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, int defaultPolicy) This protected method is called by doFilter after authentication to determine how the target SPN checking should be performed for this client.
protected java.lang.String	getConnectionId(javax.servlet.http.HttpServletRequest req) This protected method is called by doFilter to compute a String that uniquely identifies the client's connection so that stateful multi-request authentication can be conducted with multiple independent clients concurrently.
protected java.lang.Object	getRequestCredential(javax.servlet.http.HttpServletRequest request) This protected method is called by doFilter to both a) determine if explicit credential based authentication should be performed and b) retrieve that credential for authentication.
protected java.lang.String	getRequestPath(javax.servlet.http.HttpServletRequest request) This protected method is called internally to obtain the canonicalized and decoded path of the HTTP request.
javax.servlet.ServletContext	getServletContext() Returns the ServletContext provided to init.
void	init(java.util.Map props) Deprecated. As of Jespa 1.1 use init(String, ServletContext, Map)
void	init(java.lang.String name, javax.servlet.ServletContext servletContext, java.util.Map props) Initialize this HttpSecurityService with the supplied name, ServletContext and properties.
protected void	isAllowedAccess(SecurityProvider provider, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp) This protected method is called by doFilter after authentication to determine if the client is allowed access to resources protected by this HttpSecurityService.
protected boolean	isAnonymous(javax.servlet.http.HttpServletRequest request) This protected method is called by doFilter to determine if the special "anonymous" identity should be installed.
protected boolean	isLogout(javax.servlet.http.HttpServletRequest request) This protected method is called by doFilter to determine if this is a request to "logout" the current user.
protected boolean	isProtected(javax.servlet.http.HttpServletRequest request) This protected method is called by doFilter to determine if the request is for a protected resource which may only be accessed by an authenticated client.
protected static int	matchWildcard(java.lang.String[] wildcards, java.lang.String str) Case-sensitive compare the supplied string to the list of DOS-style wildcard expressions with * and ? to match zero-or-more and one-or-more characters respectively and return the index of the expression that matched or -1 to indicat that no expression matched.
protected void	onException(SecurityProviderException spe, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse rsp, SecurityProvider provider) This protected method is called from doFilter when a SecurityProviderException occurs trying to call either SecurityProvider.acceptSecContext or SecurityProvider.authenticate.
protected void	onPropertiesUpdate(java.util.Map props) This protected method is called from init and whenever the file identified by properties.path has been modified (but it will not be called more than once within a 5 second period).
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

HttpSecurityService

public HttpSecurityService()

Method Detail

init

public void init(java.util.Map props)
          throws SecurityProviderException

Deprecated. As of Jespa 1.1 use init(String, ServletContext, Map)

Initialize this HttpSecurityService with the supplied properties. See above for a list of property descriptions.

Parameters:

props - The HttpSecurityService and SecurityProvider properties.

Throws:

SecurityProviderException

init

public void init(java.lang.String name,
                 javax.servlet.ServletContext servletContext,
                 java.util.Map props)
          throws SecurityProviderException

Initialize this HttpSecurityService with the supplied name, ServletContext and properties. See above for a list of property descriptions.

Parameters:

name - The name of this HttpSecurityService instance

servletContext - The ServletContext that is initializing this HttpSecurityService instance

props - The HttpSecurityService and SecurityProvider properties

Throws:

SecurityProviderException

destroy

public void destroy()

This method closes the log stream opened if the jespa.log.path property is set. If this method is overridden, it is important to call super.destroy() (perhaps in a finally clause) to ensure that the underlying log file descriptor is closed.

onPropertiesUpdate

protected void onPropertiesUpdate(java.util.Map props)
                           throws SecurityProviderException

This protected method is called from init and whenever the file identified by properties.path has been modified (but it will not be called more than once within a 5 second period).

The default implementation just initializes the jespa.util.LogStream. Subclasses may override this method (and should call super.onPropertiesUpdate(props) within it) to re-initialize things that depend on properties loaded from the properties.path file.

Parameters:

props - The updated list of properties. The properties Map should not be modified.

Throws:

SecurityProviderException

getServletContext

public javax.servlet.ServletContext getServletContext()

Returns the ServletContext provided to init.

Note: If the deprecated init constructor was used to initialize this HttpSecurityService instance, this method will throw a RuntimeException.

Returns:

the ServletContext provided to init

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getRequestCredential

protected java.lang.Object getRequestCredential(javax.servlet.http.HttpServletRequest request)
                                         throws SecurityProviderException

This protected method is called by doFilter to both a) determine if explicit credential based authentication should be performed and b) retrieve that credential for authentication.

This method is exposed to the developer so that a subclass can override the default behavior. For example, an implementation might return a custom credential required by a custom SecurityProvider.

The default implementation returns a PasswordCredential constructed with the username and password extracted from HTTP request parameters identified by the http.parameter.username.name and http.parameter.password.name properties.

If token-based authentication is not already being conducted this method will be called. If a non-null value is returned, an instance of the configured SecurityProvider will be created and it's authenticate() method will be called with the credential object. If this method returns null, explicit authentication is not performed.

Parameters:

request - the HttpServletRequest passed to doFilter

Returns:

an Object representing the credential to be authenticated (a PasswordCredential containing a username and password is the default).

Throws:

SecurityProviderException

isLogout

protected boolean isLogout(javax.servlet.http.HttpServletRequest request)
                    throws javax.servlet.ServletException

This protected method is called by doFilter to determine if this is a request to "logout" the current user. If this method returns true, any jespa.provider.state attribute in the HTTP session will be removed thereby logging out the current authenticated user.

This method is exposed to the developer as a protected method so that a subclass can override the default behavior. For example, an implementation might look at the request path to determine if it is a logout request (as opposed to looking at an HTTP parameter).

The default implementation returns true if the HTTP parameter http.parameter.logout.name is present (note that the actual value of the parameter is ignored).

Parameters:

request - the HttpServletRequest passed to doFilter

Returns:

true if the authenticated user should be logged out

Throws:

javax.servlet.ServletException

isAnonymous

protected boolean isAnonymous(javax.servlet.http.HttpServletRequest request)
                       throws javax.servlet.ServletException

This protected method is called by doFilter to determine if the special "anonymous" identity should be installed. This method is not called and the "anonymous" identity is not installed if SecurityProvider state already exists in the HTTP session. Otherwise, if the value returned is true, a new instance of the configured SecurityProvider will be created with a property and value of anonymous = 1 and this special "dummy" SecurityProvider will be installed into the HTTP session to persist the "anonymous" identity.

WARNING: Installing the "anonymous" identity will effectively turn off security in the HttpSecurityService. Because the default implementation simply looks for the existance of an HTTP parameter, it allows any client to bypass authentication. In this case, the developer is responsible for securing all resources.

This method protected method so that a subclass can override the default behavior. For example, an implementation might return true if the HttpSecurityService should be bypassed because another component will be providing security for the application.

The "anonymous" SecurityProvider that is installed into the HTTP session will have no identity or default account. The getIdentity and getAccount methods will return null and isUserInRole will always return false.

The default implementation returns true if the HTTP parameter http.parameter.anonymous.name is present (note that the actual value of the parameter is ignored).

To re-enable security provided by the HttpSecurityService, un-install the "anonymous" SecurityProvider state by having isLogout return true (or by removing the "jespa.provider.state" attribute from the HttpSession).

Parameters:

request - the HttpServletRequest passed to doFilter

Returns:

true if the "anonymous" identity should be installed

Throws:

javax.servlet.ServletException

matchWildcard

protected static int matchWildcard(java.lang.String[] wildcards,
                                   java.lang.String str)
                            throws javax.servlet.ServletException

Case-sensitive compare the supplied string to the list of DOS-style wildcard expressions with * and ? to match zero-or-more and one-or-more characters respectively and return the index of the expression that matched or -1 to indicat that no expression matched.

See The Excludes List section in the Jespa Operator's Manual for example wildcard expressions.

Throws:

javax.servlet.ServletException

getRequestPath

protected java.lang.String getRequestPath(javax.servlet.http.HttpServletRequest request)
                                   throws javax.servlet.ServletException

This protected method is called internally to obtain the canonicalized and decoded path of the HTTP request.

This method is exposed to the developer as a protected method so that a subclass can override the default behavior.

The default implementation simply normalizes the return value of HttpServletRequest.getRequestURI.

Parameters:

request - the HttpServletRequest object passed to doFilter

Returns:

the canonicalized and decoded path of the HTTP request

Throws:

javax.servlet.ServletException

isProtected

protected boolean isProtected(javax.servlet.http.HttpServletRequest request)
                       throws javax.servlet.ServletException

This protected method is called by doFilter to determine if the request is for a protected resource which may only be accessed by an authenticated client. If this method returns false, the client will not be challenged for authentication for this request.

WARNING: If this method returns false, the resource associated with this request will be completely unprotected by the HttpSecurityService.

This method is exposed to the developer as a protected method so that a subclass can override the default behavior.

The default implementation of this method retrieves the request path with getRequestPath and then compares it to the excludes list specified with the excludes property which is a list of paths that may contain DOS-style wildcard expressions. If the request path matches an excludes path, this method returns false to indicate that the request is not protected. Otherwise, true is returned.

Note: If this method returns false, clients may still initiate authentication anyway in which case the HttpSecurityService will honor that authentication and ignore the return value of this method. In fact, some versions of Internet Explorer are known to proactively re-authenticate POST requests regardless of whether or not the server challenges the client for authentication.

Parameters:

request - the HttpServletRequest object passed to doFilter for the protected resource

Returns:

false if the request is not for a protected resource - otherwise true

Throws:

javax.servlet.ServletException

getBindingsTargetSpnsPolicy

protected int getBindingsTargetSpnsPolicy(SecurityProvider ctx,
                                          javax.servlet.http.HttpServletRequest req,
                                          javax.servlet.http.HttpServletResponse rsp,
                                          int defaultPolicy)
                                   throws SecurityProviderException

This protected method is called by doFilter after authentication to determine how the target SPN checking should be performed for this client.

The default behavior is to simply return the defaultPolicy value (defined by the bindings.targetSpns.policy property).

An alternative implementation might inspect the request and return a value that would allow (or not allow) the client to proceed if the supplied SPN did not match the list of permitted SPNs.

Code like String targetSpn = (String)ctx.getProperty("targetSpn", null) will return the SPN supplied by the client or null if the client did not supply an SPN or if the SecurityProvider does not support the targetSpn property.

Returns:

0 (disabled), 1 (allow) or 2 (required)

Throws:

SecurityProviderException

Since:

Jespa 2.0.0

getBindingsCertHashPolicy

protected int getBindingsCertHashPolicy(SecurityProvider ctx,
                                        javax.servlet.http.HttpServletRequest req,
                                        javax.servlet.http.HttpServletResponse rsp,
                                        int defaultPolicy)
                                 throws SecurityProviderException

This protected method is called by doFilter after authentication to determine how the channel bindings checking should be performed for this client.

The default behavior is to simply return the defaultPolicy value (defined by the bindings.cert.hash.policy property).

An alternative implementation might inspect the request and return a value that would allow (or not allow) the client to proceed if no channel bindings were supplied or did not match the expected value.

Code like byte[] channelBindings = (byte[])ctx.getProperty("channelBindings", null) should return the channel bindings value supplied by the client or null if the client did not supply channel bindings or if the SecurityProvider does not support the channelBindings property.

Returns:

0 (disabled), 1 (allow) or 2 (required)

Throws:

SecurityProviderException

Since:

Jespa 2.0.0

isAllowedAccess

protected void isAllowedAccess(SecurityProvider provider,
                               javax.servlet.http.HttpServletRequest req,
                               javax.servlet.http.HttpServletResponse rsp)
                        throws SecurityProviderException

This protected method is called by doFilter after authentication to determine if the client is allowed access to resources protected by this HttpSecurityService. If the client is not allowed acccess, this method will throw a SecurityProviderException with a status code of SecurityProviderException.STATUS_ACCESS_DENIED.

The default implementation denies access if the user being authenticated is either:

• in a group in the groups denied list defined by the groups.denied property or
• if the groups.allowed property is specified and the user is not in a group in the groups allowed list.

This method is exposed to the developer as a protected method so that a subclass can override the default behavior. Consider the following example:

Account acct = provider.getAccount(null, null);
if (acct.isMemberOf("BUSICORP\\Engineers"))
    return;
throw new SecurityProviderException(SecurityProviderException.STATUS_ACCESS_DENIED, provider.getIdentity() + " denied access because not in group BUSICORP\Engineers");

A possible alternative implementation of the isAllowedAccess method

If rsp.setStatus(HttpServletResponse.SC_FORBIDDEN) is called within this method, the HttpSecurityService will not challenge the client for authentication again (because it 403 Forbidden is sent instead of 401 Unauthorized) whereas the default behavior is to repeatedly challenge the client until it is successfully authenticated (which may repeatedly trigger the browser password dialog).

Parameters:

provider - the SecurityProvider used to authenticate the user

req - the HttpServletRequest object passed to doFilter that triggered authentication

rsp - the HttpServletResponse object passed to doFilter

Throws:

SecurityProviderException

getConnectionId

protected java.lang.String getConnectionId(javax.servlet.http.HttpServletRequest req)
                                    throws SecurityProviderException

This protected method is called by doFilter to compute a String that uniquely identifies the client's connection so that stateful multi-request authentication can be conducted with multiple independent clients concurrently.

The default implementation of this method attempts to determine the client's remote IP address and port number and returns a value like "192.168.10.11:12345". The header REMOTE_PORT may be used to help determine this value. However, if the header Jespa-Connection-Id is present, it's value will be used as the connection ID.

Note: The value returned by this method must uniquely identify the clients connection. Using the session ID for example would not be sufficient as it is common for a browser to create multiple connections with the same cookies such as when using frames and AJAX.

Parameters:

req - the HttpServletRequest passed to doFilter

Returns:

a String that uniquely identifies the client's connection

Throws:

SecurityProviderException

onException

protected void onException(SecurityProviderException spe,
                           javax.servlet.http.HttpServletRequest req,
                           javax.servlet.http.HttpServletResponse rsp,
                           SecurityProvider provider)
                    throws SecurityProviderException

This protected method is called from doFilter when a SecurityProviderException occurs trying to call either SecurityProvider.acceptSecContext or SecurityProvider.authenticate.

For example, if authentication fails because the user's password is incorrect, an implimentation may wish to retrieve the error code or text and store it into the HttpSession so that it can be retrieved later for display to the user. The default implementation only logs the Exception message.

Override this method in your custom HttpSecurityService to enable your application to display authentication related errors to users. Specifically, save the error message in the HttpSession with code like the following:

protected void onException(SecurityProviderException spe,
        HttpServletRequest req,
        HttpServletResponse rsp,
        SecurityProvider sp) throws SecurityProviderException
{
    HttpSession ssn = req.getSession(true);
    ssn.setAttribute("jespa.message", spe.getMessage());
}

Override this method in your custom HttpSecurityService to save authentication errors in the HttpSession

You may also want to examine the status code and create custom messages (for at least SecurityProviderException.STATUS_ACCOUNT_NOT_FOUND and STATUS_INVALID_CREDENTIALS). Then get (and remove) the message from the HttpSession when you generate the page displayed to users for authentication failures (specified by the fallback.location property). The following JSP fragment might be used to do this:

<%
HttpSession ssn = request.getSession(false);
if (ssn != null) { 
    String message = (String)ssn.getAttribute("jespa.message");
    if (message != null) { 
        ssn.removeAttribute("jespa.message");
        out.println("<div class='errmsg'>");
        out.println(message);
        out.println("</div>");
    }
}
%>

Fetch a message from the HttpSession (such as an authentication error) for display to the user

Note: Do not set rsp.setStatus(HttpServletResponse.SC_FORBIDDEN) here. This might seem like a way to stop the browser's builtin password dialog (403 Forbidden instead of 401 Unauthorized will stop the client from authenticating) but in truth the authentication will silently fail repeatedly until the browser is restarted because browsers can (and generally do) cache and reuse the incorrect credentials. There is no way for the server tell the client not to use the builtin password dialog.

Note: Throwning a SecurityProviderException from this method will cause the provider to be disposed, the exception stack trace will be logged (log.level >= 4) and the overall request will fail with 401 Unauthorized. The doFilter method will never (and should never) throw an Exception under normal operating conditions.

Note: Because this method is called when a failure occurs trying to perform authentication, the SecurityProvider parameter cannot be used to retrieve information about the user being authenticated because authentication was never completed (and getRequestCredential is only applicable to HTTP parameter based authentication and not SSO or the browser's builtin password dialog).

Throws:

SecurityProviderException

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws java.io.IOException,
                     javax.servlet.ServletException

The HttpSecurityService request handler. As described in the Implementation Details section, it is important to understand that this method may be called multiple times before the FilterChain.doFilter method is called.

Note: Even though this method has the same signature as Filter.doFilter, this class does not implement the Filter interface. The same method signature was used only to make it trivial to implement a Filter if desired. If you choose not to implement a Filter, you will need to create a dummy FilterChain object that calls your application.

Parameters:

request - the HttpServletRequest being handled

response - the HttpServletResponse being handled

chain - the FilterChain to call if the client successfully traverses the HttpSecurityService's security controls

Throws:

java.io.IOException

javax.servlet.ServletException