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

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

确定用户的角色

没有 role 默认权限。 一旦规则由数据 API 生成器确定，为使请求成功，该实体的permissions必须为这个角色定义actions。

若要具有与 anonymous 或 authenticated 不同的角色，则需要使用 x-ms-api-role 标头。

系统角色

系统角色是数据 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 ，并将标头的值设置为所需的用户角色。

角色评估示例

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

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

在静态 Web 应用中， 用户默认是匿名角色的成员。 如果用户经过身份验证，则用户既是anonymous角色的成员，又是authenticated角色的成员。

当客户端应用向通过静态 Web 应用程序数据库连接（预览）部署的数据 API 生成器发送经过身份验证的请求时，客户端应用提供的访问令牌会被静态 Web 应用程序转换为 JSON：

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

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

如果客户端应用程序的请求还包括带有X-MS-API-ROLE值的author HTTP 标头，则请求将在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

权限

权限描述：

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

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

默认保护

默认情况下，实体没有配置任何权限，这意味着没有人可以访问该实体。 此外，数据 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" ]
  }]
}

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

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

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

行动

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

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

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

字段访问

可以配置哪些字段是可用于操作访问的。 例如，可以设置要从行动中包括和排除的字段。

以下示例阻止 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" ]
              }
            }
          ]
        }
      ]
    }

项目级安全性

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

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

示例：

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

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

相关内容

• Azure 身份验证
• 本地身份验证