gitblit: Apache as frontend for x509 client authentication

It took us a long journey to finally come to the point where we decided to add a git repository server to our existing subversion source control infrastructure. The journey was quite long mostly due to the fact that both the development and management tools for git were just not good enough – at least not for us.
gitblit_raw
Luckily, the situation has improved a lot and so we decided to give gitblit [1] a try, a more or less universal management tool for git:

Gitblit is an open-source, pure Java stack for managing, viewing, and serving Git repositories.
It’s designed primarily as a tool for small workgroups who want to host centralized repositories.

It not only offers a truely rich feature set, like very fine grained access control to the repositories or groovy scripting for various hooks, but also comes with a web-, desktop and CLI interface and even has built in metrics reporting and many more things that we hope will make our life much easier 🙂

So, in our case we needed to integrate gitblit into our existing infrastructure, where Apache is facing the internet and authenticates users based on their x509 client certificates, redirecting towards internal services, such as gitblit running on a tomcat8 instance:

apache2gitblit

As you see, we are using mod_proxy_ajp to connect Apache and tomcat, as an alternative, mod_jk would work as well.

Before we start, let’s make some assumptions:

  • apache >= 2.2 with mod_proxy_ajp and mod_ssl enabled
  • tomcat >= 6.x
  • gitblit >= 1.6.x deployed on tomcat and basically running

To have apache require a valid x509 certificate for the https://apache.example.com/gitblit URL, you need the following configuration inside your >VirtualHost< definition for apache.example.com:

After restarting apache, the next piece is tomcat, that needs to get its AJP connector enabled and, very important, be told to honour the remote user already defined by apache. To do so, edit your tomcat’s server.xml and add the following line within the >Server< section:

<Connector port="8009" protocol="AJP/1.3" 
 redirectPort="8443" 
 tomcatAuthentication="false"/>

Restart tomcat.

And finally, you have to decide if you want gitblit to automagically create users on the fly as they appear. That is controlled by a setting in the gitblit.properties file (the location depends on where you told gitblit to create your git repositories, see WAR Data Location in the gitblit documentation.

If you want to automagically create users on the fly,

realm.container.autoCreateAccounts = true

The rationale behind auto creation is, that Apache will only let people with fitting certificates pass, so it is only logic to add them as users. gitblit assigns role=”#none” for those automatically created new users and it is up to an admin, to give those users the rights and roles as desired.

All this is controlled by the users.conf file, that resides at the same place as the gitblit.properties file from above.

An entry in users.conf for such an auto created user looks like this:

[user "homer.simpson@example.com"]
    password = "#externalAccount"
    displayName = homer.simpson@example.com
    accountType = CONTAINER
    emailMeOnMyTicketChanges = true
    role = "#none"

If you want to upgrade such an user to an admin, change role = “#none” to role = “#admin” and you are done.

For further information, what you can put in users.conf can be found in the Administering Users section of the gitblit documentation.

If you have reached that point, you should be able to completely administrate gitblit using apache controlled x509 client certificates, and the rest is up to you!

Happy hacking!

[1] http://gitblit.com/

Spread the love

Leave a Reply

Be the First to Comment!

avatar
  Subscribe  
Notify of

Post Navigation