注册应用程序权限

适用于: 开发人员版

在 SharePoint Embedded 应用创建容器或访问使用租户中的内容之前,注册容器类型应用程序权限。

完成 首先 创建和配置容器类型 ,以便拥有容器类型 ID 和拥有应用程序。

为什么需要注册

在使用租户中注册容器类型之前,SharePoint Embedded 应用程序无法与该租户中的容器交互。

注册控制:

  • 哪些应用程序 ID 可以访问容器类型。
  • 每个应用程序拥有的委派权限。
  • 每个应用程序具有哪些仅限应用的权限。
  • 来宾应用程序是否可以与拥有应用程序的容器交互。

如果注册缺失或不完整,以后的调用可能会失败并出现拒绝访问错误。

了解谁可以注册

只有容器类型的拥有应用程序才能在使用租户中调用注册 API。

拥有的应用程序必须:

  • 在使用租户上安装的服务主体。
  • 管理员同意在使用租户中执行注册。
  • Microsoft Graph 权限 (FileStorageContainerTypeReg.Selected 用户委派或仅限应用) 。
  • Microsoft Graph 资源的有效令牌。

注意

容器类型注册 API 在 Microsoft Graph v1.0 中可用。

当拥有应用程序代表用户 (委派) 调用注册 API 时,必须为该用户分配 SharePoint 嵌入式管理员 或 全局管理员 角色。 当它在没有用户上下文 (仅限应用的) 进行调用时,它使用客户端凭据授予流。

请求使用租户管理员授予对拥有应用程序的管理员同意。

使用 Microsoft 标识平台管理员同意终结点:

https://login.microsoftonline.com/{consuming-tenant-id}/v2.0/adminconsent?client_id={owning-app-clientid}&scope=https://graph.microsoft.com/.default&redirect_uri={spe-app-redirect-uri}

为载入流程配置成功和错误处理。

有关国家/地区云终结点,请参阅国家/地区云上的 Microsoft 标识平台终结点。

获取令牌进行注册

使用委派或仅应用身份验证进行注册。

注册要求:

  • FileStorageContainerTypeReg.Selected Microsoft Graph 权限。
  • 对于仅限应用的调用, 客户端凭据授予流。
  • 对于委派调用,是具有 SharePoint Embedded 管理员或全局管理员角色的登录用户。

注册容器类型权限

调用使用租户中的注册终结点。

PUT https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypeRegistrations/{containerTypeId}

{containerTypeId} 是在开发人员租户中创建的容器类型 ID。

在请求正文中,为容器类型提供应用程序权限授予。

创建、替换或更新注册

根据是需要替换完整注册还是更新所选属性来选择操作:

目标 Microsoft Graph 请求 行为
创建或替换注册 PUT /storage/fileStorage/containerTypeRegistrations/{containerTypeId} 使用容器类型 ID 创建注册。 如果注册存在,请求会将其替换为完整的有效负载。
更新所选注册属性 PATCH /storage/fileStorage/containerTypeRegistrations/{registrationId} 仅汇报 Microsoft Graph v1.0 中提供的属性。

该 PATCH 操作使用乐观并发的注册 etag 。 读取当前注册,并将其属性包含在 etag 更新正文中。 如果另一个请求首先更改注册,请读取最新值并核对更新,而不是覆盖它。

注册更新可能需要长达一小时才能传播。

有关 API 的详细信息,请参阅 创建 fileStorageContainerTypeRegistration 和 更新 fileStorageContainerTypeRegistration。

向拥有应用授予权限

通用首次注册会授予拥有应用对委派调用和仅应用调用的完全权限。

{
  "applicationPermissionGrants": [
    {
      "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
      "delegatedPermissions": ["full"],
      "applicationPermissions": ["full"]
    }
  ]
}

将示例应用 ID 替换为你拥有的应用程序 ID。

警告

将最小权限用于生产。 仅当应用程序需要完全容器类型访问时才授予 full 。

向来宾应用授予权限

拥有的应用还可以注册其他应用程序的权限。

当来宾应用需要定义的工作负载(例如备份或处理)时,使用此模式。

{
  "applicationPermissionGrants": [
    {
      "appId": "71392b2f-1765-406e-86af-5907d9bdb2ab",
      "delegatedPermissions": ["full"],
      "applicationPermissions": ["full"]
    },
    {
      "appId": "89ea5c94-7736-4e25-95ad-3fa95f62b6cd",
      "delegatedPermissions": ["read", "write"],
      "applicationPermissions": ["none"]
    }
  ]
}

将这两个应用 ID 替换为应用程序。

权限值

权限 用途
none 不授予任何权限。
readContent 读取此类型容器中的内容。
writeContent 在此类型的容器中写入内容。
create 创建此类型的容器。
delete 删除此类型的容器。
read 读取容器元数据。
write 更新容器元数据。
enumeratePermissions 枚举容器成员和角色。
addPermissions 添加容器成员。
updatePermissions 更新现有成员资格。
deletePermissions 删除其他成员。
deleteOwnPermission 删除调用方自己的成员身份。
managePermissions 管理容器角色分配。
manageContent 管理此类型容器的内容。
full 授予所有权限。

注意

writeContent 如果没有 ,则 readContent无法授予。

验证注册

成功注册将返回,响应正文中配置的权限将返回 201 Created 。

注册成功后:

  1. 确认响应包含预期的应用 ID。
  2. 确认委派和仅限应用的数组与预期授权匹配。
  3. 获取具有 SharePoint Embedded 权限的 Microsoft Graph 令牌。
  4. 尝试与注册权限匹配的低风险操作。
  5. 继续 配置身份验证和授权。
症状 可能的原因 操作
401 Unauthorized 令牌缺失或无效 请求有效的仅应用令牌。
403 Forbidden 应用缺乏权限或不拥有应用 确认 FileStorageContainerTypeReg.Selected、同意和应用 ID。
404 Not Found 容器类型不存在 验证 ID 和租户。
Graph 调用拒绝访问 注册缺失或不足 使用所需的权限重新注册。
管理员找不到隐藏的权限 门户不公开它 使用管理员同意 URL。

安全重新注册

可以调用注册 API 的次数没有限制。

上次成功的注册调用将确定在使用租户中使用的设置。

使用安全更新过程:

  1. 确定更改是需要完全 PUT 替换还是有针对性的 PATCH 更新。
  2. 对于 PUT,生成完整的注册有效负载。
  3. 对于 PATCH,请阅读并包含当前注册。etag
  4. 包括应保留访问权限的所有应用。
  5. 提交注册调用。
  6. 验证响应。
  7. 对每个应用角色运行冒烟测试。

重要

请勿发送部分有效负载,除非你希望生成的注册仅包含该组应用程序和权限。

后续步骤

在“ 配置身份验证和授权”中配置令牌和授权流。