Here’s the instructions I use whenever I need to remember how to set up basic server-side authentication on a Lucee server. These are really instructions for Apache Tomcat, which Lucee uses as its web server.
This is something I often do for development sites, but not production. It will allow your Lucee website to authenticate against a static file of users.
(If you are looking for a way to do this dynamically one option is to connect your website to Active Directory. This is how our production sites are configured and I’ve documented the process here.)
If you’re like me and migrating from Apache Webserver this process is similar to adding users to a password file using the htpasswd command.
First we will create an xml file with our user data. Store this outside of your web root! The format looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users xmlns="http://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
version="1.0">
<role rolename="canaccessMYAPP"/>
<user username="gaspard" password="abcd1234" roles="canaccessMYAPP"/>
</tomcat-users>
The userstore ends up being global within Tomcat, so I’ve made the security role specific to MYAPP. Later on you’ll see how I use this in the web.xml to control access to only MYAPP.
In our server.xml file, now we will tell Tomcat about our file with the user data by making an entry inside the <GlobalNamingResources> tag.
<GlobalNamingResources>
<Resource name="UserDatabase" auth="Container"
type="org.apache.catalina.UserDatabase"
description="User database that can be updated and saved"
factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
pathname="conf/tomcat-users.xml" />
<Resource name="MY_APP_UserDatabase" auth="Container"
type="org.apache.catalina.UserDatabase"
factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
pathname="C:\MY_APP-users.xml" />
</GlobalNamingResources>
(you can remove the default user store on lines 2-6)
Now that we’ve told Tomcat about our XML file with user data, let’s tell Tomcat that this file is available within the engine.
<Engine name="Catalina" defaultHost="127.0.0.1">
<!-- Use the LockOutRealm to prevent attempts to guess user passwords
via a brute-force attack -->
<Realm className="org.apache.catalina.realm.LockOutRealm">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
<Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="MY_APP_UserDatabase"/>
</Realm>
<Host name="MY_APP.test" appBase="webapps" unpackWARs="true" autoDeploy="true" >
<Context path="" docBase="C:\wwwroot\MY_APP\public_html\" />
<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="access_log" suffix=".txt" pattern="%h %l %u %t "%r" %s %b" />
</Host>
</Engine>
We’ve also defined our host within the <engine> area. You can read more about that here.
Now lets tell our website to authenticate against our list of users. In our web.xml we will add the following:
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
id="WebApp_ID" version="3.1">
<display-name>test</display-name>
<welcome-file-list>
<welcome-file>index.html</welcome-file>
<welcome-file>index.htm</welcome-file>
<welcome-file>index.cfm</welcome-file>
<welcome-file>default.html</welcome-file>
<welcome-file>default.htm</welcome-file>
<welcome-file>default.cfm</welcome-file>
</welcome-file-list>
<security-constraint>
<web-resource-collection>
<web-resource-name></web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>canaccessMYAPP</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<role-name>canaccessMYAPP</role-name>
</security-role>
<login-config>
<auth-method>BASIC</auth-method>
</login-config>
</web-app>
As I said at the start, I usually only use this for dev environments. But if you have multiple user files for multiple web apps on one server the user accounts are global. We don’t want the users from MYAPP #1 getting access to MYAPP #2. In the above example I am controlling access by stating that this website only allows users with “canaccessMYAPP”. If I had a second user database I would make a role for those users called “canaccessOTHERAPP” and configure that web.xml to only allow the users with that role to access.
Hope some of you find this useful!
