Delivery Tier Authentication Configuration

Introduction

Goal

Learn about the delivery tier's default authentication configuration.

Background

Bloomreach Experience Manager's delivery framework (HST) supports authentication throughJAAS out-of-the-box. A standard implementation projectcreated using the Maven archetype is configured for form-based authentication over HTTPS using the default LoginModule implementation included in the HST. Unauthenticated users requesting a page for whichauthorization is required are automatically redirected to the login form.

This page describes the default authentication configuration and some options for customization.

Separate pages describe how to:

• Configure the Delivery Tier to Use Basic Authentication
• Customize the Delivery Tier Authentication Provider
• Customize the Delivery Tier's Form Login Pages

JAAS Login Configuration

Default Configuration

Bloomreach Experience Manager's delivery framework provides adefault JAAS login configuration file which configures the defaultLoginModule implementation org.hippoecm.hst.security.impl.DefaultLoginModule.

Configure a Custom Login Module

To configure a differentLoginModule implementation:

Place the LoginModule implementation class in the site webapp, e.g. site/src/main/java/org/example/MyLoginModule.java.

Configure theLoginModule implementation class in a JAAS login configuration file, e.g. conf/login.conf:

HSTSITE {   org.example.MyLoginModule required   debug="false"   storePrivCreds="true";};

Configure the location of the JAAS login configuration file in the cms webapp's hst-config.properties, i.e. cms/webapp/src/main/webapp/WEB-INF/hst-config.properties:

java.security.auth.login.config = file:/${catalina.base}/conf/login.conf

The authentication realm and valve are configured in the application context configuration in site/webapp/src/main/webapp/META-INF/context.xml:

<?xml version="1.0" encoding="UTF-8"?><Context crossContext="true">  <Realm className="org.apache.catalina.realm.JAASRealm"         appName="HSTSITE"         userClassNames="org.hippoecm.hst.security.TransientUser"         roleClassNames="org.hippoecm.hst.security.TransientRole"         useContextClassLoader="true"/>  <Valve className="org.apache.catalina.authenticator.FormAuthenticator" characterEncoding="UTF-8"/></Context>

The name of the realm must be the same asconfigured in web.xml. By default, the realm is configured to use form-based authentication using the FormAuthenticator valve. Alternatively, you mayConfigure the Delivery Tier to Use Basic Authentication.

Finally, make sure that login.conf ends up in the Tomcat conf directory.

For local development using cargo:run, in the project root pom.xml, add the following tobuild/plugins/plugin/configuration/configuration/configfiles:

<configfile>  <file>${project.basedir}/conf/login.conf</file>  <todir>conf/</todir>  <tofile>login.conf</tofile></configfile>

For deployment using a project distribition, add the following to src/main/assembly/conf-component.xml:

<file>  <source>conf/login.conf</source>  <outputDirectory>conf</outputDirectory>  <destName>login.conf</destName></file>

Servlet Configuration

The form-based authentication is enabled and processed by theLoginServlet configured in site/webapp/src/main/webapp/WEB-INF/web.xml:

<servlet>  <servlet-name>LoginServlet</servlet-name>  <servlet-class>org.hippoecm.hst.security.servlet.LoginServlet  </servlet-class></servlet>

<servlet-mapping>  <servlet-name>LoginServlet</servlet-name>  <url-pattern>/login/*</url-pattern></servlet-mapping>

<security-constraint>  <web-resource-collection>    <web-resource-name>Login</web-resource-name>    <url-pattern>/login/resource</url-pattern>  </web-resource-collection>  <auth-constraint>    <role-name>everybody</role-name>  </auth-constraint></security-constraint><login-config>  <auth-method>FORM</auth-method>  <realm-name>HSTSITE</realm-name>  <form-login-config>    <form-login-page>/login/login</form-login-page>    <form-error-page>/login/error</form-error-page>  </form-login-config></login-config><security-role>  <description>Default role of the repository</description>  <role-name>everybody</role-name></security-role>

The configurations above set a default protected web resource path (/login/resource), which is internally used by theLoginServlet, and form-based authentication with the internal login page path and error page path. Also, only for authentication purpose, the default role, "everybody", is required for the default protected web resource path (/login/resource).

Login Form Skin Resources

Default Configuration

The default login form needs access to some built-in skin resources such as CSS and images. These resources are served by theSecurityResourceServlet configured in site/webapp/src/main/webapp/WEB-INF/web.xml:

<servlet>  <servlet-name>SecurityResourceServlet</servlet-name>  <servlet-class>org.springframework.js.resource.ResourceServlet</servlet-class>  <init-param>    <param-name>jarPathPrefix</param-name>    <param-value>/META-INF/hst/security</param-value>  </init-param></servlet>

<servlet-mapping>  <servlet-name>SecurityResourceServlet</servlet-name>  <url-pattern>/login/hst/security/*</url-pattern></servlet-mapping>

Override Login Form CSS

For simple customization of the look and feel of the login form, itsdefault CSS can be overridden by creating a file src/main/resources/META-INF/hst/security/skin/screen.css in either thesite/components orsite/webapp module.

HTTPS vs HTTP Login

By default, all delivery framework login requests are overHTTPS. In a standard Cargo-based development environment, you have two options to use HTTPS:

• Configure Cargo for SSL/TLS
• Configure Apache HTTP Server as Reverse Proxy (also see Apache HTTP Server'sSSL/TLS andmod_ssl documentation).

Alternatively, you may configure login over HTTP instead (in local development environments only!), following the instructions below.

Using theConsole, browse to the default login sitemap item at /hst:hst/hst:configurations/hst:default/hst:sitemap/login.

Change the value of thehst:scheme property fromhttps tohttp.

/hst:hst/hst:configurations/hst:default/hst:sitemap:  /login:    jcr:primaryType: hst:sitemapitem    hst:scheme: http

Test the Login Form

Point your browser to /login/form. In a standard project running in a local development environment that would be http://localhost:8080/site/login/form.

Enter a CMS username and password to sign in. You will be able to get authenticated.

If you enter an incorrect username or password, you will be redirected to the default error page,/login/error.

In your delivery framework components, you can check if the current user is authenticated by calling HttpServletRequest#getUserPrincipal(). If the method returns a non-null value, then the user is authenticated!