Hide upstream identity providers with the Auth Facade

How can the auth facade pattern help you deploy apps in customer's networks?


Published: January 27, 2021

During conversations with FusionAuth customers, I have seen a common deployment pattern I call the “Auth Facade”. This architecture is useful when deploying software to heterogeneous environments. You and your team are building an application which will deploy onsite. This could be into a data center, an isolated network, or a private cloud. These environments are run by your customers and you have limited insight into their configuration.

You might choose this deployment model for a variety of reasons:

  • Data gravity, when your application needs to go to the data because there’s so much that the data isn’t coming to you for cost or performance reasons.
  • Security of confidential data; the customer needs to have the data remain in their hands.
  • Intermittent or lossy connectivity to the internet due to the location of the deployment.

All of these stem from customer demand; you meet your customers where they are. Your production deployment environment is out of your control. This situation was common before the rise of “software as a service”, and its complexities led to the proliferation of SaaS. But for these environments, typical SaaS solutions, whether for monitoring, auth or analytics won’t work.

At the same time, your enterprise customer doesn’t want Yet Another User Database to maintain. Instead the stakeholders want your application to authenticate users against an existing datastore. This may be Azure Active Directory/Microsoft Entra ID, Okta, or another identity provider. This identity provider is run by your customer’s employees and may support OIDC or SAML.

However, you want to ensure that your developers focus on building and extending your application, not building auth integrations. You especially want to avoid debugging authentication in prod environments you don’t control.

Finally, your application has needs around user data as well. Whether that is role based authorization, auditing access or displaying a “Welcome” message, your application will need to access and modify user data.

Options for handling upstream auth

As an enterprise software developer, you have a couple of options to solve this problem:

  • Test and document how your application can be configured to use an upstream provider. This is a roll your own solution and requires knowledge of your customers deployment environments. You’ll want to provide and test configuration options for all the major providers.
  • Code to the OIDC and SAML specs, since most enterprise providers support these. You will limit your user data needs to what these provide. This is the pure federation option.
  • Use an auth facade.

Like any facade, the auth facade hides a subsystem. In this case, the subsystem is your client’s identity provider. When using this pattern, as part of your application you ship an embedded auth and user management system. All auth functionality is routed through this; it is configured to communicate with upstream authentication providers.

A common architectural pattern..

The auth facade vs federation

The auth facade provides more than just authentication and authorization federation, though. Federation is a good start, but sometimes you need more functionality, support and documentation than standards provide.

When you use an auth facade, you get the following:

  • A single interface for your developers to access and manage user data
  • An easy, deployable, compact auth system which runs everywhere
  • A rich set of APIs and data models
  • Ample documentation for various upstream providers

Let’s talk a bit more about each of these.

Developer interface

Your developers need some kind of auth system in order to know which users can access the application, as well as what particular functionality is available to a user. By using the auth facade, your devs learn how to integrate with only one system, rather than every system your clients may require you to work with. This makes development easier and also frees up engineering focus for the features of your application.

Additionally, when there are bugs in the auth system, there are two common locations:

  • Between your application and the facade
  • Between the auth facade system and the upstream provider

In the former case, you have everything you need to debug what is causing an issue for your customer. In the latter, you’ll be leveraging the troubleshooting and bug fixing expertise of the maintainers of the auth facade system. In either case, separating the concerns makes it easier to track down issues.

You’ll want a responsive team behind the auth facade system when issues arise. You don’t want to keep your customers waiting for a fix.

Deployable auth system

When evaluating auth facade solutions, make sure you can deploy the system providing the facade into a variety of customer environments. This rules out any typical SaaS solutions, unless the SaaS provider deploys into their network. Being able to support air gapped or isolated networks can be a strong differentiator for your application, especially if it accesses sensitive data.

Ensure your application and the auth facade system are deployable using the same technologies. Doing so decreases installation complexity. Depending on customers’ needs, you may want to deploy in a unix friendly package such as an RPM or DEB, a generic software package like a zip file, or, for the cutting edge clients using kubernetes, a container solution such as Docker.

Since auth is a necessary part of your application, but not a differentiator, an auth system that fades into the background is best. This should happen both in the literal sense, with a user interface that isn’t recognizable as separate from your application, and the figurative sense, where your engineers minimize time spent worrying about it or maintaining it.

You also want a friendly license for embedding the auth system into your code. I am not a lawyer, but make sure you understand the licensing ramifications of any third party applications or libraries you ship hand in hand with your app. Some open source projects offer dual licensing, which may be a viable option.

APIs and data model

If you can get by with the lowest common denominator of authentication and authorization information, strictly follow the OIDC and SAML standards and you’ll be happy.

But often the application you are building will need more information about a user than these standards can provide. You may want to store custom domain specific attributes useful to your application, for example.

Any auth facade solution must provide a superior data model when compared to the standards in order to be worthwhile to implement. If it doesn’t, just use the standards to interface with the upstream provider.


As I talked to customers, they pointed out the benefits of documentation, which was surprising to me. While documentation is often useful, why is it so important for an auth facade?

Documentation lets you offload configuration of the connection between the auth facade and the upstream systems to people who know and maintain those upstream systems. These employees of your clients won’t be familiar with your application.

In fact, they may resent the additional work that your application’s installation requires of them. Making the configuration of the auth facade well documented and as simple as possible will make it easier to get your application working in your customer’s environment.

You therefore have two choices:

  • Maintain such documentation yourself
  • Rely on the auth facade provider to create and offer great docs

Guess which one is easier for your engineering team?

How can you implement the auth facade with FusionAuth

FusionAuth is a great choice for an auth facade. It runs anywhere, integrates with both SAML and OIDC as well as other upstream providers, provides a single, rich interface for your developers, and is well documented.

To begin implementing the auth facade with FusionAuth, review the FusionAuth Identity Provider and Connector documentation to make sure that your client’s identity providers are supported. Contact us if they aren’t; we’d love to learn more. You can also read case studies of customers using FusionAuth in this fashion, such as this one from Unsupervised (PDF).

If you think FusionAuth fits your needs, download FusionAuth, kick the tires and build a proof of concept.

If you are interested in packaging it as part of your application, please contact us to discuss a resellers agreement.

More on authentication

Why Passkeys Matter

24 billion. That's how many passwords hackers exposed in a single year. That's a staggering enough figure, and even more sobering when you realize that it gets...

Subscribe to The FusionAuth Newsletter

A newsletter for developers covering techniques, technical guides, and the latest product innovations coming from FusionAuth.

Just dev stuff. No junk.