通过

数据 API 生成器中的授权和角色

  • 项目

数据 API 生成器使用基于角色的授权工作流。 任何传入请求（无论是否经过身份验证）都分配给角色。 角色 可以是 系统角色 或 用户角色。 然后，根据配置文件中指定的已定义权限检查分配的角色，以了解哪些操作、字段和策略可用于请求的实体上的该角色。

角色

角色设置应在其中执行请求的权限上下文。 对于运行时配置中定义的每个实体，可以定义一组角色和关联权限，以确定如何在 REST 和 GraphQL 终结点中访问实体。

数据 API 生成器在单个角色的上下文中评估请求：

  • anonymous 如果未显示访问令牌，则为 。
  • authenticated 当提供有效的访问令牌时。
  • <CUSTOM_USER_ROLE> 如果提供了有效的访问令牌 ，并且X-MS-API-ROLE HTTP 标头包含在指定也包含在访问令牌的 roles 声明中的用户角色，则为 。

角色 不是 累加的，这意味着属于 和 Role1Role2 的成员的用户不会继承与这两个角色关联的权限。

系统角色

系统角色是由数据 API 生成器识别的内置角色。 系统角色会自动分配给请求者，而不考虑请求者在其访问令牌中表示的角色成员身份。 有两个系统角色： anonymous 和 authenticated。

匿名系统角色

系统 anonymous 角色分配给未经身份验证的用户执行的请求。 如果需要未经身份验证的访问权限， anonymous 运行时配置定义的实体必须包含角色的权限。

示例

以下数据 API 生成器运行时配置演示如何显式配置系统角色 anonymous ，以包括对 Book 实体的 读取 访问权限：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        }
    ]
}

当客户端应用程序发送代表未经身份验证的用户访问 Book 实体的请求时，应用不应包含 Authorization HTTP 标头。

经过身份验证的系统角色

系统 authenticated 角色分配给经过身份验证的用户执行的请求。

示例

以下数据 API 生成器运行时配置演示如何显式配置系统角色 authenticated ，以包括对 Book 实体的 读取 访问权限：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "authenticated",
            "actions": [ "read" ]
        }
    ]
}

用户角色

用户角色是分配给在运行时配置中设置的标识提供者中的用户的非系统角色。若要使数据 API 生成器在用户角色的上下文中评估请求，必须满足两个要求：

  1. 客户端应用提供的访问令牌必须包含列出用户的角色成员身份的角色声明。
  2. 客户端应用必须包含包含请求的 HTTP 标头 X-MS-API-ROLE ，并将标头的值设置为所需的用户角色。

角色评估示例

以下示例演示对 Book 数据 API 生成器运行时配置中配置的实体发出的请求，如下所示：

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

在 Static Web Apps 中，默认情况下，用户是匿名角色的成员。 如果用户已经过身份验证，则用户是 和 authenticated 角色的成员anonymous。

当客户端应用向使用 Static Web Apps 数据库连接 (Preview) 部署的数据 API 生成器发送经过身份验证的请求时，客户端应用将提供Static Web Apps转换为 JSON 的访问令牌：

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

由于数据 API 生成器在单个角色的上下文中评估请求，因此默认情况下，它会在系统角色 authenticated 的上下文中评估请求。

如果客户端应用程序的请求还包含值为 author的 HTTP 标头X-MS-API-ROLE，则会在角色的上下文中评估请求author。 包含访问令牌和 X-MS-API-ROLE HTTP 标头的示例请求：

curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book

重要

当提供的访问令牌 roles 的 声明不包含 标头中列出的 X-MS-API-ROLE 角色时，客户端应用的请求将被拒绝。

权限

权限描述：

  • 谁可以根据角色成员身份对实体发出请求？
  • (创建、读取、更新、删除、执行) 用户可以执行的操作？
  • 特定操作可访问哪些字段？
  • 请求返回的结果存在哪些额外限制？

运行时配置一文中介绍了定义权限的语法。

重要

单个实体的权限配置中可能定义了多个角色。 但是，仅在单个角色的上下文中评估请求：

  • 默认情况下，系统角色 anonymous 或 authenticated
  • 如果包含，则为 HTTP 标头中 X-MS-API-ROLE 设置的角色。

默认保护

默认情况下，实体未配置任何权限，这意味着没有人可以访问该实体。 此外，数据 API 生成器在运行时配置中未引用数据库对象时会忽略这些对象。

必须显式配置权限

若要允许对实体进行未经身份验证的访问， anonymous 必须在实体的权限中显式定义角色。 例如，实体 book 的权限显式设置为允许未经身份验证的读取访问：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

为了简化对实体的权限定义，假定如果没有对 authenticated 角色的特定权限，则使用为角色 anonymous 定义的权限。 book前面显示的配置允许任何匿名或经过身份验证的用户对book实体执行读取操作。

当读取操作应仅限于经过身份验证的用户时，应设置以下权限配置，导致拒绝未经身份验证的请求：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "authenticated",
    "actions": [ "read" ]
  }]
}

实体不需要且未预配置和authenticated角色的权限anonymous。 可以在实体的权限配置中定义一个或多个用户角色，并且所有其他未定义的角色、系统或用户定义的角色将自动被拒绝访问。

在以下示例中，用户角色 administrator 是实体的唯一 book 定义角色。 用户必须是角色的成员， administrator 并将该角色包含在 HTTP 标头中 X-MS-API-ROLE ，才能对 book 实体进行操作：

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

注意

若要在将数据 API 生成器与 Azure Cosmos DB 配合使用时对GraphQL查询强制实施访问控制，需要在提供的 GraphQL 架构文件中使用 @authorize 指令。 但是，对于GraphQL查询中的GraphQL突变和筛选器，访问控制仍由权限配置强制执行，如前所述。

操作

操作 描述角色范围内实体的可访问性。 可以单独指定操作，也可以使用通配符快捷方式指定操作： * (星号) 。 通配符快捷方式表示实体类型支持的所有操作：

  • 表和视图： create、 read、 update、 delete
  • 存储过程： execute

有关操作的详细信息，请参阅 配置文件 文档。

字段访问

可以配置操作应可访问的字段。 例如，可以设置要 从操作中包括 和 排除 的 read 字段。

以下示例阻止角色中的 free-access 用户对 Column3执行读取操作。 Column3在 GET 请求 (REST 终结点) 或查询 (GraphQL 终结点) 中对 的引用会导致请求被拒绝：

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

注意

若要在将数据 API 生成器与 Azure Cosmos DB 配合使用时对GraphQL查询强制实施访问控制，需要在提供的 GraphQL 架构文件中使用 @authorize 指令。 但是，对于GraphQL查询中的GraphQL突变和筛选器，访问控制仍由权限配置强制执行，如此处所述。

项目级别安全性

数据库策略 表达式允许进一步限制结果。 数据库策略将表达式转换为对数据库执行的查询谓词。 以下操作支持数据库策略表达式：

  • create
  • 读取
  • update
  • 删除

警告

与存储过程一起使用 的 execute 操作 不支持 数据库策略。

注意

CosmosDB for NoSQL 目前不支持数据库策略。

有关数据库策略的详细信息，请参阅 配置文件 文档。

示例

数据库策略，将角色上的 read 操作 consumer 限制为仅返回 标题 为“示例标题”的记录。

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

相关内容