Secure Mercurial in GlassFish using SSL

A friend of mine, Wade Chandler, contacted me the other day to ask about implementing security (SSL) for Mercurial on GlassFish. Wade is NetBeans Dream Team member, and all-around great guy. I told him I would figure it out, and tell him how to do it. I also decided that I would explain to everyone how to take advantage of this cool functionality using GlassFish 3.1.1 and NetBeans 7.1 RC 2. 

In  a previous blog entry, Mercurial on GlassFish 2.1 Using Multiple Repositories, I successfully deployed Mercurial repositories on GlassFish. This time I have given everything a Java EE 6 upgrade.

One of the great aspects of using GlassFish to provide SSL is that we don't require messy configuration in Python and Mercurial to implement SSL. GlassFish handles the security for us. The only thing that the end client users will want to do is add the server fingerprint to the .hgrc file in their home directory. This will remove any warnings about a missing server fingerprint, or cacerts file.

If you have used Mercurial on Apache HTTPD Server, along with cacerts, and client certificates... this will make you make the switch immediately.

Requirements:

• GlassFish 3.1.1
• NetBeans 7.1 RC2 +
• Mercurial 1.9.3+
• Mercurial.zip (Required)
• repos.zip (Optional)

You can create your own web project in NetBeans, but the Mercurial.zip is a self-contained Mercurial repository, and NetBeans project which can serve as the basis for your own server with very little modification. I would simply use my project as the basis for your own deployment.

Note: The requirements include repos.zip which is optional. The repos.zip contains sample mercurial repos which are required for the demo.

Procedures

Configure GlassFish

1. Start the GlassFish administration console.
2. Go to Configuration → server-config → Security → Realms → file.
   Note: You may create your own realm, this is just for demonstration purposes.
3. Click on Manage Users.
   

   

   GlassFish Security Configuration

4. Click on New. Add a user called mercurial in a group called Mercurial Users with the password hg.
   Note: Please change the username, group, and password for production.
5. The server configuration is complete.

NetBeans

1. Using NetBeans open the Mercurial project from the requirements link above.
2. There are four files in the project (simple huh?) which control the behavior of the Mercurial repository on GlassFish: hgweb.cgi, hgweb.config, web.xml, and glassfish-web.xml.
3. The hgweb.cgi should not need to be modified under normal circumstances.
4. Open the hgweb.config file. Make any changes that you would like to customize the application. Pay particular attention to the location of the repositories.
   There are two examples: (1) using the "/" along with a * on the end of the file path will list all repositories in the specified directory, and (2) a specific listing.
   
   Note: Please note that allow_push = * and push_ssl = false are set. This will allow push to the server and let GlassFish take care of the SSL.
5. The web.xml file has been modified to add security constraints for the alpha, and beta example repositories.
   The alpha repository has security only on PUT, POST, and DELETE.
   The beta repository will not allow you to perform any actions without logging into the server.
   The gamma repository has no security constraints.
   
   Note: You will need to modify the security constraints to meet your requirements.
   
   Note: You secure the entire repository by adding:
   <url-pattern>/cgi-bin/hgweb.cgi/*</url-pattern>.
   
   
6. The glassfish-web.xml is used to map the security role(s) to the file realm on the GlassFish server.
   
7. Clean, build, and Run the application.
8. When the application successfully deploys, go to the secure connection on https://localhost:8181/Mercurial. It may prompt you to accept the server certificate. Accept it.
9. You should see something like the image below:
   

   

   Mercurial Repositories

10. Click on the beta repository. It should prompt you to login.
11. Congratulations you are running Mercurial on GlassFish securely.

Note: To secure the application completely, you should disable the non-secure http port listener on port 8080, or redirect requests to the secure port. 

Verification

It would be unwise to accept that the application is secure without verification.

I made this demonstration video to prove the connection is secure. The demonstration shows both insecure and secure connections to the repository. I use Wireshark to sniff the connection, and pull the repository from the command line using hg clone.

Conclusion

Mercurial is a great distributed source control system. Its ease of use is further enhanced by using GlassFish 3.1.1 to provide the front end to your repository. It also simplifies the deployment, and use models.