Multi-tenant architecture for SaaS apps

Rabia Williams

• Do you distribute the same app to multiple clients/tenants?
• Are you looking to offer Software as a service and need to dig deep into the architecture of apps to work in multiple tenants?
• Are you tired of installing your app multiple times at these different clients/tenants?
• Do you want to push updates like features and bug fixes into the app without any involvement of client’s IT admins?

Then you need to know about multi-tenancy and how you can create a multi-tenant app in Microsoft 365.

In this post, we will convert a simple single tenant JavaScript application into a multi-tenant app that can run across different tenants to bring data into the app. Same app, different data.

Check out our YouTube video for more guidance, live coding, and commentary 👇

Let’s first learn about single tenant apps. A single tenant app is registered and used in a single tenant (single instance). Here is the source code of a sample single tenant application that retrieves data from Microsoft 365 using Microsoft Graph: https://github.com/MicrosoftDocs/mslearn-retrieve-m365-data-with-msgraph-quickstart.

In the source code’s README file, you can see that you’ll need to Register a new application in the Azure Portal. If you want to distribute, you’ll need to repeatedly register this app in each tenant to consume its services.

So, what if you want to register once and use your app in multiple tenants? That’s what multi-tenant apps are for!

Registering an app should not be confused with hosting. Hosting is where your app lives, which can be done anywhere. Registering your app is capturing it in the Microsoft identity platform, which can be done by registering the app in Azure AD to consume Microsoft 365 services securely.

Multi-tenant apps

Applications that are registered only in a home tenant but used in home as well as in other tenants are called multi-tenant apps (multiple instances of the same app). Deploy once, use wherever. The app code remains the same, but the data will be different based on the tenant they are running in.

Convert a single tenant app to a multi-tenant app

Let’s now go back to the sample app https://github.com/MicrosoftDocs/mslearn-retrieve-m365-data-with-msgraph-quickstart which displays the name of a currently logged-in user using Microsoft Graph.

Register the app in AAD as specified in the instructions in the above project’s README file   but under Supported account types, choose Accounts in any organizational directory (Any Azure AD directory – Multitenant).

In this app solution, open the auth.js file. You can see the MSAL configuration of this app. Read more about MSAL which is the authentication library used to acquire tokens from Microsoft Identity platform in-order to safely and securely authenticated users and access API services like Microsoft Graph. The config without any changes would look like below:

const msalConfig = {    auth: {        clientId: '<your client ID here>',              
authority: 'https://login.microsoftonline.com/<your directory ID here>',       
redirectUri: 'http://localhost:8080'    }};

Directory ID is the same as tenant ID.

Change it to:

const msalConfig = {    auth: {        clientId: '<your client ID here>',              
authority: 'https://login.microsoftonline.com/common',       
redirectUri: 'http://localhost:8080'    }};

(You replaced your directory ID with common)

And that’s the code change really! Your app should now be a multi-tenant app. When you run the app on the browser, no matter which tenant you log into, the app will ask you to consent to permissions, and once consented positively will retrieve data from Microsoft 365 using Microsoft Graph without any knowledge of what tenant’s data it is accessing.

What happens behind the scenes?

When the app is registered under App registrations in AAD of the home tenant, an instance of the app is created called a Service principal, which is the global instance of the app object.

These service principals or instances are created in all the tenants where the app is used. This enables the application to access services after authenticating the users successfully.

When the app is accessed by client tenant’s users for the very first time, the app will register itself and create the service principal under Enterprise applications of the client’s tenant, creating the local instance of the app object. The registration at this level is seamless, and users or admins do not have to do anything besides consenting the app to permissions that it needs and can then access and use the application.

Hope that demystifies the concept of multi-tenant applications in Microsoft 365! Read more about Single tenant vs Multi-tenant apps here and about application in Azure AD here.

Rabia Williams

Follow