Recently, our team took on the job of creating a custom single sign-on solution for a client. They had already implemented a single-purpose solution, but it just didn't offer the benefits of a modern identity and access solution.

We spun up an Authentication Server with a bespoke identity/security API, which could be leveraged by any number of applications. Now came the challenging part – integrating the new platform into the existing, entirely-custom (and non-boilerplate) application.

Here are the top three lessons we have learned over the years, which will definitely help when it's time to integrate your application.

Lesson One: Create a Clear Picture of the End State

Having a clear picture of your end state is critical when it comes to any major technical project, especially in situations where you are retrofitting a solution. Does this mean that you must set forth to build a perfect specification right out of the gate? Definitely not. No "best practice" reference architecture will ever survive the battle of a complex integration.

It becomes increasingly important then, to uncover all we can about our legacy system to help shape the end state into its ideal form. Consider your vision to be a sculpture where you must use what you learn in order to carve away, until you can reveal the final work hidden underneath.

A good starting point is to use both automated and manual techniques to analyze the code base, forming a comprehensive view of the impact radius of the work to be performed. This view will pay dividends, informing the team on how to make the best decisions during integration. This not only saves huge amounts of time, but also enhances the accuracy of the desired end state.

Next, you'll want to find the dirty code. The code that would normally surprise you after you’ve already waded deep into the waters of execution. There are many places that some dirty code can be hiding – from the depths of the database ( ... stored procedures everywhere), to the largely-uncompiled world of the View. When it comes to large-team development, there is a solid chance that not everyone is going to be following strong software practices, let alone the same patterns established by the majority of the application.

In our case, it was all of the above and more. Make sure to search the database for errant security phrases (e.g., user, role), turn on compilation for your views, and examine the script files to uncover hard-to-trace checks. Be certain that assumptions aren't carried through multiple layers (e.g., user information in templates, base controllers or dependency injection bootstrappers). Being thorough in these spots can prevent a landmine in the system or even worse – opening access to non-privileged users.

Now, this all may seem obvious – a bit of planning goes a long way – but in matters of software development, this idea is often met with pitchforks, torches and a choir of villagers screaming in defense of their agile culture. But IAM integrations can ultimately touch every layer of an application, and an iterative, prototype-driven approach will introduce unnecessary risk to an already difficult project.

Lesson Two: Document

Here at Workstate, we are huge advocates of using wikis and other forms of documentation to capture everything learned along the way. What you capture now could save someone else many hours (if not days) in the future. Often, we face the same challenges over and over, and I've often referenced documentation I've created to save myself (and the client) a ton of time and cost.

For this particular integration, we had several developers working together, each attacking various aspects of the project. By bringing everything home in a wiki and a collaboration tool like Slack, we prevented a lot of rework and painful rediscovery.

What kinds of things do we document? Here are a few examples:

• Configuration for various environments
• Architecture decisions, or non-obvious implementation details
• Troubleshooting common issues (SSL certs, web server ninjutsu, cookie overload)
• Repositories where you can find unique solutions
• Helpful scripts to automate routine tasks

Beyond simply documenting, make sure you have a good taxonomy so that others can easily find this information in the future. Tags are your friend; and making your information discoverable can mean the difference between a huge time-saver and a waste of time.

A good rule of thumb is to dedicate at least 5% of your time to creating content that describes the activities performed each week. That represents only a fraction of the time it will save over the course of multiple projects. Some of this work can even lend itself to blogs or other public content, which will benefit many others that happen upon it.

Lesson Three: Pay Off Some Technical Debts

As your planning phase undoubtedly will reinforce, most custom applications accumulate technical debt over the years. Whether it's quick-turnaround bug fixes that didn't quite follow the architecture, or just the byproduct of an aging system capitalizing on new technologies; you're certain to have debt. Let your integration be a good time to examine some of this debt and figure out what can be eliminated through an already invasive process.

To make it simple: Just because your old solution used three different ways to authorize access doesn't mean your new integration should, too.

Here are a few common pieces of technical debt we find during these integrations:

• Methods that circumvent the security architecture
• Multiple different ways to determine access to privileged data or features
• Unsecured API or Webservice endpoints
• Cookie management
• Obsolete, incomplete, or failing unit tests

If you've been considering an IAM platform, chances are that you're already juggling multiple applications that have their own individual logins, identity sources and security. The process of ripping thousands of lines of custom code and dropping in a fully functioning IAM solution probably seems challenging, if not insurmountable.

With our years of experience, Workstate is here to help make your integration smooth, and a lot less daunting. Get in touch with us today to learn more about reducing the headaches of a new IAM implementation.