configuration guide - eoircace.eoir.com/configuration.pdf · 2.6 authentication ... password for...

CACE Configuration Guide | 1

Configuration Guide

Version 4.0

2/13/2017

This document is a guide on how to configure CACE for your installation environment.


Contents

Basic Post-Install Configuration .................................................................................................................... 3

1 Tomcat Configuration ....................................................................................................................... 3

1.1 Configuring a TGZ install ........................................................................................................... 3

1.2 Configuring Ports ...................................................................................................................... 3

1.3 Configuring Sandboxing ............................................................................................................ 4

1.4 Tomcat Database Configuration ............................................................................................... 4

1.5 Operating Behind a Proxy ......................................................................................................... 5

1.6 Authentication Configuration ................................................................................................... 5

2 JBoss/WildFly Configuration ............................................................................................................. 8

2.1 Configuring a TGZ install ........................................................................................................... 8

2.2 Configuring Ports ...................................................................................................................... 8

2.3 Configuring Sandboxing ............................................................................................................ 8

2.4 JBoss Database Configuration ................................................................................................... 9

2.5 Operating Behind a Proxy ....................................................................................................... 10

2.6 Authentication Configuration ................................................................................................. 10

3 Production Install Best Practices ......................................................................................................... 13

3.1 Server Configuration ................................................................................................................... 13

3.2 Post Install Cleanup ..................................................................................................................... 13


Basic Post-Install Configuration The configuration options in this section should be done after in install while the Web Server is stopped.

1 Tomcat Configuration Tomcat stores its configuration information in the conf folder. Catalina.properties stores user

configuration parameters while the xml files store server and webapp configurations. If installing CACE

from an RPM or DEB package, the tomcat configuration files should be preconfigured with the CACE

defaults.

Operating System Typical Conf Location

Ubuntu /etc/tomcat7

CentOS /usr/share/tomcat7/conf

1.1 Configuring a TGZ install

When installing from a tgz file, the server-config folder must be deployed to the correct tomcat

directories. The contents of tc-bin should be copied to tomcat/bin. The contents of tc-libs should be

copied to tomcat/lib. Finally, the contents of tc-conf should be copied to tomcat/conf.

1.2 Configuring Ports

Port information is configured in catalina.properties and the server.xml file. The server.xml file will use

the variables defined inside of catalina.properties:

Admin.port is usually safe to leave at 8005 (default) however it can be changed for security reasons. If

this port is changed the init.d script or management app will also need to be modified to use the correct

shutdown port.

Http.port is the default port tomcat will listen on for http traffic. For development purposes or when

operating behind a proxy port 8080 can be used (default). For production installs, this will most likely be

set to 80. Note: On Linux, Authbind or an equivalent will be needed to run on port 80 without root.

Https.port is the default port tomcat will listen on for https traffic. For development purposes or when


set to 443. Note: On Linux, Authbind or a similar system will be needed to run on port 443 without root.

Protocol is the default protocol for all traffic (the login page will always use https). To minimize load on

the server this can be left at the default http. For more secure installations, this value can be changed

to https. Note: Once set to https, HTTP Strict Transport Security (HSTS) will be enabled.


1.3 Configuring Sandboxing

In the catalina.properties file the following properties can be configured:

Valid.domains enables CACE application level sandboxing. When left blank (default) this will disable

sandboxing. When set to a whitespace separated list of domains this will limit web traffic to the limited

domains preventing malicious widgets from leaking sensitive data.

Websocket.domains can be used to specify additional domains that websockets will be allowed to

connect to. If valid.domains is left blank, this setting will have no effect. When set to a whitespace

separated list of domains this will block all websocket connections not in this list.

1.4 Tomcat Database Configuration

Inside of the context.xml file will be the default CACE database configuration.

If changing databases, replace @DATABASE_PLATFORM in the above image with either mysql or

postgresql (NOTE: this will already be done based on which package you downloaded).

Next open the server.xml file:

Each @parameter in the above image is a configurable setting. Below is a table indicating what each

parameter does and what their default values are.

Parameter Name Description Default Value

DATABASE_HOST The server that the database is running on

localhost

DATABASE_PORT The port the database is listening on

MySQL: 3306 PostgreSQL: 5432

DATABASE_NAME CACE database name impulse5

USERNAME Database username with permission to CACE database

impulse

PASSWORD Password for the above user csptech


1.5 Operating Behind a Proxy

In order to use CACE behind a proxy server, the proxy server must support WebSockets (RFC 6455).

NGINX 1.3.13+, Apache 2.4.5+ (using mod_proxy_wstunnel) and IIS 8+ (Using ARR 3.0+) all support

proxying of websocket traffic. Support from other proxies may vary. When using one of the compatible

proxy servers, be sure to forward websocket traffic in addition to standard http/https traffic if

necessary.

If installing CACE behind a proxy, the proxy’s IP address should be provided to CACE. In the

catalina.properties file, set the proxy.ip parameter to the IP address (not host name) of the proxy

server. When configuring the proxy server, ensure it utilizes the X-Forwarded-For header (most do by

default) to ensure all logging accurately reflects the clients IP address.

1.6 Authentication Configuration

CACE supports a number of security mechanisms including Database Authentication, LDAP, CAS,

Certificate Based Authentication and Proxy Authentication.

Database Authentication

CACE comes configured out of the box with a salted hash database authentication configuration. The

installation script will create a single user with the username admin and password admin. No additional

configuration should be needed if using this method.

LDAP Authentication

Lightweight Directory Access Protocol (LDAP) can be configured using the catalina.properties file:

These configuration settings can be obtained from your LDAP administrator. Once these settings are

correct, start your server keeping the original configuration cace.authentication.profile=database. Log

in as admin/admin and create an administrator user that will match up with a valid LDAP user. The

password for this user can be anything since the authentication will happen using LDAP credentials

instead. Give this new user administrator permissions then shut down the server.

Next, change catalina.properties again, setting:

cace.authentication.profile=ldap

Start up the server again and log in to the admin screen as the administrator user you just created. The

user list will now be populated from LDAP. You can now enable each LDAP user that requires access to

CACE and assign modules as necessary.


CAS Authentication

Central Authentication Service (CAS) can be configured using 3 properties in the catalina.properties file:

cace.cas.server.url=https://localhost:8443/cas cace.server.url=https://localhost:8443/impulse cace.authentication.profile=cas

Cace.cas.server.url is the full url to the CAS webapp. In the example above the CAS webapp is installed

on localhost (running https on port 8443) and is called cas.

Cace.server.url is the full url to the CACE webapp. This is used by cas to push authentication tickets back

to CACE.

Client Certificate Based Authentication

Client Certificates can be used via Standalone Distribution or Smart Cards (like CAC cards). To configure

CACE to use client certificates for login, start up the server in the default configuration and login to the

administrator screen as admin/admin. Create a new administrator user with the username of a valid

administrator user and a randomly generated password. Then shut down the server and make the

follow changes to server.xml:

Add the SSLCACertificate property to the https connector and point it to the CA certificate that signed

the client certificates. For certificate login only add the SSLVerifyClient property and set it to required.

For installs where a lack of a client certificate should fallback to a username/password based login, set

SSLVerifyClient to optional.

Finally change the following line in the catalina.properties file:

cace.authentication.profile=certificate

Start up the server and all users should now be able to login using client certificates.

Proxy Based Authentication

When proxy based authentication is enabled, the proxy server will handle authentication of the user and

pass the results to CACE. Before continuing, ensure all steps were followed in section 1.5.

Configuring a Proxy Server using Client Certificate Authentication

To enable certificate based authentication, following the instructions for your proxy server to setup the

certificate based authentication. Then set a header SSL_CLIENT_S_DN to be the DN of the client

certificate. Next, set a header SSL_CLIENT_VERIFY to SUCCESS if the certificate is valid. If the client

certificate is optional, these headers must be stripped for clients without a valid client certificate.

Finally, in the catalina.properties file set cace.authentication.profile=certificate and start the

server.


Configuring a Proxy Server using an Alternative Authentication Mechanism

If using an alternative authentication mechanism, ensure all users are authenticated before passing

through the proxy. Then add a header SSL_CLIENT_S_DN specifying the username of the authenticated

user with a CN= prefix. For example: SSL_CLIENT_S_DN: CN=user1. Next, set a header

SSL_CLIENT_VERIFY to SUCCESS. Finally, in the catalina.properties file set

cace.authentication.profile=certificate and start the server.


2 JBoss/WildFly Configuration JBoss stores its configuration in the %JBOSS_ROOT%/standalone/configuration folder. It consists of a

single standalone.xml file with multiple configuration beans. If installing CACE from an RPM or DEB

package, the JBoss configuration files should be preconfigured with the CACE defaults.

2.1 Configuring a TGZ install

When installing from a tgz file, the server-config folder must be deployed to the correct JBoss

directories. The contents of jb-config should be copied to jboss/standalone/configuration. The contents

of jb-modules should be copied to jboss/modules.

2.2 Configuring Ports

Port information is configured in the standalone.xml file:

Http.port is the default port tomcat will listen on for http traffic. For development purposes or when


set to 80. Note: On Linux, Authbind or an equivalent will be needed to run on port 80 without root.

Https.port is the default port tomcat will listen on for https traffic. For development purposes or when


set to 443. Note: On Linux, Authbind or a similar system will be needed to run on port 443 without root.

Protocol is the default protocol for all traffic (the login page will always use https). To minimize load on

the server this can be left at the default http. For more secure installations, this value can be changed

to https. Note: Once set to https, HTTP Strict Transport Security (HSTS) will be enabled.

2.3 Configuring Sandboxing

In the server.xml file the following properties can be configured:

Valid.domains enables CACE application level sandboxing. When left blank (default) this will disable

sandboxing. When set to a whitespace separated list of domains this will limit web traffic to the limited

domains preventing malicious widgets from leaking sensitive data.

Websocket.domains can be used to specify additional domains that websockets will be allowed to

connect to. If valid.domains is left blank, this setting will have no effect. When set to a whitespace

separated list of domains this will block all websocket connections not in this list.


2.4 JBoss Database Configuration

Inside of the standalone.xml file will be the default CACE database configuration.

If changing databases, replace @DATABASE_PLATFORM in the above image with either mysql or

postgresql (note: this will already be done based on which package you downloaded).

The next section of the file contains the database connection settings:

Each @parameter in the above image is a configurable setting. Below is a table indicating what each

parameter does and what their default values are.

Parameter Name Description Default Value

DATABASE_HOST The server that the database is running on

localhost

DATABASE_PORT The port the database is listening on

MySQL: 3306 PostgreSQL: 5432

DATABASE_NAME CACE database name impulse5

USERNAME Database username with permission to CACE database

impulse

PASSWORD Password for the above user csptech


2.5 Operating Behind a Proxy

In order to use CACE behind a proxy server, the proxy server must support WebSockets (RFC 6455).

NGINX 1.3.13+, Apache 2.4.5+ (using mod_proxy_wstunnel) and IIS 8+ (Using ARR 3.0+) all support

proxying of websocket traffic. Support from other proxies may vary. When using one of the compatible

proxy servers, be sure to forward websocket traffic in addition to standard http/https traffic if

necessary.

If installing CACE behind a proxy, the proxy’s IP address should be provided to CACE. In the

standalone.xml file, set the proxy.ip parameter to the IP address (not host name) of the proxy server.

When configuring the proxy server, ensure it utilizes the X-Forwarded-For header (most do by default)

to ensure all logging accurately reflects the clients IP address.

2.6 Authentication Configuration

CACE supports a number of security mechanisms including Database Authentication, LDAP, CAS,

Certificate Based Authentication and Proxy Authentication.

Database Authentication

CACE comes configured out of the box with a salted hash database authentication configuration. The

installation script will create a single user with the username admin and password admin. No additional

configuration should be needed if using this method.

LDAP Authentication

Lightweight Directory Access Protocol (LDAP) can be configured using the standalone.xml file:

These configuration settings can be obtained from your LDAP administrator. Once these settings are

correct, start your server keeping the original configuration <property

name=”cace.authentication.profile” value=”database” />. Log in as admin/admin and create an

administrator user that will match up with a valid LDAP user. The password for this user can be anything

since the authentication will happen using LDAP credentials instead. Give this new user administrator

permissions then shut down the server.

Next, change standalone.xml again, setting:

<property name=”cace.authentication.profile” value=”ldap” />

Start up the server again and log in to the admin screen as the administrator user you just created. The

user list will now be populated from LDAP. You can now enable each LDAP user that requires access to

CACE and assign modules as necessary.


CAS Authentication

Central Authentication Service (CAS) can be configured using 3 properties in the standalone.xml file:

Cace.cas.server.url is the full url to the CAS webapp. In the example above the CAS webapp is installed

on localhost (running https on port 8443) and is called cas.

Cace.server.url is the full url to the CACE webapp. This is used by cas to push authentication tickets back

to CACE.

Client Certificate Based Authentication

Client Certificates can be used via Standalone Distribution or Smart Cards (like CAC cards). To configure

CACE to use client certificates for login, start up the server in the default configuration and login to the

administrator screen as admin/admin. Create a new administrator user with the username of a valid

administrator user and a randomly generated password. Then shut down the server and make the

follow changes to standalone.xml:

Add the SSLCACertificate property to the ssl bean and point it to the CA certificate that signed the client

certificates. For certificate login only add the SSLVerifyClient property and set it to required. For installs

where a lack of a client certificate should fallback to a username/password based login, set

SSLVerifyClient to optional.

Finally change the following line in the standalone.xml file:

<property name=”cace.authentication.profile” value=”certificate” />

Start up the server and all users should now be able to login using client certificates.

Proxy Based Authentication

When proxy based authentication is enabled, the proxy server will handle authentication of the user and

pass the results to CACE. Before continuing, ensure all steps were followed in section 1.5.

Configuring a Proxy Server using Client Certificate Authent ication

To enable certificate based authentication, following the instructions for your proxy server to setup the

certificate based authentication. Then set a header SSL_CLIENT_S_DN to be the DN of the client

certificate. Next, set a header SSL_CLIENT_VERIFY to SUCCESS if the certificate is valid. If the client

certificate is optional, these headers must be stripped for clients without a valid client certificate.

Finally, in the standalone.xml file set <property name=”cace.authentication.profile” value=”certificate”

/> and start the server.


Configuring a Proxy Server using an Alternative Authentication Mechanism

If using an alternative authentication mechanism, ensure all users are authenticated before passing

through the proxy. Then add a header SSL_CLIENT_S_DN specifying the username of the authenticated

user with a CN= prefix. For example: SSL_CLIENT_S_DN: CN=user1. Next, set a header

SSL_CLIENT_VERIFY to SUCCESS. Finally, in the standalone.xml file set <property

name=”cace.authentication.profile” value=”certificate” /> and start the server.


3 Production Install Best Practices

3.1 Server Configuration We recommend configuring the Java VM arguments for the web server for best performance.

Depending on the server and operating system theses settings are usually found where init.d services

store their default settings.

-Xss228K -Xmx2048M -XX:MaxPermSize=512m

XMX is usually set to 2GB but will vary based on the available memory. When installing a database and

web server on the same machine set this value to 40% of the available physical RAM (ex: 3.2GB on an

8GB server). When installing just the web server (database on a separate machine), we recommend

setting this value to 75% of the available physical RAM (ex: 3GB on a 4GB server).

3.2 Post Install Cleanup After completing the installation and verifying everything is working correctly, cleanup of unneeded files

will limit security vulnerabilities and reduce future maintenance needs. We recommend removing the

following:

All Tomcat/JBoss log files generated during the configuration phase (this includes any errors

generated from misconfiguration or server starts/stops before everything was correctly setup).

Remove the webapps or uninstall the rpm/deb packages for the examples webapp, documentation

webapp and manager webapp.

Delete or disable the default admin user (admin/admin).

Configure all system firewalls following industry best practices. The only ports that need to be

externally accessible are the http port (tcp) and https port (tcp).

Replace the ROOT webapps index.html page with a redirect to CACE if necessary

configuration guide - eoircace.eoir.com/configuration.pdf · 2.6 authentication ... password for...

Documents