Maven Tomcat Plugin: Adding Authentication to an Embedded Tomcat

October 12th, 2011 by

The Tomcat Maven Plugin not only allows us to deploy our mavenized application to an existing Tomcat server but also to run our web application with an embedded instance from our project’s directory. Recently I needed to add basic authentication to such an instance and wanted to share the steps necessary here



We just need Maven and a JDK …

Project Setup

  • I am using the webapp archetype here
  • We’re adding the following configuration for the Tomcat plugin to your pom.xml – my final descriptor is this one
    <project xmlns="" xmlns:xsi=""
     <name>Maven Embedded Tomcat Basic Auth Sample</name>
  • The path node configures the context path for the web application – if we don’t specify it, the artifactId is used

Adding Authentication

Now that we’ve got a mavenized project we need to configure our web application …

  • First we’re going to edit our src/main/webapp/WEB-INF/web.xml – we’re adding a security constraint that is applied for all requests to a path that matches “/secure” and permit access to users that match the role ‘admin‘. The role is also defined here. My web.xml looks like this
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app version="2.4" xmlns="" xmlns:xsi="" xsi:schemaLocation="">
     <realm-name> Secured Area</realm-name>
  • Now we need a valid user that fulfils the defined role ‘admin‘ and some credentials for his authentication. In a normal Tomcat server we could add a user to the tomcat-users.xml but here we have an embedded instance – but this is no problem .. the Tomcat Maven Plugin searches for a directory src/main/tomcatconf and if it exists it is copied to the configuration of the embedded instance.
  • So we’re creating a new directory src/main/tomcatconf and adding a file named tomcat-users.xml with the following content
    <?xml version="1.0" encoding="UTF-8"?>
     <user name="admin" password="admin" roles="admin" />
  • As you can see we’re going to have a user “admin” with password “admin” and role “admin” .. very imaginative :)

Adding Content

Now that everything is secured we’re in need for some content to display and proof the correctness of our configuration …

  • First we’re creating a simple JSP that displays a text and a link to the secured JSP (that is created in the next step). This JSP is also used as welcome file – so we’re creating a file named test.jsp in src/main/webapp
    <h1>This is a test page</h1>
    <a href="/tcembed/secure/info.jsp">To the restricted area</a>
  • Now our secured JSP named info.jsp to be saved in src/main/webapp/secure
    <h1>This is some sensitive information</h1>

Run the Application

Now it’s time to test the application

  • Run the web application using the Tomcat Maven Plugin by running
    mvn tomcat:run
  • You should see some output in your console – this also gives you a hint what the URL to your application looks like
    [INFO] Running war on http://localhost:8080/tcembed
  • Now open the following address in your browser: http://localhost:8080/tcembed/ you should be able to see the following screen

    Accessing the unsecured JSP in the browser

    Accessing the unsecured JSP in the browser

  • Now click on the link – you should see the following prompt

    Basic Authentication: The login prompt to access the restricted JSP

    Basic Authentication: The login prompt to access the restricted JSP

  • Enter admin and admin and you should be able to see the secured JSP

    Viewing the secured JSP in the browser

    Viewing the secured JSP in the browser

Tutorial Sources

I have put the source from this tutorial on my Bitbucket repository – download it there or check it out using Mercurial:

hg clone


Tags: , , , , ,

2 Responses to “Maven Tomcat Plugin: Adding Authentication to an Embedded Tomcat”

  1. jack Says:

    I am not sure if it is a bug, but here is what i noticed.
    first time i ran the application, secure info page asked for the userid and pwd which is perfect.
    I restrated the server, the secure info did not ask for the userid and pwd .
    are these credentials it cached somewhere ?

  2. micha kops Says:

    This is not a bug .. using basic auth, the credentials are saved in your browser until you close and restart your browser or clear your history.