HeaderAuthenticationFilter (web-commons 5.0.0 API)

java.lang.Object
- nl.b3p.web.filter.HeaderAuthenticationFilter

All Implemented Interfaces:: javax.servlet.Filter

public class HeaderAuthenticationFilter
extends Object
implements javax.servlet.Filter

Servlet filter which wraps the request to return getUserPrincipal(), getRemoteUser(), and isUserInRole() results according to HTTP headers we trust meant to be sent by Apache modules like mod_auth_mellon and not by end users (the webserver MUST be configured correctly to avoid security problems).

WARNING: only enable when all requests to authPath are proxied via a webserver which overwrites the client request header configured as userHeader! If you use mod_proxy_ajp, DISABLE access through the Tomcat HTTP connector!

Note that if you only want to use SAML authentication, you can use Apache authentication by setting the tomcatAuthentication attribute on the AJP Connector to false in server.xml, and for authorization either use Apache (isUserInRole() always returns false) or use a Realm which recognizes the IdP usernames for roles and set tomcatAuthorization to true on the Connector to use isUserInRole().

This filter trusts HTTP request headers, which must be set by Apache on the configured authPath to overwrite any headers sent by the client! Unfortunately, the more secure way of passing information using environment variables is not supported by mod_proxy_ajp and Tomcat. Environment variables can be propagated using the AJP_ prefix, but these are only set on the CoyoteRequest which is not available to the web application.

Usage with mod_auth_mellon for SAML support

Configure Mellon as follows:

 <Location />
     MellonEndpointPath "/mellon"
     MellonSPPrivateKeyFile mellon/sp-private-key.pem
     MellonSPCertFile mellon/sp-cert.pem
     MellonIdpMetadataFile mellon/idp-metadata-here.xml

     # When using localhost for testing
     #MellonSubjectConfirmationDataAddressCheck off
 </Location>

 <Location /[contextPath]/auth/saml>
     Require valid-user
     AuthType "Mellon"
     MellonEnable auth

     # For tomcatAuthentication=false, set the username to this attribute's oid
     MellonUser "urn:oid:0.9.2342.19200300.100.1.1"

     # Optional: if you want the Mellon Session XML to be available, enable
     # these options and also configure the AJP connector in Tomcat/conf/server.xml
     # with packetSize:
     # <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" packetSize="65536"/>
     #MellonSessionDump On
     #RequestHeader set MELLON_SESSION "%{MELLON_SESSION}e"
     # Set this outside the <Location> block
     #ProxyIOBufferSize 65536

     # Look at the base64 decoded MELLON_SESSION (using printenv.pl or similar)
     # to see the oids of the returned attributes. This oid is for uid
     MellonSetEnvNoPrefix "MELLON_uid" "urn:oid:0.9.2342.19200300.100.1.1"
     RequestHeader set MELLON_uid "%{MELLON_uid}e"

     # oid for FriendlyName="eduPersonAffiliation"
     # Supported in newer Mellon versions:
     #MellonMergeEnvVars On
     MellonSetEnvNoPrefix "MELLON_roles" "urn:oid:1.3.6.1.4.1.5923.1.1.1.1"
     RequestHeader set MELLON_roles "%{MELLON_roles}e"
     # If merging is not supported, use multiple request headers, for a maximum
     # number of groups, add more to increase maximum
     RequestHeader set MELLON_roles_0 "%{MELLON_roles_0}e"
     RequestHeader set MELLON_roles_1 "%{MELLON_roles_1}e"
     RequestHeader set MELLON_roles_2 "%{MELLON_roles_2}e"
     RequestHeader set MELLON_roles_3 "%{MELLON_roles_3}e"
     RequestHeader set MELLON_roles_4 "%{MELLON_roles_4}e"
     RequestHeader set MELLON_roles_5 "%{MELLON_roles_5}e"
  </Location>

Servlet filter configuration

Configure with a filter-mapping for the entire webapp with the init parameters as described in the JavaDoc.

Logging out

Not currently supported. To enable logout by IdP calling the SingleLogoutService binding, we would need to enable MellonEnable info for all URL's and check if the userHeader is still there when the principal is on the session attribute. SP initiated logout also not supported, would need extra configuration of the SingleLogoutService binding in the IdP metadata.

Author:: Matthijs Laan

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`PARAM_AUTH_INIT_PATH` authInitPath init-param: path which will save a returnTo parameter or Referer before redirecting to the authPath, default "/auth/init".
`static String`	`PARAM_AUTH_PATH` authPath init-param: path after the contextPath for which Apache is configured to send the authentication/authorization headers which we trust - must override any headers sent by the client, default "/auth/saml".
`static String`	`PARAM_COMMON_ROLE` commonRole init-param: role to always add to users authenticated by this filter.
`static String`	`PARAM_ENABLED` Filter only works when this init-param is set to true, which must only be done when the client cannot send the userHeader - meaning the Tomcat HTTP connector must be disabled as all requests must go through Apache mod_proxy_ajp configured as above to clear this header and only sets it when properly authenticated.
`static String`	`PARAM_ROLES_HEADER` rolesHeader init-param: header which contains the roles.
`static String`	`PARAM_ROLES_SEPARATOR` rolesSeparator init-param: if configured, the separator to split the roles with.
`static String`	`PARAM_SAVE_EXTRA_HEADERS` saveExtraHeaders init-param: extra headers to save sent to authPath, such as MELLON_SESSION, separated by ','.
`static String`	`PARAM_USE_ROLES_NSUFFIX` useRolesNSuffix init-param: set to "true" to use a suffix for the roles header instead of splitting on a separator, defaults to true if rolesSeparator is not set.
`static String`	`PARAM_USER_HEADER` userHeader init-param: the request header that contains the username, default MELLON_uid.

Constructor Summary

Constructors
Constructor and Description

HeaderAuthenticationFilter()

Constructors
Constructor and Description
`HeaderAuthenticationFilter()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`destroy()`
`void`	`doFilter(javax.servlet.ServletRequest servletRequest, javax.servlet.ServletResponse servletResponse, javax.servlet.FilterChain chain)`
`static Map<String,String>`	`getExtraHeaders(javax.servlet.http.HttpServletRequest request)`
`void`	`init(javax.servlet.FilterConfig filterConfig)`
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - PARAM_USER_HEADER
```
public static final String PARAM_USER_HEADER
```
    userHeader init-param: the request header that contains the username, default MELLON_uid.
    
    See Also:
    
    Constant Field Values
  - PARAM_AUTH_PATH
```
public static final String PARAM_AUTH_PATH
```
    authPath init-param: path after the contextPath for which Apache is configured to send the authentication/authorization headers which we trust - must override any headers sent by the client, default "/auth/saml". If the application directly redirects to this path without redirecting to authInitPath first, redirects to the contextPath after succesful authentication.
    
    See Also:
    
    Constant Field Values
  - PARAM_AUTH_INIT_PATH
```
public static final String PARAM_AUTH_INIT_PATH
```
    authInitPath init-param: path which will save a returnTo parameter or Referer before redirecting to the authPath, default "/auth/init". The returnTo parameter is saved in the session and redirected to after successful login. Only relative URL's supported, otherwise redirects to the contextPath. When no returnTo parameter is present the Referer header is saved and redirected to after successful login.
    
    See Also:
    
    Constant Field Values
  - PARAM_ROLES_HEADER
```
public static final String PARAM_ROLES_HEADER
```
    rolesHeader init-param: header which contains the roles.
    
    See Also:
    
    Constant Field Values
  - PARAM_ROLES_SEPARATOR
```
public static final String PARAM_ROLES_SEPARATOR
```
    rolesSeparator init-param: if configured, the separator to split the roles with. If useRolesNSuffix is set to false, this defaults to ';'. Use with MellonMergeEnvVars.
    
    See Also:
    
    Constant Field Values
  - PARAM_USE_ROLES_NSUFFIX
```
public static final String PARAM_USE_ROLES_NSUFFIX
```
    useRolesNSuffix init-param: set to "true" to use a suffix for the roles header instead of splitting on a separator, defaults to true if rolesSeparator is not set. When rolesHeader is "groups", searches for roles_0, roles_1, roles_2, etc. Will stop when header contains "(null)" as sent by Apache when variable is null or next _N header is not found.
    
    See Also:
    
    Constant Field Values
  - PARAM_COMMON_ROLE
```
public static final String PARAM_COMMON_ROLE
```
    commonRole init-param: role to always add to users authenticated by this filter.
    
    See Also:
    
    Constant Field Values
  - PARAM_SAVE_EXTRA_HEADERS
```
public static final String PARAM_SAVE_EXTRA_HEADERS
```
    saveExtraHeaders init-param: extra headers to save sent to authPath, such as MELLON_SESSION, separated by ','. Retrieve using getExtraAuthHeaders().
    
    See Also:
    
    Constant Field Values
  - PARAM_ENABLED
```
public static final String PARAM_ENABLED
```
    Filter only works when this init-param is set to true, which must only be done when the client cannot send the userHeader - meaning the Tomcat HTTP connector must be disabled as all requests must go through Apache mod_proxy_ajp configured as above to clear this header and only sets it when properly authenticated.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - HeaderAuthenticationFilter
```
public HeaderAuthenticationFilter()
```
- Method Detail
  - init
```
public void init(javax.servlet.FilterConfig filterConfig)
```
    Specified by:
    
    init in interface javax.servlet.Filter
  - destroy
```
public void destroy()
```
    Specified by:
    
    destroy in interface javax.servlet.Filter
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - doFilter
```
public void doFilter(javax.servlet.ServletRequest servletRequest,
                     javax.servlet.ServletResponse servletResponse,
                     javax.servlet.FilterChain chain)
              throws IOException,
                     javax.servlet.ServletException
```
    Specified by:
    
    doFilter in interface javax.servlet.Filter
    
    Throws:
    
    IOException
    
    javax.servlet.ServletException
  - getExtraHeaders
```
public static Map<String,String> getExtraHeaders(javax.servlet.http.HttpServletRequest request)
```

Class HeaderAuthenticationFilter

Usage with mod_auth_mellon for SAML support

Servlet filter configuration

Logging out

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PARAM_USER_HEADER

PARAM_AUTH_PATH

PARAM_AUTH_INIT_PATH

PARAM_ROLES_HEADER

PARAM_ROLES_SEPARATOR

PARAM_USE_ROLES_NSUFFIX

PARAM_COMMON_ROLE

PARAM_SAVE_EXTRA_HEADERS

PARAM_ENABLED

Constructor Detail

HeaderAuthenticationFilter

Method Detail

init

destroy

toString

doFilter

getExtraHeaders