Restrict access to a tenant

Large organizations that emphasize security want to move to cloud services like Microsoft 365, but need to know that their users only can access approved resources. Traditionally, companies restrict domain names or IP addresses when they want to manage access. This approach fails in a world where software as a service (or SaaS) apps are hosted in a public cloud, running on shared domain names like outlook.office.com and login.partner.microsoftonline.cn. Blocking these addresses would keep users from accessing Outlook on the web entirely, instead of merely restricting them to approved identities and resources.

The Microsoft Entra solution to this challenge is a feature called tenant restrictions. With tenant restrictions, organizations can control access to SaaS cloud applications, based on the Microsoft Entra tenant the applications use for single sign-on. For example, you might want to allow access to your organization's Microsoft 365 applications, while preventing access to other organizations' instances of these same applications.

With tenant restrictions, organizations can specify the list of tenants that users on their network are permitted to access. Microsoft Entra ID then only grants access to these permitted tenants - all other tenants are blocked, even ones that your users might be guests in.

This article focuses on tenant restrictions for Microsoft 365, but the feature protects all apps that send the user to Microsoft Entra ID for single sign-on. If you use SaaS apps with a different Microsoft Entra tenant from the tenant used by your Microsoft 365, make sure that all required tenants are permitted. (For example, in B2B collaboration scenarios). For more information about SaaS cloud apps, see the Active Directory Marketplace.

How it works

The overall solution comprises the following components:

1. Microsoft Entra ID: If the Restrict-Access-To-Tenants: <permitted tenant list> header is present, Microsoft Entra-only issues security tokens for the permitted tenants.

2. On-premises proxy server infrastructure: This infrastructure is a proxy device capable of Transport Layer Security (TLS) inspection. You must configure the proxy to insert the header containing the list of permitted tenants into traffic destined for Microsoft Entra ID.

3. Client software: To support tenant restrictions, client software must request tokens directly from Microsoft Entra ID, so that the proxy infrastructure can intercept traffic. Browser-based Microsoft 365 applications currently support tenant restrictions, as do Office clients that use modern authentication (like OAuth 2.0).

4. Modern Authentication: Cloud services must use modern authentication to use tenant restrictions and block access to all nonpermitted tenants. You must configure Microsoft 365 cloud services to use modern authentication protocols by default. For the latest information on Microsoft 365 support for modern authentication, read Updated Office 365 modern authentication.

The following diagram illustrates the high-level traffic flow. Tenant restrictions require TLS inspection only on traffic to Microsoft Entra ID, not to the Microsoft 365 cloud services. This distinction is important, because the traffic volume for authentication to Microsoft Entra ID is typically much lower than traffic volume to SaaS applications like Exchange Online and SharePoint Online.

Set up tenant restrictions

There are two steps to get started with tenant restrictions. First, make sure that your clients can connect to the right addresses. Second, configure your proxy infrastructure.

URLs and IP addresses

To use tenant restrictions, your clients must be able to connect to the following Microsoft Entra URLs to authenticate:

• login.partner.microsoftonline.cn
• login.chinacloudapi.cn

Additionally, to access Office 365, your clients must also be able to connect to the fully qualified domain names (FQDNs), URLs, and IP addresses defined in Office 365 URLs and IP address ranges.

Proxy configuration and requirements

The following configuration is required to enable tenant restrictions through your proxy infrastructure. This guidance is generic, so you should refer to your proxy vendor's documentation for specific implementation steps.

Prerequisites

• The proxy must be able to perform TLS interception, HTTP header insertion, and filter destinations using FQDNs/URLs.

• Clients must trust the certificate chain presented by the proxy for TLS communications. For example, if certificates from an internal public key infrastructure (PKI) are used, the internal issuing root certificate authority certificate must be trusted.

• Microsoft Entra ID P1 or P2 licenses are required for use of tenant restrictions.

Configuration

For each outgoing request to login.partner.microsoftonline.cn and login.chinacloudapi.cn, insert two HTTP headers: Restrict-Access-To-Tenants and Restrict-Access-Context.

The headers should include the following elements:

• For Restrict-Access-To-Tenants, use a value of <permitted tenant list>, which is a comma-separated list of tenants you want to allow users to access. Any domain that is registered with a tenant can be used to identify the tenant in this list, and the directory ID itself. For an example of all three ways of describing a tenant, the name/value pair to allow Contoso, Fabrikam, and Microsoft looks like: Restrict-Access-To-Tenants: contoso.com,fabrikam.partner.onmschina.cn,aaaabbbb-0000-cccc-1111-dddd2222eeee

• For Restrict-Access-Context, use a value of a single directory ID, declaring which tenant is setting the tenant restrictions. For example, to declare Contoso as the tenant that set the tenant restrictions policy, the name/value pair looks like: Restrict-Access-Context: bbbbcccc-1111-dddd-2222-eeee3333ffff. You must use your own directory ID here to get logs for these authentications. If you use any directory ID other than your own, the sign-in logs *appear in someone else's tenant, with all personal information removed. For more information, see Admin experience.

To find your directory ID:

1. Sign in to the Microsoft Entra admin center as at least a Global Reader.
2. Browse to Identity > Overview > Overview.
3. Copy the Tenant ID value.

To validate that a directory ID or domain name refer to the same tenant, use that ID or domain in place of <tenant> in this URL: https://login.partner.microsoftonline.cn/<tenant>/v2.0/.well-known/openid-configuration. If the results with the domain and the ID are the same, they refer to the same tenant.

To prevent users from inserting their own HTTP header with nonapproved tenants, the proxy needs to replace the Restrict-Access-To-Tenants header if it's already present in the incoming request.

Clients must be forced to use the proxy for all requests to login.partner.microsoftonline.cn and login.chinacloudapi.cn. For example, if PAC files are used to direct clients to use the proxy, end users shouldn't be able to edit or disable the PAC files.

The user experience

This section describes the experience for both end users and admins.

End-user experience

An example user is on the Contoso network, but is trying to access the Fabrikam instance of a shared SaaS application like Outlook online. If Fabrikam is a nonpermitted tenant for the Contoso instance, the user sees an access denial message. The denial message says you're trying to access a resource that belongs to an organization unapproved by your IT department.

Admin experience

While configuration of tenant restrictions is done on the corporate proxy infrastructure, admins can access the tenant restrictions reports in the Microsoft Entra admin center directly. To view the reports:

1. Sign in to the Microsoft Entra admin center as at least a Global Reader.
2. Browse to Identity > Overview > Tenant restrictions.

The admin for the tenant specified as the Restricted-Access-Context tenant can use this report to see sign-ins blocked because of the tenant restrictions policy, including the identity used and the target directory ID. Sign-ins are included if the tenant setting the restriction is either the user tenant or resource tenant for the sign-in.

The report might contain limited information, such as target directory ID, when a user who is in a tenant other than the Restricted-Access-Context tenant signs in. In this case, user identifiable information, such as name and user principal name, is masked to protect user data in other tenants (For example, "{PII Removed}@domain.com" or 00000000-0000-0000-0000-000000000000 in place of usernames and object IDs as appropriate).

Like other reports in the Microsoft Entra admin center, you can use filters to specify the scope of your report. You can filter on a specific time interval, user, application, client, or status. If you select the Columns button, you can choose to display data with any combination of the following fields:

• User - this field can have personal data removed, where its value is set to 00000000-0000-0000-0000-000000000000.
• Application
• Status
• Date
• Date (UTC) - where UTC is Coordinated Universal Time
• IP Address
• Client
• Username - this field can have personal data removed, where its value is set to {PII Removed}@domain.com
• Location
• Target tenant ID

Microsoft 365 support

Microsoft 365 applications must meet two criteria to fully support tenant restrictions:

1. The client used supports modern authentication.
2. Modern authentication is enabled as the default authentication protocol for the cloud service.

For the latest information on which Office clients currently support modern authentication, see Updated Office 365 modern authentication. That page also includes links to instructions for enabling modern authentication on specific Exchange Online and Skype for Business Online tenants. SharePoint Online already enables Modern authentication by default. Teams only supports modern auth, and doesn't support legacy auth, so this bypass concern doesn't apply to Teams.

Microsoft 365 browser-based applications (such as the Office Portal, Yammer, SharePoint sites, and Outlook on the Web.) currently support tenant restrictions. Thick clients (Outlook, Skype for Business, Word, Excel, PowerPoint, and more) can enforce tenant restrictions only when using modern authentication.

Outlook and Skype for Business clients that support modern authentication might still be able to use legacy protocols against tenants where modern authentication isn't enabled, effectively bypassing tenant restrictions. Tenant restrictions might block applications that use legacy protocols if they contact login.partner.microsoftonline.cn, or login.chinacloudapi.cn during authentication.

For Outlook on Windows, customers might choose to implement restrictions preventing end users from adding nonapproved mail accounts to their profiles.

Azure RMS and Office Message Encryption incompatibility

The Azure Rights Management Service (Azure RMS) and Office Message Encryption features aren't compatible with tenant restrictions. These features rely on signing your users into other tenants in order to get decryption keys for the encrypted documents. Because tenant restrictions blocks access to other tenants, encrypted mail and documents sent to your users from untrusted tenants aren't accessible.

Testing

If you want to try out tenant restrictions before implementing it for your whole organization, you have two options: a host-based approach using a tool like Fiddler, or a staged rollout of proxy settings.

Fiddler for a host-based approach

Fiddler is a free web debugging proxy that can be used to capture and modify HTTP/HTTPS traffic, it includes inserting HTTP headers. To configure Fiddler to test tenant restrictions, perform the following steps:

1. Download and install Fiddler.

2. Configure Fiddler to decrypt HTTPS traffic, per Fiddler's help documentation.

3. Configure Fiddler to insert the Restrict-Access-To-Tenants and Restrict-Access-Context headers using custom rules:

   1. In the Fiddler Web Debugger tool, select the Rules menu and select Customize Rules… to open the CustomRules file.

   2. Add the following lines within the OnBeforeRequest function. Replace <List of tenant identifiers> with a domain registered with your tenant (for example, contoso.partner.onmschina.cn). Replace <directory ID> with your tenant's Microsoft Entra GUID identifier. You must include the correct GUID identifier in order for the logs to appear in your tenant.

    // Allows access to the listed tenants.
      if (
          oSession.HostnameIs("login.partner.microsoftonline.cn") ||
          oSession.HostnameIs("login.chinacloudapi.cn")
      )
      {
          oSession.oRequest["Restrict-Access-To-Tenants"] = "<List of tenant identifiers>";
          oSession.oRequest["Restrict-Access-Context"] = "<Your directory ID>";
      }
   
   

   If you need to allow multiple tenants, use a comma to separate the tenant names. For example:

   oSession.oRequest["Restrict-Access-To-Tenants"] = "contoso.partner.onmschina.cn,fabrikam.partner.onmschina.cn";

4. Save and close the CustomRules file.

After you configure Fiddler, you can capture traffic by going to the File menu and selecting Capture Traffic.

Staged rollout of proxy settings

Depending on the capabilities of your proxy infrastructure, you might be able to stage the rollout of settings to your users. See the following high-level options for consideration:

1. Use PAC files to point test users to a test proxy infrastructure, while normal users continue to use the production proxy infrastructure.
2. Some proxy servers might support different configurations using groups.

For specific details, refer to your proxy server documentation.

Platforms that don't support TLS break and inspect

Tenant restrictions depends on injection of a list of allowed tenants in the HTTPS header. This dependency requires Transport Layer Security Inspection (TLSI) to break and inspect traffic. For environments where the client's side isn't able to break and inspect the traffic to add headers, tenant restrictions doesn't work.

Take the example of Android 7.0 and onwards. Android changed how it handles trusted certificate authorities (CAs) to provide safer defaults for secure app traffic. For more information, see Changes to Trusted Certificate Authorities in Android Nougat.

Following the recommendation from Google, Microsoft client apps ignore user certificates by default. This policy makes such apps unable to work with tenant restrictions, since the certificates used by the network proxy are installed in the user certificate store, which client apps don't trust.

For such environments that can't break and inspect traffic to add the tenant restrictions parameters onto the header, other features of Microsoft Entra ID can provide protection. The following list provides more information on such Microsoft Entra features.

• Conditional Access: Only allow use of managed/compliant devices
• Conditional Access: Manage access for guest/external users
• B2B Collaboration: Restrict outbound rules by Cross-tenant access for the same tenants listed in the parameter "Restrict-Access-To-Tenants"
• B2B Collaboration: Restrict invitations to B2B users to the same domains listed in the "Restrict-Access-To-Tenants" parameter
• Application management: Restrict how users consent to applications
• Intune: Apply App Policy through Intune to restrict usage of managed apps to only the UPN of the account that enrolled the device - Check the section under, Allow only configured organization accounts in apps subheading.

However, some specific scenarios can only be covered using tenant restrictions.

Next steps

• Read about Updated Office 365 modern authentication
• Review the Office 365 URLs and IP address ranges