HeaderAuthenticationFilter (web-commons 5.3.3 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: pick a random header name prefix for each installation so that users cannot send their own headers when connecting directly to the Tomcat HTTP connector if that is enabled and not firewalled.
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. Pick a random header prefix to prevent a user from maliciously providing the headers directly to the HTTP connector.

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 [prefix]_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 [prefix]_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 [prefix]_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 [prefix]_roles_0 "%{MELLON_roles_0}e"
     RequestHeader set [prefix]_roles_1 "%{MELLON_roles_1}e"
     RequestHeader set [prefix]_roles_2 "%{MELLON_roles_2}e"
     RequestHeader set [prefix]_roles_3 "%{MELLON_roles_3}e"
     RequestHeader set [prefix]_roles_4 "%{MELLON_roles_4}e"
     RequestHeader set [prefix]_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.

To support custom deployments overriding parameters without having to overwrite web.xml (which needs to be kept up-to-date with new versions), context parameters can also be set to override filter init-params by prefixing them with headerAuth and uppercasing the first character of the parameter name, so to set the "prefix" parameter using a context parameter, use "headerAuthPrefix" as the parameter name.

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_HEADER_PREFIX` Random header prefix which must be kept secret and changed on each deployment.
`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 [prefix]_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 _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_HEADER_PREFIX
```
public static final String PARAM_HEADER_PREFIX
```
    Random header prefix which must be kept secret and changed on each deployment. If this is not changed from the default, this filter is not enabled.
    
    See Also:
    
    Constant Field Values
  - PARAM_USER_HEADER
```
public static final String PARAM_USER_HEADER
```
    userHeader init-param: the request header that contains the username, default _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 [prefix]_SESSION, separated by ','. Retrieve using getExtraAuthHeaders().
    
    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_HEADER_PREFIX

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

Constructor Detail

HeaderAuthenticationFilter

Method Detail

init

destroy

toString

doFilter

getExtraHeaders