Logging in via the HTTP request header

JAAS module name: de.espirit.firstspirit.server.authentication.RequestHeaderLoginModule

This module is used in conjunction with a web access management system; i.e., a reverse proxy with a simultaneous authentication function. In the network topology, the reverse proxy is operated nearby the WebApp server being used for FirstSpirit. For example, it could be that the reverse proxy is in the DMZ and the FirstSpirit WebApp server is in the LAN or in the DMZ too.

The reverse proxy automatically authenticates the user who calls up the FirstSpirit start page using a web browser. The authentication process is completely independent from FirstSpirit. It may take place via Kerberos, a PKI (“public key infrastructure”) smart card, or an HTML input form, for instance. In each HTTP request following successful authentication, the reverse proxy transfers the user name of the authenticated user between the reverse proxy and the FirstSpirit WebApp server. It does so by means of an entry in the HTTP request header.

To ensure the authenticity of the transferred user name in the HTTP request header, the RequestHeaderLoginModule checks either the sending proxy's IP address or its HTTP client certificate (see configuration).

FirstSpirit then accepts the transferred user name as a FirstSpirit user name. This means there is no need for the user to perform additional authentication on FirstSpirit.

Parameters:

authHeader

Name of the HTTP header in which the reverse proxy enters the user name (example for IBM WebSEAL: iv-user)

allowedCerts

Name (common name DN) of the HTTPS client certificate for the reverse proxy. Multiple certificate names are separated by a ; character. All incoming certificates are then checked against the truststore of the FirstSpirit WebApp server JVM. The RequestHeaderLoginModule only reads out the user name from the HTTP header in the case of HTTP requests with a valid certificate, so that it is only possible to log into FirstSpirit through the HTTP header specification and not without authentication.

To determine the correct name of the client certificate during installation:

• operate the FirstSpirit WebApp in DEBUG log level, then
• read out the certificate name from the log file firstspirit.log and enter it as a parameter value.

allowedAddrs

If the parameter allowedCerts is not defined – in the case of test environments with low security requirements, for example – the parameter allowedAddrs must be used. The IP address of the reverse proxy is passed in this case. The user name is only read out from the HTTP header in the case of HTTP requests from this address. Multiple addresses are separated by a , or a ; character. The parameters allowedAddrs and allowedCerts may also be combined so that the certificate and the IP address are checked at the same time.

The RequestHeaderLoginModule is entered in the websso area of file fs-jaas.conf (via FirstSpirit ServerMonitoring / Configuration / Login configuration):

/* FirstSpirit start page with SSO: ContentCreator, SiteArchitect with Webstart */
websso {          
de.espirit.firstspirit.server.authentication.FSTicketLoginModule sufficient;
//de.espirit.firstspirit.server.authentication.KerberosLoginModule 
optional useFullPrincipal="false";
//de.espirit.firstspirit.server.authentication.RequestHeaderLoginModule 
optional authHeader="iv-user" 
//allowedCerts="CN=proxy1,OU=editors,DC=domain;CN=proxy2,OU=editors,DC=domain"
//allowedAddrs="10.11.12.13;10.11.12.14";
//de.espirit.firstspirit.server.authentication.LdapLoginModule optional section="LDAP";
de.espirit.firstspirit.server.authentication.FSUserLoginModule optional;
};

The paths and designations must be adapted in line with the local system.

To configure the HTTPS connector, refer to HTTPS server configuration and the following information:

The configuration is dependent on the specific system environment in which the module is being used. The configuration adaptations below are examples only and do not claim to be complete.

If a CA within an organization is being used and Tomcat is being used as the WebApp server, in tomcat/bin/setenv.sh there must be a link to a valid trust store in JAVA_OPTIONS; for example:

-Djavax.net.ssl.trustStore=/opt/tomcat/conf/fs-truststore.jks

-Djavax.net.ssl.trustStorePassword=changeit

Logging

Any errors or notifications that arise are passed to the logging system “log4j” (see also https://logging.apache.org/log4j/1.2/manual.html). For this purpose, the following call must be added to file fs-logging.conf (via ServerMonitoring / Configuration / Logging), with any of the log levels DEBUG, INFO, and ERROR available for selection:

log4j.logger.de.espirit.firstspirit.server.authentication.RequestHeaderLoginModule=DEBUG

Once the server has been restarted, the log outputs are displayed in firstspirit5/log/fs‑server.log. It is also possible to read the transferred certificate names (DN) there.

Following a successful test login, the log level should be restored to its default setting:

log4j.logger.de.espirit.firstspirit.server.authentication.RequestHeaderLoginModule=INFO