August 29, 2018

Adding PWM, a Free Password Reset Tool, to a Windows Network

by Grant Hamono

People asking you to reset their passwords all the time?

Would it lighten your workload to have them reset it themselves with a web-based interface?

Trying to implement a better password policy to break your users out of bad practices?

Well, there’s a Microsoft service that can handle this for you. But there are license costs. And it turns out that it’s actually not even as good as the open source alternative: PWM. This is a very powerful, self-service password reset tool that integrates with your existing MS Active Directory infrastructure using LDAP.

This guide will show you how to configure PWM start to finish with SSL cert installation and MYSQL database setup included.

I will be using Ubuntu Server 16.04 for this guide. I have tried with 18.04 but with varying degrees of success. It seems that 18.04, at the time of writing this article, has some compatibility issues with some of the packages that get installed in the process.

The official installation instructions are actually pretty good – even a Windows guy like me could figure out most of it. But I got stuck a bit trying to configure the SSL certificates and configuring PWM to use a remote database. Having taken the effort to figure these bits out, I wanted to share what I’d done to make it easier for the next guy 🙂

Running Linux as a Virtual Machine

Because PWM runs on Linux, we’ll need to install it onto a virtual machine. This guide assumes you are already using and are familiar with some flavour of virtual machine software.

Virtual machine technology is ubiquitous enough in modern client/server networks that you are almost certainly running it already, even if you’re not familiar with it. If that’s you, try to find out which virtual machine software is installed on your network and look up some introductory tutorials for it.

Other Things to Get Ready

Before we start you should download some tools that will help you immensely in the process, especially if you’re more comfortable with a windows GUI than a command line interface.

You will also want to install PUTTY; Putty allows you to have SSH access to your virtual machine that will make cutting and pasting code from this guide into the command line a breeze.

WINSCP is a great tool for copying files between your windows machine and the Ubuntu server we will be setting up.

Finally you might want to download notepad++ especially if you are uncomfortable with using linux text editors, like nano or VI.

Let’s get this show on the road!

Initial Server configuration

Create a virtual machine with Ubuntu Server 16.04 installed and running, then follow these steps:

  • Apply updates to Ubuntu
    sudo apt update 
    sudo apt upgrade
  • Install SSH so that you can use Putty to manage your VM
    sudo apt install ssh
  • Set a static IP address
    sudo nano /etc/network/interfaces
    • Edit the primary network interface, substituting your own network details
      # This file describes the network interfaces available on your system
      # and how to activate them. For more information, see interfaces(5).
      source /etc/network/interfaces.d/*
      # The loopback network interface
      auto lo
      iface lo inet loopback
      # The primary network interface
      auto eth0
      iface eth0 inet static
  • Press Ctrl+O to save and Ctrl+X to exit
  • Restart the networking service
    sudo service networking restart

Install and configure packages

  • Open putty and connect to your VM using the IP address you configured.
  • Install Apache, PHP & Tomcat.
    sudo apt install apache2
    sudo apt install php libapache2-mod-php
    sudo apt install tomcat8 tomcat8-docs tomcat8-examples tomcat8-admin
  • Edit the tomcat-users.xml file to configure a tomcat user and roles that will allow you to install PWM later on.
    sudo nano /etc/tomcat8/tomcat-users.xml
    • Full contents of tomcat-users.xml below. Green text is the altered text. Change values for username and password to wherever you like.
      <?xml version='1.0' encoding='utf-8'?>
        Licensed to the Apache Software Foundation (ASF) under one or more
        contributor license agreements.  See the NOTICE file distributed with
        this work for additional information regarding copyright ownership.
        The ASF licenses this file to You under the Apache License, Version 2.0
        (the "License"); you may not use this file except in compliance with
        the License.  You may obtain a copy of the License at
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
      <tomcat-users xmlns=""
                    xsi:schemaLocation=" tomcat-users.xsd"
        NOTE:  By default, no user is included in the "manager-gui" role required
        to operate the "/manager/html" web application.  If you wish to use this app,
        you must define such a user - the username and password are arbitrary.
        NOTE:  The sample user and role entries below are wrapped in a comment
        and thus are ignored when reading this file. Do not forget to remove
        <!.. ..> that surrounds them.
        <role rolename="tomcat"/>
        <role rolename="role1"/>
        <user username="tomcat" password="tomcat" roles="tomcat"/>
        <user username="both" password="tomcat" roles="tomcat,role1"/>
        <user username="role1" password="tomcat" roles="role1"/>
      <role rolename="manager-gui"/>
      <role rolename="admin-gui"/>
      <role rolename="manager-script"/>
      <user username="username" password="password" roles="manager-gui,admin-gui,manager-script"/>
  • Restart the Tomcat service
    sudo service tomcat8 restart
  • If tomcat is slow to start up you can install haveged entropy gathering daemon to speed it up
    sudo apt install haveged
  • Go to scroll to the bottom and select the latest version of pwm (“pwm-1.8.0-SNAPSHOT.war” at the time of writing this guide).
  • Rename “pwm-1.8.0-SNAPSHOT.war” to “pwm.war”
  • Browse to http://yourserverIP-OR-DNSname:8080/manager/. You will be prompted to log in using the credentials you configured in tomcat-users.xml
  • Under the “WAR file to deploy” section, click the “Choose File” button, and locate the pwm.war file. With the file selected, click the “Deploy” button.
  • Create the pwm configuration folder and set tomcat as the owner
    sudo mkdir /media/pwm/
    sudo chown tomcat8 /media/pwm/
  • Tell pwm where to look for its configuration directory
    sudo nano /var/lib/tomcat8/webapps/pwm/WEB-INF/web.xml
    • locate the <param-value> tags, and replace “unspecified” with “/media/pwm”
        <display-name>PWM Password Management</display-name>
          <!-- <distributable/> Clustering/Session replication is not supported -->
          <description>Password Management Servlet</description>
                  Explicit location of application path working directory or the literal value "/media/pwm/".  See the environment documentation at /public/reference/environment.jsp for more information.
  • Restart Tomcat
    sudo service tomcat8 restart
  • At this point pwm is installed and ready to be configured for a test environment. It will be able to use its own internal database for storing secret questions and user data. If you want to test it out now you can browse to to http://yourserverIP-OR-DNSname:8080/pwm. However, we are going to continue on and configure this server for production.

Install and configure MySQL

  • Next we will install MySQL to be used instead of the pwm internal database. The MySQL database can be installed on the same VM as pwm or on a separate server. The process will be the same no matter which option you chose.
  • Install MySQL
    sudo apt install mysql-server
  • run the secure installation script and accept all defaults for optimal security.
  • Run MySQL (you may have to complete this from the Virtual Machine instead of Putty depending on if you allow SSH root access in the previous step)
    mysql -u root –p
  • Create the DB, add a user & assign privileges (replace “password” with your own password). Single quotes and semi-colons must be included.
    CREATE USER 'pwm'@'localhost' IDENTIFIED BY 'password';
    GRANT ALL PRIVILEGES ON pwm.* TO 'pwm'@'localhost';

Install an SSL Cert and configure the Tomcat https Connector

  • The last thing we will do before the final configuration of pwm is to install an SSL certificate so that you can publish the tool on your intranet and staff can’t configure their own secret question answers and start re-setting and changing their own passwords. For this example we will be using a free SSL certificate from but the same process can be used for whatever provider you choose.
  • When you receive your certificate from SSL For Free, unzip the contents and use WINSCP to place them into your home directory on your Ubuntu server (found at /home/yourusername/). There should be three file ins your zip from SSL For Free; “ca_bundle.crt”, “certificate.crt” and “private.key”.
  • Install apr
    sudo apt install libapr1 libtcnative-1 libapr1-dev
    sudo ln -sv /usr/lib/x86_64-linux-gnu/ /usr/lib/
  • Create a folder to store your certs and move them there
    sudo mkdir /usr/local/ssl
    sudo mv ca_bundle.crt /usr/local/ssl/
    sudo mv certificate.crt /usr/local/ssl/
    sudo mv private.key /usr/local/ssl/
  • Create an HTTPS connector for tomcat and point it to your SSL files
    sudo nano /etc/tomcat8/server.xml
    • Locate the following section in the file
    • Comment out the http connector
    • Add the green text below
    • Save and close server.xml
          <!-- A "Connector" represents an endpoint by which requests are received
               and responses are returned. Documentation at :
               Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
               Java AJP  Connector: /docs/config/ajp.html
               APR (HTTP/AJP) Connector: /docs/apr.html
               Define a non-SSL/TLS HTTP/1.1 Connector on port 8080
          <!-- HTTP connector. Uncomment to enable
               <Connector port="8080" protocol="HTTP/1.1"
                redirectPort="8443" />
      <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
             port="8443" maxThreads="200"
             scheme="https" secure="true" SSLEnabled="true"
             SSLVerifyClient="optional" SSLProtocol="TLSv1+TLSv1.1+TLSv1.2"/>
          <!-- A "Connector" using the shared thread pool-->
          <Connector executor="tomcatThreadPool"
                     port="8080" protocol="HTTP/1.1"
                     redirectPort="8443" />
  • Restart tomcat
    sudo service tomcat8 restart
  • Browse to https://yourserverIP/DomainName:8443/pwm and begin the PWM setup procedure. Use the following when connecting to the MySQL database:

And that’s it! Start to finish! I’ve found that it’s a good idea to print off a QR code linking to your pwm server around the office with a title like “Forgotten your password?” then staff can simply use their phone to answer their secret questions and reset their own passwords instead of hassling you!

Need Us to do this for You?

We’re available for hire across the Melbourne metropolitan area, or remotely via the internet. To get in touch, please contact us via our server installation and configuration page.