Set up tenant restrictions V2 (Preview)

Note

The Tenant restrictions settings, which are included with cross-tenant access settings, are preview features of Azure Active Directory. For more information about previews, see Supplemental Terms of Use for Microsoft Azure Previews.

For increased security, you can limit what your users can access when they use an external account to sign in from your networks or devices. With the Tenant restrictions settings included with cross-tenant access settings, you can control the external apps that your Windows device users can access when they're using external accounts.

For example, let's say a user in your organization has created a separate account in an unknown tenant, or an external organization has given your user an account that lets them sign in to their organization. You can use tenant restrictions to prevent the user from using some or all external apps while they're signed in with the external account on your network or devices.

1	Contoso configures Tenant restrictions in their cross-tenant access settings to block all external accounts and external apps. Contoso enforces the policy on each Windows device by updating the local computer configuration with Contoso's tenant ID and the tenant restrictions policy ID.
2	A user with a Contoso-managed Windows device tries to sign in to an external app using an account from an unknown tenant. The Windows device adds an HTTP header to the authentication request. The header contains Contoso's tenant ID and the tenant restrictions policy ID.
3	Authentication plane protection: Azure AD uses the header in the authentication request to look up the tenant restrictions policy in the Azure AD cloud. Because Contoso's policy blocks external accounts from accessing external tenants, the request is blocked at the authentication level.
4	Data plane protection: The user tries to access the external application by copying an authentication response token they obtained outside of Contoso's network and pasting it into the Windows device. However, Azure AD compares the claim in the token to the HTTP header added by the Windows device. Because they don't match, Azure AD blocks the session so the user can't access the application.

This article describes how to configure tenant restrictions V2 using the Azure portal. You can also use the Microsoft Graph cross-tenant access API to create these same tenant restrictions policies.

Tenant restrictions V2 overview

Azure AD offers two versions of tenant restrictions policies:

• Tenant restrictions V1, described in Set up tenant restrictions V1 for B2B collaboration, let you restrict access to external tenants by configuring a tenant allowlist on your corporate proxy.
• Tenant restrictions V2, described in this article, let you apply policies directly to your users' Windows devices instead of through your corporate proxy, reducing overhead and providing more flexible, granular control.

Supported scenarios

Tenant restrictions V2 can be scoped to specific users, groups, organizations, or external apps. Apps built on the Windows operating system networking stack are protected, including:

• All Office apps (all versions/release channels).
• Universal Windows Platform (UWP) .NET applications.
• Microsoft Edge and all websites in Microsoft Edge.
• Auth plane protection for all applications that authenticate with Azure AD, including all Microsoft first-party applications and any third-party applications that use Azure AD for authentication.
• Data plane protection for SharePoint Online and Exchange Online.
• Anonymous access protection for SharePoint Online, OneDrive for business, and Teams (with Federation Controls configured).
• Authentication and Data plane protection for Microsoft tenant or Consumer accounts.

Unsupported scenarios

• Chrome, Firefox, and .NET applications such as PowerShell.
• Anonymous blocking to consumer OneDrive account. Customers can work around at proxy level by blocking https://onedrive.live.com/.
• When a user accesses a third-party app, like Slack, using an anonymous link or non-Azure AD account.
• When a user copies an Azure AD-issued token from a home machine to a work machine and uses it to access a third-party app like Slack.

Compare Tenant restrictions V1 and V2

The following table compares the features in each version.

	Tenant restrictions V1	Tenant restrictions V2
Policy enforcement	The corporate proxy enforces the tenant restriction policy in the Azure AD control plane.	Windows devices are configured to point Microsoft traffic to the tenant restriction policy, and the policy is enforced in the cloud. Tenant restrictions are enforced upon resource access, providing data path coverage and protection against token infiltration. For non-Windows devices, the corporate proxy enforces the policy.
Malicious tenant requests	Azure AD blocks malicious tenant authentication requests to provide authentication plane protection.	Azure AD blocks malicious tenant authentication requests to provide authentication plane protection.
Granularity	Limited.	Tenant, user, group, and application granularity.
Anonymous access	Anonymous access to Teams meetings and file sharing is allowed.	Anonymous access to Teams meetings is blocked. Access to anonymously shared resources (“Anyone with the link”) is blocked.
Microsoft accounts (MSA)	Uses a Restrict-MSA header to block access to consumer accounts.	Allows control of Microsoft account (MSA and Live ID) authentication on both the identity and data planes. For example, if you enforce tenant restrictions by default, you can create a Microsoft accounts-specific policy that allows users to access specific apps with their Microsoft accounts, for example: Microsoft Learn (app ID 18fbca16-2224-45f6-85b0-f7bf2b39b3f3), or Microsoft Enterprise Skills Initiative (app ID 195e7f27-02f9-4045-9a91-cd2fa1c2af2f).
Proxy management	Manage corporate proxies by adding tenants to the Azure AD traffic allowlist.	N/A
Platform support	Supported on all platforms. Provides only authentication plane protection.	Supported on Windows operating systems and Microsoft Edge by adding the tenant restrictions V2 header using Windows Group Policy. This configuration provides both authentication plane and data plane protection. On other platforms, like macOS, Chrome browser, and .NET applications, tenant restrictions V2 are supported when the tenant restrictions V2 header is added by the corporate proxy. This configuration provides only authentication plane protection.
Portal support	No user interface in the Azure portal for configuring the policy.	User interface available in the Azure portal for setting up the cloud policy.
Unsupported apps	N/A	Block unsupported app use with Microsoft endpoints by using Windows Defender Application Control (WDAC) or Windows Firewall (for example, for Chrome, Firefox, and so on). See Block Chrome, Firefox and .NET applications like PowerShell.

Migrate tenant restrictions V1 policies to V2

Along with using tenant restrictions V2 to manage access for your Windows device users, we recommend configuring your corporate proxy to enforce tenant restrictions V2 to manage other devices and apps in your corporate network. Although configuring tenant restrictions on your corporate proxy doesn't provide data plane protection, it provides authentication plane protection. For details, see Step 4: Set up tenant restrictions V2 on your corporate proxy.

Tenant restrictions vs. inbound and outbound settings

Although tenant restrictions are configured along with your cross-tenant access settings, they operate separately from inbound and outbound access settings. Cross-tenant access settings give you control when users sign in with an account from your organization. By contrast, tenant restrictions give you control when users are using an external account. Your inbound and outbound settings for B2B collaboration and B2B direct connect don't affect (and are unaffected by) your tenant restrictions settings.

Think of the different cross-tenant access settings this way:

• Inbound settings control external account access to your internal apps.
• Outbound settings control internal account access to external apps.
• Tenant restrictions control external account access to external apps.

Tenant restrictions vs. B2B collaboration

When your users need access to external organizations and apps, we recommend enabling tenant restrictions to block external accounts and use B2B collaboration instead. B2B collaboration gives you the ability to:

• Use Conditional Access and force multi-factor authentication for B2B collaboration users.
• Manage inbound and outbound access.
• Terminate sessions and credentials when a B2B collaboration user's employment status changes or their credentials are breached.
• Use sign-in logs to view details about the B2B collaboration user.

Tenant restrictions and Microsoft Teams

For greater control over access to Teams meetings, you can use Federation Controls in Teams to allow or block specific tenants, along with tenant restrictions V2 to block anonymous access to Teams meetings. Tenant restrictions prevent users from using an externally issued identity to join Teams meetings.

For example, suppose Contoso uses Teams Federation Controls to block the Fabrikam tenant. If someone with a Contoso device uses a Fabrikam account to join a Contoso Teams meeting, they're allowed into the meeting as an anonymous user. Now, if Contoso also enables tenant restrictions V2, Teams blocks anonymous access, and the user isn't able to join the meeting.

To enforce tenant restrictions for Teams, you need to configure tenant restrictions V2 in your Azure AD cross-tenant access settings. You also need to set up Federation Controls in the Teams Admin portal and restart Teams. Tenant restrictions implemented on the corporate proxy won't block anonymous access to Teams meetings, SharePoint files, and other resources that don't require authentication.

Tenant restrictions V2 and SharePoint Online

SharePoint Online supports tenant restrictions v2 on both the authentication plane and the data plane.

Authenticated sessions

When tenant restrictions v2 are enabled on a tenant, unauthorized access is blocked during authentication. If a user directly accesses a SharePoint Online resource without an authenticated session, they're prompted to sign in. If the tenant restrictions v2 policy allows access, the user can access the resource; otherwise, access is blocked.

Anonymous access

If a user tries to access an anonymous file using their home tenant/corporate identity, they'll be able to access the file. But if the user tries to access the anonymous file using any externally issued identity, access is blocked.

For example, say a user is using a managed device configured with tenant restrictions V2 for Tenant A. If they select an anonymous access link generated for a Tenant A resource, they should be able to access the resource anonymously. But if they select an anonymous access link generated for Tenant B SharePoint Online, they're prompted to sign-in. Anonymous access to resources using an externally issued identity is always blocked.

Tenant restrictions V2 and OneDrive

Like SharePoint, OneDrive for Business supports tenant restrictions v2 on both the authentication plane and the data plane. Blocking anonymous access to OneDrive for business is also supported. For example, tenant restrictions V2 policy enforcement works at the OneDrive for Business endpoint (microsoft-my.sharepoint.com).

However, OneDrive for consumer accounts (via onedrive.live.com) doesn't support tenant restrictions V2. Some URLs (such as onedrive.live.com) are unconverged and use our legacy stack. When a user accesses the OneDrive consumer tenant through these URLs, the policy isn't enforced. As a workaround, you can block https://onedrive.live.com/ at the proxy level.

Tenant restrictions V2 and non-Windows platforms

For non-Windows platforms, you can break and inspect traffic to add the tenant restrictions V2 parameters into the header via proxy. However, some platforms don't support break and inspect, so tenant restrictions V2 won't work. For these platforms, the following features of Azure AD can provide protection:

• 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 (under Allow only configured organization accounts in apps)

Although these alternatives provide protection, certain scenarios can only be covered through tenant restrictions, such as the use of a browser to access Microsoft 365 services through the web instead of the dedicated app.

Prerequisites

To configure tenant restrictions, you'll need the following:

• Azure AD Premium P1 or P2
• Account with a role of Global administrator or Security administrator
• Windows devices running Windows 10, Windows 11, or Windows Server 2022 with the latest updates

Step 1: Configure default tenant restrictions V2

Settings for tenant restrictions V2 are located in the Azure portal under Cross-tenant access settings. First, configure the default tenant restrictions you want to apply to all users, groups, apps, and organizations. Then, if you need partner-specific configurations, you can add a partner's organization and customize any settings that differ from your defaults.

To configure default tenant restrictions

1. Sign in to the Azure portal using a Global administrator, Security administrator, or Conditional Access administrator account. Then open the Azure Active Directory service.

2. Select External Identities

3. Select Cross-tenant access settings, and then select the Default settings tab.

   

4. Scroll to the Tenant restrictions (Preview) section.

5. Select the Edit tenant restrictions defaults link.

   

6. If a default policy doesn't exist yet in the tenant, next to the Policy ID you'll see a Create Policy link. Select this link.

   

7. The Tenant restrictions page displays both your Tenant ID and your tenant restrictions Policy ID. Use the copy icons to copy both of these values. You'll use them when you configure Windows clients to enable tenant restrictions.

   

8. Select the External users and groups tab. Under Access status, choose one of the following:

   • Allow access: Allows all users who are signed in with external accounts to access external apps (specified on the External applications tab).
   • Block access: Blocks all users who are signed in with external accounts from accessing external apps (specified on the External applications tab).

   

   Note

   Default settings can't be scoped to individual accounts or groups, so Applies to always equals All <your tenant> users and groups. Be aware that if you block access for all users and groups, you also need to block access to all external applications (on the External applications tab).

9. Select the External applications tab. Under Access status, choose one of the following:

   • Allow access: Allows all users who are signed in with external accounts to access the apps specified in the Applies to section.
   • Block access: Blocks all users who are signed in with external accounts from accessing the apps specified in the Applies to section.

   

10. Under Applies to, select one of the following:

    • All external applications: Applies the action you chose under Access status to all external applications. If you block access to all external applications, you also need to block access for all of your users and groups (on the Users and groups tab).
    • Select external applications: Lets you choose the external applications you want the action under Access status to apply to. To select applications, choose Add Microsoft applications or Add other applications. Then search by the application name or the application ID (either the client app ID or the resource app ID) and select the app. (See a list of IDs for commonly used Microsoft applications.) If you want to add more apps, use the Add button. When you're done, select Submit.

    

11. Select Save.

Step 2: Configure tenant restrictions V2 for specific partners

Suppose you use tenant restrictions to block access by default, but you want to allow users to access certain applications using their own external accounts. For example, say you want users to be able to access Microsoft Learn with their own Microsoft accounts (MSAs). The instructions in this section describe how to add organization-specific settings that take precedence over the default settings.

Example: Configure tenant restrictions V2 to allow Microsoft Accounts

1. Sign in to the Azure portal using a Global administrator, Security administrator, or Conditional Access administrator account. Then open the Azure Active Directory service.

2. Select External Identities, and then select Cross-tenant access settings.

3. Select Organizational settings. (If the organization you want to add has already been added to the list, you can skip adding it and go directly to modifying the settings.)

4. Select Add organization.

5. On the Add organization pane, type the full domain name (or tenant ID) for the organization.

   Example: Search for the following Microsoft Accounts tenant ID:

   9188040d-6c67-4c5b-b112-36a304b66dad
   

   

6. Select the organization in the search results, and then select Add.

7. The organization appears in the Organizational settings list. Scroll to the right to see the Tenant restrictions column. At this point, all tenant restrictions settings for this organization are inherited from your default settings. To change the settings for this organization, select the Inherited from default link under the Tenant restrictions column.

   

8. The Tenant restrictions (Preview) page for the organization appears. Copy the values for Tenant ID and Policy ID. You'll use them when you configure Windows clients to enable tenant restrictions.

   

9. Select Customize settings, and then select the External users and groups tab. Under Access status, choose an option:

   • Allow access: Allows users and groups specified under Applies to who are signed in with external accounts to access external apps (specified on the External applications tab).
   • Block access: Blocks users and groups specified under Applies to who are signed in with external accounts from accessing external apps (specified on the External applications tab).

   Note

   For our Microsoft Accounts example, we select Allow access.

   

10. Under Applies to, choose either All <your tenant> users and groups or Select <your tenant> users and groups. If you choose Select <your tenant> users and groups, perform these steps for each user or group you want to add:

    • Select Add external users and groups.
    • In the Select pane, type the user name or group name in the search box.
    • Select the user or group in the search results.
    • If you want to add more, select Add and repeat these steps. When you're done selecting the users and groups you want to add, select Submit.

    Note

    For our Microsoft Accounts example, we select All Contoso users and groups.

    

11. Select the External applications tab. Under Access status, choose whether to allow or block access to external applications.

    • Allow access: Allows the external applications specified under Applies to to be accessed by your users when using external accounts.
    • Block access: Blocks the external applications specified under Applies to from being accessed by your users when using external accounts.

    Note

    For our Microsoft Accounts example, we select Allow access.

    

12. Under Applies to, select one of the following:

    • All external applications: Applies the action you chose under Access status to all external applications.
    • Select external applications: Applies the action you chose under Access status to all external applications.

    Note

    • For our Microsoft Accounts example, we choose Select external applications.
    • If you block access to all external applications, you also need to block access for all of your users and groups (on the Users and groups tab).

    

13. If you chose Select external applications, do the following for each application you want to add:

    • Select Add Microsoft applications or Add other applications. For our Microsoft Learn example, we choose Add other applications.
    • In the search box, type the application name or the application ID (either the client app ID or the resource app ID). (See a list of IDs for commonly used Microsoft applications.) For our Microsoft Learn example, we enter the application ID 18fbca16-2224-45f6-85b0-f7bf2b39b3f3.
    • Select the application in the search results, and then select Add.
    • Repeat for each application you want to add.
    • When you're done selecting applications, select Submit.

    

14. The applications you selected are listed on the External applications tab. Select Save.

    

Step 3: Enable tenant restrictions on Windows managed devices

After you create a tenant restrictions V2 policy, you can enforce the policy on each Windows 10, Windows 11, and Windows Server 2022 device by adding your tenant ID and the policy ID to the device's Tenant Restrictions configuration. When tenant restrictions are enabled on a Windows device, corporate proxies aren't required for policy enforcement. Devices don't need to be Azure AD managed to enforce tenant restrictions V2; domain-joined devices that are managed with Group Policy are also supported.

Administrative Templates (.admx) for Windows 10 November 2021 Update (21H2) and Group policy settings

You can use Group Policy to deploy the tenant restrictions configuration to Windows devices. Refer to these resources:

• Administrative Templates for Windows 10
• Group Policy Settings Reference Spreadsheet for Windows 10

Test the policies on a device

To test the tenant restrictions V2 policy on a device, follow these steps.

Note

• The device must be running Windows 10, Windows 11, or Windows Server 2022 with the latest updates.

1. On the Windows computer, press the Windows key, type gpedit, and then select Edit group policy (Control panel).

2. Go to Computer Configuration > Administrative Templates > Windows Components > Tenant Restrictions.

3. Right-click Cloud Policy Details in the right pane, and then select Edit.

4. Retrieve the Tenant ID and Policy ID you recorded earlier (in step 7 under To configure default tenant restrictions) and enter them in the following fields (leave all other fields blank):

   • Azure AD Directory ID: Enter the Tenant ID you recorded earlier. You can also find your tenant ID in the Azure portal by navigating to Azure Active Directory > Properties and copying the Tenant ID.
   • Policy GUID: The ID for your cross-tenant access policy. It's the Policy ID you recorded earlier. You can also find this ID by using the Graph Explorer command https://graph.microsoft.com/v1.0/policies/crossTenantAccessPolicy/default.

   

5. Select OK.

Step 4: Set up tenant restrictions V2 on your corporate proxy

Tenant restrictions V2 policies can't be directly enforced on non-Windows 10, Windows 11, or Windows Server 2022 devices, such as Mac computers, mobile devices, unsupported Windows applications, and Chrome browsers. To ensure sign-ins are restricted on all devices and apps in your corporate network, configure your corporate proxy to enforce tenant restrictions V2. Although configuring tenant restrictions on your corporate proxy don't provide data plane protection, it does provide authentication plane protection.

Important

If you've previously set up tenant restrictions, you'll need to stop sending restrict-msa to login.live.com. Otherwise, the new settings will conflict with your existing instructions to the MSA login service.

1. Configure the tenant restrictions V2 header as follows:

   Header name	Header Value
   sec-Restrict-Tenant-Access-Policy	<DirectoryId>:<policyGuid>

   • DirectoryID is your Azure AD tenant ID. Find this value by signing in to the Azure portal as an administrator, select Azure Active Directory, then select Properties.
   • policyGUID is the object ID for your cross-tenant access policy. Find this value by calling /crosstenantaccesspolicy/default and using the “id” field returned.

2. On your corporate proxy, send the tenant restrictions V2 header to the following Microsoft login domains:

   • login.live.com
   • login.microsoft.com
   • login.microsoftonline.com
   • login.windows.net

   This header enforces your tenant restrictions V2 policy on all sign-ins on your network. This header won't block anonymous access to Teams meetings, SharePoint files, or other resources that don't require authentication.

Block Chrome, Firefox and .NET applications like PowerShell

You can use the Windows Firewall feature to block unprotected apps from accessing Microsoft resources via Chrome, Firefox, and .NET applications like PowerShell. The applications that would be blocked/allowed as per the tenant restrictions V2 policy.

For example, if a customer adds PowerShell to their tenant restrictions V2 CIP policy and has graph.microsoft.com in their tenant restrictions V2 policy endpoint list, then PowerShell should be able to access it with firewall enabled.

1. On the Windows computer, press the Windows key, type gpedit, and then select Edit group policy (Control panel).

2. Go to Computer Configuration > Administrative Templates > Windows Components > Tenant Restrictions.

3. Right-click Cloud Policy Details in the right pane, and then select Edit.

4. Select the Enable firewall protection of Microsoft endpoints checkbox, and then select OK.

After you enable the firewall setting, try signing in using a Chrome browser. Sign-in should fail with the following message:

View tenant restrictions V2 events

View events related to tenant restrictions in Event Viewer.

1. In Event Viewer, open Applications and Services Logs.
2. Navigate to Microsoft > Windows > TenantRestrictions > Operational and look for events.

Audit logs

The Azure AD audit logs provide records of system and user activities, including activities initiated by guest users. To access audit logs, in Azure Active Directory, under Monitoring, select Audit logs. To access audit logs of one specific user, select Azure Active Directory > Users > select the user > Audit logs.

You can get more details about each event listed in the audit log. For example, let's look at the user update details.

You can also export these logs from Azure AD and use the reporting tool of your choice to get customized reports.

Microsoft Graph

Use Microsoft Graph to get policy information:

HTTP request

• Get default policy

  GET https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/default
  

• Reset to system default

  POST https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/default/resetToSystemDefault
  

• Get partner configuration

  GET https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners
  

• Get a specific partner configuration

  GET https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners/9188040d-6c67-4c5b-b112-36a304b66dad
  

• Update a specific partner

  PATCH https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy/partners/9188040d-6c67-4c5b-b112-36a304b66dad
  

Request body

"tenantRestrictions": {
    "usersAndGroups": {
        "accessType": "allowed",
        "targets": [
            {
                "target": "AllUsers",
                "targetType": "user"
            }
        ]
    },
    "applications": {
        "accessType": "allowed",
        "targets": [
            {
                "target": "AllApplications",
                "targetType": "application"
            }
        ]
    }
}

Next steps

See Configure external collaboration settings for B2B collaboration with non-Azure AD identities, social identities, and non-IT managed external accounts.