Reducing user management headaches with new Active Directory integration

For the New Zealand Government Common Web Platform we needed a way for government agencies to authenticate users with their existing on-premises directory. For SilverStripe Platform we needed a way of managing a large number of users and their access rights to sites that make up the platform, such as Gitlab for code hosting, and Deploynaut to deploy that code. Users that are authorised on the platform need to login to all of them, but users may have different access rights than others. Senior Platform Developer Sean Harvey explains our recent work to integrate SilverStripe with Active Directory and some of the technical challenges that arose. 

So what is a directory? It's basically a database but has a bunch more features, mostly around user account data. Technically, it can hold pretty much anything but is most commonly used for managing user accounts in a computer network.

The idea of a directory is not new and has been around since the late 80s. Nowadays, a popular (and common) implementation of a directory is Microsoft's Active Directory, which heavily integrates into Windows, but can be used in other environments.

And what do we do with the directory? You have your sites talk to the directory in the LDAP protocol, so users authenticate on these sites using their directory account. The user only has to remember one set of credentials, rather than carry around that keyring full of keys.

What we did

For getting your SilverStripe integrated with a directory, we built the silverstripe-activedirectory module. It currently only works with Active Directory, but you can use Samba instead if you don't like Windows, or if you're using AWS (Amazon Web Services) there's Simple AD that gives you an Amazon managed Samba based directory in a few clicks, so you don't have to set it up yourself.

The module's development was funded by the Common Web Platform to be used on that platform, and the module was built in a generic way and released open source for anyone to use. The code is available now on Github, so check it out if you're interested, but first keep reading for the challenges that lie ahead.

Challenges

Everything sounds fantastic so far right? Check out these challenges we faced:

Documentation and jargon

Take a look at the developer documentation and you'll see what I mean. There's an alarming amount of acronyms and technical terms to get your head around. The documentation for that module has already been through a couple of rewrites in an attempt to provide clarity on how to configure it.

Check out this list of attributes for a user in Active Directory. Fortunately directories are slow moving and most of them haven't changed in decades.

Windows single sign-on integration

The module we wrote supports single sign-on using SAML, so users on a Windows network can authenticate with sites and applications using their logged in computer credentials without having to re-enter them again. That's a large sub-topic I won't go into for now, but needless to say it's not easy to get it working. There's a lot of "auto-magic" involved here that can be frustrating, and there are a lot of grey areas of responsibility between the web developer implementing the authentication and the administrators of the Windows network.

Maintaining the directory

Should the directory be on multiple servers for performance? Should it have redundancy so it’s available when one of the servers goes down? Do you want to look after it yourself and become an expert in all things directory? These are some non-functional requirements to ask yourself if you're considering deploying a directory yourself. One compromise in this case might be to use Simple AD, where the directory is managed for you.

Integration

This one should not be understated by any means.

There are a number of things that need to be considered for integration. For one, the communication between servers should be secure, so that means setting everything up with SSL, which means valid certificates installed. That goes for all your sites who should talk to the directory, as well as the directory itself.

There's also the most difficult part, which is the job of integrating your site with an existing directory that you don't control. It's most definitely going to be in a locked down environment with no external access, in which case you'll probably need a VPN (Virtual Private Network) to access it. This slows down the process of getting the job done substantially, as you have to deal with firewalls and network routing that is not trivial. Often you'll use a "fake" directory server locally for testing before deploying your work to production, but unexpected bugs can occur due to differences in the environment.

To summarise

There are a number of benefits using a directory, such as maintainability, usability, and security. Administrators can manage the users in a central place, users only have to remember one set of login credentials, and their passwords don’t need to be stored in the site databases.

However, it should not be underestimated how much time investment you'll need to put in to get it working, especially when it comes to integrating an existing directory you don't control. That said, it's still worth considering especially if you have multiple sites and want to remove the burden of managing individual user accounts across them.

I shall leave you on a slightly humorous note: Microsoft seemed to have a bit of a sense of humour when they added the drink attribute to Active Directory. I don't know if they were serious or not, but at least you can figure out people's drink of choice on Friday!