添加策略文档¶

目前，操作员需要阅读代码才能完全理解特定的策略规则实际执行的操作。这给部署者和操作员带来了糟糕的用户体验。本规范旨在通过为每个策略规则添加非常详细的描述来解决这个问题。

问题描述¶

为了理解策略，需要详细了解项目的源代码。这导致操作员必须解析源代码才能审计默认策略规则，授予特定用户访问特定 API 的权限，或限制对特定 API 的访问。

提议的变更¶

为了确保操作员拥有做出策略决策所需的信息，我们应该实施以下措施

所有描述应使用 Identity API 文档中描述的实体的名称
我们应该以与 api-ref 中相同的方式声明策略规则影响的 API 的 URL，例如：DELETE /projects/{project_id}
我们应该确保文档在生成的策略文件中渲染良好，确保所有规则默认被注释掉

以下示例说明了将在示例策略文件中表示的内容

# List users
#
# GET /users/
#
# "identity:list_users": "rule:admin_required",

# Show details of a specific user
#
# GET /users/{user_id}
#
# "identity:get_user": "rule:admin_or_owner",

# Create a new user
#
# POST /users/
#
# "identity:create_user": "rule:admin_required",

# Create a trust relationship between two users
#
# POST OS-TRUST/trusts/
#
# "identity:create_trust": "user_id:%(trust.trustor_user_id)s",

例如，我们将从以下策略定义更新为

policy.RuleDefault(USERS % 'show', RULE_AOO),

更新为类似以下内容

policy.RuleDefault(
    USERS % 'show',
    RULE_AOO,
    description='Show details of a specific user',
    urls=[{method='GET', path='/users/{user_id}'}]
)

备选方案¶

我们可以尝试像过去那样记录策略文件中的所有信息，但那样更难维护，并且无法通过代码自动执行或强制执行。

安全影响¶

更好地理解每个规则的含义，只会帮助操作员和开发人员正确配置策略。

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

无

其他部署者影响¶

部署者现在能够生成一个包含为每个操作编写的良好描述的策略文件。

开发人员影响¶

开发人员在实现新的 API 或更改现有 API 的 RBAC 时，必须提供描述。我们可以添加 hacking 检查来确保自动捕获这些差距。

实现¶

负责人¶

主要负责人: Anthony Washington (antwash) Richard Avelar (ravelar)
其他贡献者: Lance Bragstad (lbragstad)

工作项¶

添加支持，使 oslo.policy 能够识别规则/操作描述并正确渲染它们
为每个策略规则添加文档
确保示例策略文件正确渲染
添加 hacking 检查，如果策略规则缺少预期的描述，则使其失败
确保所有管理员和安装指南引用包含渲染描述的策略文件

依赖项¶

这项工作需要实现代码中的策略。
这项工作还需要扩展 oslo.policy 库，以包含策略默认值的描述和渲染。

文档影响¶

通过这样做，我们将为操作员提供开箱即用的文档。我们需要确保所有安装指南和管理员指南引用包含渲染描述的策略文件。

参考资料¶

无

添加策略文档