Master the Azure AD Tenant Restrictions Feature


Hey Everyone! I hope all is well and is staying calm with all the madness happening in the world today! Maybe you had a chance to read my awesome blog series on using Power Automate to automate tasks with Azure AD and Active Directory. If not, I would highly recommend it! I have another blog post for you explaining the Azure AD Tenant Restrictions feature. We will review how to implement, how to test and how to troubleshoot the feature. Let’s dig into it!

Tenant Restrictions Implementation Overview

Azure AD (AAD) Tenant Restrictions is a feature available for Azure AD customers. It can be used to control which Azure AD tenants a user of an organization can access applications/resources in.  This feature is applied by having a web proxy service append additional HTTP headers for any requests sent to Azure AD.

NOTE: The use of this feature does not require any changes to Azure AD tenant settings. 

One of the headers is Restrict-Access-To-Tenants. This header is used to determine which Azure AD tenants users are allowed to access resources in. The other header is Restrict-Access-Context. This contains the Azure AD tenant identifier which determines the tenant that receives the tenant restrictions logs. Usually this is the tenant ID of the organization implementing the restrictions.

Tenant Restrictions User Impact

This feature can affect users of an organization when they access an application which is integrated with an AAD tenant. As mentioned previously, two additional headers need to be added to requests sent to AAD in order to have this feature enforced. To ensure the feature is enforced, users need to access the internet through a web proxy service. This usually means they need to be on the internal network or have a PAC file deployed to their machine.

Internal Users

Typically, when an organization implements this feature, they allow access to apps/resources in the AAD tenants that they own and manage. When accessing resources integrated with their own tenant there is typically no impact.

When accessing resources in a different AAD tenant users will receive an error unless an entry for that specific tenant is added to the Restrict-Access-To-Tenants HTTP header. Below is an example of the error the users would receive:

Azure AD Tenant Restrictions Error

Some scenarios where this can happen are the following:

  • SaaS apps shared by another organization (apps like Salesforce or Dropbox)
  • Advertisement
  • Multi-tenant apps (such as an external tenant instance of SharePoint Online or Teams) shared by another organization
  • Internal apps shared by another organization (internally developed apps integrated with the other organizations AAD tenant)

External Users (B2B Guest Users)

Let’s imagine you have an app or a resource that you would like to share with another organization. Your internal users can access the app fine without any issues and the tenant restrictions feature has been implemented successfully. When trying to invite a guest user from another Azure AD tenant using the B2B service the invited user receives an error like the error pictured above.

If this scenario occurs, it is most likely because the guest user’s organization is also using the tenant restrictions feature. The issue is probably occurring because they do not have an entry for your Azure AD tenant in their Restrict-Access-To-Tenants HTTP header. Once this entry is added, the error should stop occurring.

Other Tenant Restrictions Observations

Identity Provider Does Not Matter

Based on testing and my experience with the setting, it does not matter which Azure AD tenant or Identity Provider authenticates the user. If the Azure AD service receives the tenant restriction headers with the request it will only allow users to access applications/resources in the allowed list of tenants.

Troubleshooting Using the Azure AD Sign-In Logs

The image below shows what the AAD Sign-In logs capture when a tenant restriction error is encountered.  It is important to point out that these logs would be sent to the Azure AD tenant defined in the Restrict-Access-Context HTTP header. 

Notice the correlation ID is also recorded in the event.  The correlation ID from the error page the user is presented with can be used to search for the corresponding logs generated by that specific session.

The AAD Sign-In logs show events related to tenant restriction errors

The event shows the resource information.  It also shows error code 500021 which is specific to Azure AD tenant restriction errors

Fiddler Trace Testing

The Microsoft documentation I provided earlier shows a way to test this feature by using Fiddler. I highly recommend this! While testing you can see the HTTP headers in the requests sent to Azure AD as shown in the image below:

Notice the custom HTTP headers in the request pane on the bottom of the image

Updating the HTTP Headers

Scenario Example

Let’s go back to that scenario I mentioned earlier. You have successfully deployed the tenant restrictions feature in your environment. All end users either go through the proxy server or use a PAC file to ensure any traffic sent to Azure AD has the HTTP headers added to the requests. This includes any requests sent to the following endpoints:


This results in users only being able to access resources (apps) in your AAD tenant. As a result, the proxy service has a configuration that looks something like this:

Restrict-Access-Context: <The AAD Tenant ID GUID for my tenant>

New App From External Partner

When some of your users try to access an app being shared by another organization, they receive an error. You grab the Correlation ID from the error and search the sign-in logs and determine it is a tenant restrictions error. The resolution is to add another entry to the Restrict-Access-To-Tenants header value. The resulting configuration looks like this (note that the Restrict-Access-Context does not change):

Restrict-Access-Context: <The AAD Tenant ID GUID for my tenant> 

After the change, users in your org can access the new app from the external partner organization. You can go off to happy hour!


If you made it all the way through this post, you have learned how the AAD tenant restriction feature works. You have also learned how to troubleshoot the feature and how to test the feature. I hope this information along with my previous experiences I have shared helps you in your journey with exploring AAD tenant restrictions. Until next time, rock on!

2 thoughts on “Master the Azure AD Tenant Restrictions Feature”

  1. Hello Ed!
    Thanks a lot for the explanation. I would like to ask what will happen to mobile applications that use mobile networks for accessing saas services which authenticate using office365


    1. Hi Alexander,

      Thanks for reading! In terms of the tenant restrictions feature, it depends on if the organization has a mechanism on the device that would cause the mobile browser to send the required custom headers in the requests to Azure AD. If the headers are present, the restrictions will be enforced. I am not an expert in the MDM space but I am thinking maybe sending those headers is possible with an MDM solution which maybe connects the users to a VPN or applies settings to managed browsers.


Comments are closed.