将 CrossTenantAccessPolicy JSON 迁移到新的 Microsoft 图形 API

2025-05-01

新版 CrossTenantAccessPolicy Microsoft Graph API 现已提供，能够增强策略的功能和管理。在 Microsoft Teams 共享频道和Microsoft Entra 外部 ID B2B 协作预览版期间创建的任何跨租户访问策略都必须更新为版本 2。本文档介绍对 Microsoft 图形 API 支持的架构的更改，并提供迁移策略的步骤。

背景

在 Microsoft Teams 共享频道和 Microsoft Entra 外部 ID B2B 协作的预览期间，管理员使用 Microsoft Graph 的 CrossTenantAccessPolicy API 版本 1 和序列化 JSON 创建了跨租户访问策略，例如：

POST https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy
{
  "definition": [
    "CrossTenantAccessPolicy": ...
  ]
}

但是，随着版本 2 中 API 和后端 JSON 架构的重新设计，新 API 不再支持以前创建的这些策略。因此，客户必须迁移到新的架构化 CrossTenantAccessPolicy 微软图形 API。

预检查：确定是否需要迁移

注释

如果已收到指示手动升级的通信，则此预检查很可能失败。

首先，通过尝试访问新的 CrossTenantAccessPolicy Microsoft Graph API 来确定是否需要迁移。如果遇到指示过时架构的错误，则表示正在使用不支持的策略 JSON。若要执行此检查，必须具有具有以下角色之一的帐户：全局管理员、安全管理员或条件访问管理员。

使用 Graph Explorer 资源管理器登录到你的租户并授予 directory.AccessAsUser.All 权限。

运行以下请求：

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

如果在任一 Bad Request 响应中收到错误，则表示需要将 JSON 迁移到受支持的架构。但是，如果在这两个 OK – 200 响应中都收到状态，则表示你已使用受支持的模式，迁移已完成或者无需迁移。
在继续之前，请确保您具有当前跨租户访问策略的备份副本，以便在迁移过程中遇到问题时还原。

如何迁移到新 API

有两个选项可用于将现有策略迁移到 Microsoft 图形 API 支持的新架构：

方法 1：就地迁移。如果策略位于生产环境中，并且需要迁移数据，请遵循此方法。
方法 2：将策略替换为新的空白策略。最简单的方法是使用新 API 创建新策略来替换旧策略。

只需执行一次迁移。迁移后，无需直接修改 JSON，因为Microsoft图形 API 为你管理基础 JSON。

方法 1：就地迁移

重要

在开始之前，请阅读本文档中有关新策略架构的详细信息部分。

查看架构的更改并熟悉模板。使用本文档中的示例，修改现有 JSON 以匹配正确的格式。
请确保已安装适用于 PowerShell 的 Microsoft Graph 模块。

启动 PowerShell 并连接到租户：

Connect-Graph -Scopes "Directory.AccessAsUser.All"

按照说明打开 Web 浏览器登录并输入全局管理员凭据。
使用以下命令将更新的 JSON 文件读入 PowerShell。此命令假定 JSON 文件位于当前文件夹中：
```
$policy = Get-Content .\CrossTenantAccessPolicy.json
```

运行以下命令，使用 Microsoft Graph 将 JSON 转换为正确的引入格式：

$json = "{\"displayName\": \"Cross Tenant Access Policy\", \"definition\":[\""+[string]$($policy.trim()).Replace("", \"\\\"").Replace("\r*\n", "")+"\"] }"

运行以下命令以更新现有策略：

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy" -Body $json -Headers @{"Content-Type"="application/json"}

运行以下命令来验证策略是否已成功更新：

Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/policies/crossTenantAccessPolicy" | %{$_.definition}

断开与租户的连接：
```
Disconnect-Graph
```
关闭 PowerShell。
重复预检查中的步骤：确定是否需要迁移，以确保 API 在默认终结点和合作伙伴终结点中返回有效的响应。

方法 2：将策略替换为新的空白策略

如果不需要迁移现有策略（例如在测试环境中工作时），可以将旧策略替换为空白策略。然后，可以使用新 API 创建策略。请参阅本文档中有关新策略架构的详细信息。

若要替换旧策略，请上传以下策略：

{ "CrossTenantAccessPolicy": { "Version": 1, "LastModified": "2021-09-20 16:14:00", "TenantGroup":[]} }

有关新策略架构的详细信息

使用新 API 创建策略之前，请查看此整个部分以了解架构的更改。

不再支持 AllowAccess

AllowAccess设置在FromMyTenancy和ToMyTenancy部分不再受支持。

之前

"FromMyTenancy": [
  {
    "AllowAccess": false
  }
]

之后

"FromMyTenancy": [
  {
    "AllowB2B": false,
    "AllowNativeFederation": false
  }
]

之前

"ToMyTenancy": [
  {
    "AllowAccess": true,
    "AllowNativeFederation": true
  }
]

之后

"ToMyTenancy": [
  {
    "AllowB2B": true,
    "AllowNativeFederation": true
  }
]

之前

"ToMyTenancy": [
  {
    "AllowAccess": true
  }
]

之后

"ToMyTenancy": [
  {
    "AllowB2B": true
  }
]

必须将信任设置移动到单独的条目

在ToMyTenancy部分中，信任设置现在必须与用于 B2B 协作和 B2B 直接连接的功能分开，在不同的条目中设置。 JSON 信任设置包括AcceptMFA和 AcceptCompliantDeviceAcceptHybridAzureADJoinedDevice。

之前

"ToMyTenancy": [
  {
    "AllowAccess": true,
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "AcceptMFA": true
  }
]

之后

"ToMyTenancy": [
  {
    "AllowB2B": true,
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    }
  },
  {
    "AcceptMFA": true
  }
]

之前

"ToMyTenancy": [
  {
    "AllowAccess": true,
    "AcceptMFA": true,
    "AcceptCompliantDevice": true,
    "AcceptHybridAzureADJoinedDevice": false
  }
]

之后

"ToMyTenancy": [
  {
    "AllowB2B": true
  },
  {
    "AcceptMFA": true,
    "AcceptCompliantDevice": true,
    "AcceptHybridAzureADJoinedDevice": false
  }
]

不支持应用程序的多个用户/组配置

不再支持创建访问或阻止特定应用程序的用户或组的多个配置。以前，策略 JSON 架构允许对特定应用程序允许或阻止的用户和组进行许多复杂的组合。例如，策略可以指定组 A 中的用户可以访问应用程序 A，而组 B 中的用户可能会被阻止访问应用程序 B。新架构仅支持允许或阻止用户和组，以及允许或阻止一组应用程序。此更改涵盖大多数方案，并使该功能更加直观。

不再受支持的配置示例

新架构 不再支持 以下配置：

"FromMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "Applications": ["Office365"]
  },
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "bbbbbbbb-1111-2222-3333-cccccccccccc"
      ]
    },
    "Applications": ["cccccccc-2222-3333-4444-dddddddddddd"]
  }
]

"ToMyTenancy": [
  {
    "AllowAccess": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "Applications": ["Office365"]
  },
  {
    "AllowAccess": false,
    "Targets": {
      "Groups": [
        "bbbbbbbb-1111-2222-3333-cccccccccccc"
      ]
    },
    "Applications": ["cccccccc-2222-3333-4444-dddddddddddd"]
  }
]

有效配置的示例

以下配置允许主租户中组 aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb 的所有用户访问所有外部租户中的 Office365。第二个基线配置阻止所有家庭用户通过 B2B 直接连接进行外部访问。

"FromMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "Applications": ["Office365"]
  },
  {
    "AllowNativeFederation": false
  }
]

以下配置允许主租户中aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb组的所有用户访问所有外部租户，实现B2B直接连接。它还阻止通过应用程序 ID cccccccc-2222-3333-4444-dddddddddddd访问一个外部应用程序。最后一个配置阻止访问主租户中 B2B 直接连接功能的其余用户。

"ToMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    }
  },
  {
    "AllowNativeFederation": false,
    "Applications": ["cccccccc-2222-3333-4444-dddddddddddd"]
  },
  {
    "AllowNativeFederation": false
  }
]

指定目标时，需要基线设置

在新设计中，如果您为特定目标指定了可供性，那么还需要添加一个不为任何目标指定的基线可供性。此基线负担适用于其余目标。否则，这些目标将应用相反的互动性。添加基准线可确保即使公司或服务的默认设置发生更改，目标也能保持您预期的功能。

之前

"ToMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "Applications": ["Office365"]
  }
]

之后

"ToMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    },
    "Applications": ["Office365"]
  },
  {
    "AllowNativeFederation": false
  }
]

之前

"FromMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    }
  },
  {
    "AllowNativeFederation": false,
    "Applications": ["Office365"]
  }
]

之后

"FromMyTenancy": [
  {
    "AllowNativeFederation": true,
    "Targets": {
      "Groups": [
        "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
      ]
    }
  },
  {
    "AllowNativeFederation": false,
    "Applications": ["Office365"]
  },
  {
    "AllowNativeFederation": false
  }
]

跨租户访问策略的模板

以下示例显示了正确配置的策略。可以将此示例用作模板，并删除与你无关的部分。

{
  "CrossTenantAccessPolicy": {
    "Version": 1,
    "LastModified": "2021-09-20 16:14:00",
    "TenantGroup": [
      {
        "DisplayName": "Allow B2B Collab to all home and external users for all apps",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "FromMyTenancy": [
          {
            "AllowB2B": true
          }
        ],
        "ToMyTenancy": [
          {
            "AllowB2B": true
          }
        ]
      },
      {
        "DisplayName": "Allow B2B Collab and Direct Connect to all home and external users for all apps",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "FromMyTenancy": [
          {
            "AllowB2B": true,
            "AllowNativeFederation": true
          }
        ],
        "ToMyTenancy": [
          {
            "AllowB2B": true,
            "AllowNativeFederation": true
          }
        ]
      },
      {
        "DisplayName": "Allow B2B Collab and Direct Connect to all home and external users for Office365 apps",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "FromMyTenancy": [
          {
            "AllowB2B": true,
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowB2B": false,
            "AllowNativeFederation": false
          }
        ],
        "ToMyTenancy": [
          {
            "AllowB2B": true,
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowB2B": false,
            "AllowNativeFederation": false
          }
        ]
      },
      {
        "DisplayName": "Allow B2B Collab to all home and external users for all apps and Direct Connect for Office365 apps only",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "FromMyTenancy": [
          {
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowB2B": true,
            "AllowNativeFederation": false
          }
        ],
        "ToMyTenancy": [
          {
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowB2B": true,
            "AllowNativeFederation": false
          }
        ]
      },
      {
        "DisplayName": "Allow B2B Direct Connect outbound for a group and Office365Appsonly and allow inbound external user to Office365 apps",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "FromMyTenancy": [
          {
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ],
            "Targets": {
              "Groups": [
                "eeeeeeee-4444-5555-6666-ffffffffffff"
              ]
            }
          },
          {
            "AllowNativeFederation": false
          }
        ],
        "ToMyTenancy": [
          {
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowNativeFederation": false
          }
        ]
      },
      {
        "DisplayName": "Allow B2B Direct Connect inbound external users from partner to Office365 apps and trust their MFA and device",
        "Tenants": [
          "dddddddd-3333-4444-5555-eeeeeeeeeeee"
        ],
        "ToMyTenancy": [
          {
            "AllowNativeFederation": true,
            "Applications": [
              "Office365"
            ]
          },
          {
            "AllowNativeFederation": false
          },
          {
            "AcceptMFA": true
          }
        ]
      }
    ]
  }
}

通过