oslo_policy 包

子模块

oslo_policy.fixture 模块

class oslo_policy.fixture.HttpCheckFixture(return_value=True)

基础: Fixture

帮助短路外部 http 调用

setUp()

准备 Fixture 以供使用。

不应覆盖此方法。具体的 fixture 应该实现 _setUp。仍然支持覆盖 setUp，但不推荐。

在 setUp 完成后，fixture 将具有一个或多个属性，这些属性可用于（具体取决于具体的子类）。

引发:

如果 _setUp 失败，则引发 MultipleExceptions。MultipleExceptions 中捕获的最后一个异常将是一个 SetupError 异常。

返回值:

None。

更改于 1.3:

覆盖 setUp 的建议已反转 - 在 1.3 之前，应该覆盖 setUp()，现在不应该覆盖。

更改于 1.3.1:

现在捕获 BaseException，并且只有 Exception 的子类才会被包装在 MultipleExceptions 中。

class oslo_policy.fixture.HttpsCheckFixture(return_value=True)

基础: Fixture

帮助短路外部 http 调用

setUp()

准备 Fixture 以供使用。

不应覆盖此方法。具体的 fixture 应该实现 _setUp。仍然支持覆盖 setUp，但不推荐。

在 setUp 完成后，fixture 将具有一个或多个属性，这些属性可用于（具体取决于具体的子类）。

引发:

如果 _setUp 失败，则引发 MultipleExceptions。MultipleExceptions 中捕获的最后一个异常将是一个 SetupError 异常。

返回值:

None。

更改于 1.3:

覆盖 setUp 的建议已反转 - 在 1.3 之前，应该覆盖 setUp()，现在不应该覆盖。

更改于 1.3.1:

现在捕获 BaseException，并且只有 Exception 的子类才会被包装在 MultipleExceptions 中。

oslo_policy.generator 模块

oslo_policy.generator.convert_policy_json_to_yaml(args=None, conf=None)
oslo_policy.generator.generate_policy(args=None)
oslo_policy.generator.generate_sample(args=None, conf=None)
oslo_policy.generator.get_policies_dict(namespaces)

查找给定命名空间中可用的选项。

参数：

namespaces – 注册在 ‘oslo.policy.policies’ 下的命名空间列表

返回值:

一个 {namespace1: [rule_default_1, rule_default_2], namespace2: [rule_default_3]…} 字典

oslo_policy.generator.list_redundant(args=None)
oslo_policy.generator.on_load_failure_callback(*args, **kwargs)
oslo_policy.generator.upgrade_policy(args=None, conf=None)
oslo_policy.generator.validate_policy(args=None)

oslo_policy.opts 模块

oslo_policy.opts.list_opts()

返回库中可用的 oslo.config 选项列表。

返回的列表包含库在运行时可能注册的所有 oslo.config 选项。列表中的每个元素都是一个元组。第一个元素是将在配置文件中注册元素的组的名称。组名称为 None 对应于配置文件中的 [DEFAULT] 组。此函数还可以通过 ‘oslo_messaging’ 入口点在 ‘oslo.config.opts’ 命名空间下发现。其目的是允许像 Oslo 示例配置文件生成器这样的工具发现此库向用户公开的选项。

返回值:

一个 (group_name, opts) 元组列表

oslo_policy.opts.set_defaults(conf, policy_file=None, **kwargs)

设置配置变量的默认值。

覆盖默认选项值。

参数：

  • conf (oslo.config.cfg.ConfigOpts) – 配置对象，由调用者管理。

  • policy_file (unicode) – 定义策略的文件名的基本名称。

  • kwargs – 任何其他配置变量及其新的默认值。

oslo_policy.policy 模块

通用策略引擎实现

策略表示为目标和关联规则

"<target>": <rule>

目标 特定于执行策略强制的服务。通常，目标指的是 API 调用。

对于 <rule> 部分，请参阅 策略规则表达式。

策略规则表达式

策略规则可以以两种形式表示：用新策略语言编写的字符串或列表的列表。首选字符串格式，因为它更容易被大多数人理解。

在策略语言中，每个检查都指定为简单的“a:b”对，该对与正确的类匹配以执行该检查

类型

语法

用户角色

role:admin

已在策略中定义的规则

rule:admin_required

针对 URL¹

http://my-url.org/check

用户属性²

project_id:%(target.project.id)s

字符串

  • <variable>:’xpto2035abc’

  • ‘myproject’:<variable>

字面量

  • project_id:xpto2035abc

  • domain_id:20

  • True:%(user.enabled)s

¹URL 检查必须返回 True 才能有效

²用户属性（通过令牌获得）：user_id、domain_id 或 project_id

可以使用逻辑运算符 and 和 or，从而在制定策略时提供更大的灵活性。例如

"role:admin or (project_id:%(project_id)s and role:projectadmin)"

策略语言还具有 not 运算符，从而允许更丰富的策略规则

"project_id:%(project_id)s and not role:dunce"

运算符优先级如下

优先级

类型

表达式

4

分组

(…)

3

逻辑非

not …

2

逻辑与

… and …

1

逻辑或

… or …

优先级较高的运算符优先于优先级较低的运算符。

在列表的列表表示形式中，最内层列表中的每个检查都组合为“and”连接 – 要使该检查通过，必须通过所有指定的检查。然后，这些最内层列表组合为“or”连接。例如，以下规则以列表的列表形式表示

[["role:admin"], ["project_id:%(project_id)s", "role:projectadmin"]]

最后，应该提到两个特殊的策略检查；“@”策略检查将始终接受访问，而“！”策略检查将始终拒绝访问。（请注意，如果规则是空列表 ([]) 或空字符串 ("")，则这等效于“@”策略检查。）其中，“！”策略检查可能最有用，因为它允许明确禁用特定的规则。

通用检查

通用 检查用于针对与 API 调用一起发送的属性进行匹配。这些属性可用于策略引擎（表达式的右侧），方法是使用以下语法

<some_attribute>:%(user.id)s

右侧的值是字符串或使用 Python 字符串替换解析为字符串。可用的属性和值取决于使用通用策略引擎的程序。

所有这些属性（与用户、API 调用和上下文相关）都可以相互检查或与常量进行检查。重要的是要注意，这些属性特定于执行策略强制的服务。

通用检查可用于对通过令牌获得的以下用户属性执行策略检查

  • user_id

  • domain_id 或 project_id（取决于令牌范围）

  • 给定令牌范围所持有的角色列表

注意

一些由 API 公开的资源不支持按 user_id 强制执行策略，仅支持按 project_id 强制执行策略。一些全局资源不支持按 user_id 和 project_id 的组合强制执行策略。

例如，对 user_id 的检查定义如下

user_id:<some_value>

结合前面显示的示例，完整的通用检查将是

user_id:%(user.id)s

还可以对代表凭据的其他属性执行检查。这通过将其他值添加到传递给 enforce() 方法的 creds 字典中来实现。

特殊检查

特殊检查允许比使用通用检查更大的灵活性。内置的特殊检查类型是 role、rule 和 http 检查。

角色检查

role 检查用于检查提供的凭据中是否存在特定角色。角色检查表示为

"role:<role_name>"

规则检查

rule check 用于通过其名称引用另一个定义的规则。这允许将公共检查定义一次作为可重用的规则，然后在其他规则中引用。它还允许将一组检查定义为更具描述性的名称，以帮助提高策略的可读性。规则检查表示为

"rule:<rule_name>"

以下示例显示了一个定义为规则的角色检查，然后通过规则检查使用

"admin_required": "role:admin"
"<target>": "rule:admin_required"

HTTP 检查

http 检查用于向远程服务器发出 HTTP 请求以确定检查的结果。目标和凭据传递给远程服务器进行评估。如果远程服务器返回 True 的响应，则授权该操作。http 检查表示为

"http:<target URI>"

预计目标 URI 包含字符串格式化关键字，其中关键字是目标字典中的键。使用 name 键从目标构造 URL 的 http 检查示例定义如下

"http://server.test/%(name)s"

注册新的特殊检查

还可以使用 register() 函数注册其他特殊检查类型。

可以使用以下类作为自定义特殊检查类型的父类

默认规则

可以定义一个默认规则，当检查的目标不存在规则时，将强制执行该规则。默认情况下，与规则名称 default 关联的规则将用作默认规则。可以通过将 policy_default_rule 配置设置设置为所需的规则名称来使用不同的规则名称作为默认规则。

class oslo_policy.policy.AndCheck(rules)

基类: BaseCheck

add_check(rule)

添加要测试的规则。

允许将另一个规则添加到将要测试的规则列表中。

返回值:

self

返回类型:

AndCheck

class oslo_policy.policy.Check(kind, match)

基类: BaseCheck

class oslo_policy.policy.DeprecatedRule(name: str, check_str: str, *, deprecated_reason: str | None = None, deprecated_since: str | None = None)

基类: _BaseRule

表示已弃用的策略或规则。

以下是如何使用它来更改策略的默认角色或规则。假设以下策略存在于代码中

from oslo_policy import policy

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:fizz',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}]
)

下一个片段将保留弃用选项，但允许 foo:create_bar 默认使用 role:bang 而不是 role:fizz

deprecated_rule = policy.DeprecatedRule(
    name='foo:create_bar',
    check_str='role:fizz'
    deprecated_reason='role:bang is a better default',
    deprecated_since='N',
)

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:bang',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}],
    deprecated_rule=deprecated_rule,
)

DeprecatedRule 可用于更改策略名称本身。假设以下策略存在于代码中

from oslo_policy import policy

policy.DocumentedRuleDefault(
    name='foo:post_bar',
    check_str='role:fizz',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}]
)

为了保持一致性，假设我们要将 foo:post_bar 替换为 foo:create_bar，但保留与默认值相同的 check_str。我们可以通过执行以下操作来实现

deprecated_rule = policy.DeprecatedRule(
    name='foo:post_bar',
    check_str='role:fizz'
    deprecated_reason='foo:create_bar is more consistent',
    deprecated_since='N',
)

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:fizz',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}],
    deprecated_rule=deprecated_rule,
)

最后，让我们使用 DeprecatedRule 将策略分解为更细粒度的策略。假设以下策略存在于代码中

policy.DocumentedRuleDefault(
    name='foo:bar',
    check_str='role:bazz',
    description='Create, read, update, or delete a bar.',
    operations=[
        {
            'path': '/v1/bars',
            'method': 'POST'
        },
        {
            'path': '/v1/bars',
            'method': 'GET'
        },
        {
            'path': '/v1/bars/{bar_id}',
            'method': 'GET'
        },
        {
            'path': '/v1/bars/{bar_id}',
            'method': 'PATCH'
        },
        {
            'path': '/v1/bars/{bar_id}',
            'method': 'DELETE'
        }
    ]
)

我们可以在这里看到相同的策略用于保护 bars 上的多个操作。这会阻止操作员能够为可以对 bar 执行的不同操作分配不同的角色。例如，如果操作员希望需要较不严格的角色或规则来列出 bars，但需要更严格的规则来删除它们会怎样？以下将引入一个有助于实现这一目标的策略，并弃用原始的、过于宽泛的策略

deprecated_rule = policy.DeprecatedRule(
    name='foo:bar',
    check_str='role:bazz'
    deprecated_reason=(
        'foo:bar has been replaced by more granular policies'
    ),
    deprecated_since='N',
)

policy.DocumentedRuleDefault(
    name='foo:create_bar',
    check_str='role:bang',
    description='Create a bar.',
    operations=[{'path': '/v1/bars', 'method': 'POST'}],
    deprecated_rule=deprecated_rule,
)
policy.DocumentedRuleDefault(
    name='foo:list_bars',
    check_str='role:bazz',
    description='List bars.',
    operations=[{'path': '/v1/bars', 'method': 'GET'}],
    deprecated_rule=deprecated_rule,
)
policy.DocumentedRuleDefault(
    name='foo:get_bar',
    check_str='role:bazz',
    description='Get a bar.',
    operations=[{'path': '/v1/bars/{bar_id}', 'method': 'GET'}],
    deprecated_rule=deprecated_rule,
)
policy.DocumentedRuleDefault(
    name='foo:update_bar',
    check_str='role:bang',
    description='Update a bar.',
    operations=[{'path': '/v1/bars/{bar_id}', 'method': 'PATCH'}],
    deprecated_rule=deprecated_rule,
)
policy.DocumentedRuleDefault(
    name='foo:delete_bar',
    check_str='role:bang',
    description='Delete a bar.',
    operations=[{'path': '/v1/bars/{bar_id}', 'method': 'DELETE'}],
    deprecated_rule=deprecated_rule,
)
参数：

  • name – 策略的名称。在从另一个规则或在策略执行期间引用它时使用。

  • check_str – 策略。这是一个字符串，定义符合文件顶部概述的策略语言的策略。

  • deprecated_reason – 指示计划在未来版本中删除此策略的原因。

  • deprecated_since – 指示弃用此策略的版本。接受任何字符串，但鼓励使用有效的版本字符串。

版本 1.29 中更改： 添加了 DeprecatedRule 对象。

版本 3.4 中更改： 添加了 deprecated_reason 参数。

版本 3.4 中更改： 添加了 deprecated_since 参数。

property deprecated_reason
property deprecated_since
class oslo_policy.policy.DocumentedRuleDefault(name, check_str, description, operations, deprecated_rule=None, deprecated_for_removal=False, deprecated_reason=None, deprecated_since=None, scope_types=None)

基类: RuleDefault

用于保存代码中策略对象定义的类

此类提供与 RuleDefault 类相同的功能，但它还需要有关正在注册的策略规则的其他数据。这是必要的，以便可以根据此类的属性呈现适当的文档。最终，RuleDefault 的所有使用都应转换为使用 DocumentedRuleDefault。

参数：

operations –

包含每个 API URL 及其相应 http 请求方法的字典列表。

示例

operations=[{'path': '/foo', 'method': 'GET'},
            {'path': '/some', 'method': 'POST'}]

property description
property operations
exception oslo_policy.policy.DuplicatePolicyError(name)

基础: Exception

class oslo_policy.policy.Enforcer(conf, policy_file=None, rules=None, default_rule=None, use_conf=True, overwrite=True, fallback_to_json_file=True)

基类: object

负责加载和执行规则。

参数：

  • conf – 一个配置对象。

  • policy_file – 要使用的自定义策略文件，如果未指定，将使用 conf.oslo_policy.policy_file。

  • rules – 默认字典 / 要使用的规则。它仅在第一次实例化时会被考虑。如果调用 load_rules() 时 force_reload=True，或者调用 clear() 或 set_rules() 时 overwrite=True，则将被覆盖。

  • default_rule – 要使用的默认规则，如果未指定，将使用 conf.default_rule。

  • use_conf – 是否从缓存或配置文件加载规则。

  • overwrite – 是否覆盖从配置文件重新加载规则时现有的规则。

authorize(rule, target, creds, do_raise=False, exc=None, *args, **kwargs)

围绕“enforce”的包装器，用于检查策略注册。

为了确保正在检查的策略已注册，应使用此方法而不是 enforce。通过这样做，项目可以确保其使用的所有策略都已注册，因此可用于示例文件生成。

参数与 enforce 方法匹配，并且可以在那里找到它们的描述。

check_rules(raise_on_violation=False)

查找明显不正确的规则定义。

clear()

清除 Enforcer 内容。

这将清除此实例的规则、策略缓存、文件缓存和策略路径。

enforce(rule, target, creds, do_raise=False, exc=None, *args, **kwargs)

检查规则相对于目标和凭据的授权。

参数：

  • rule – 要评估的规则，为字符串或 BaseCheck。

  • target – 关于正在操作的对象的尽可能多的信息。target 参数应为 dict 实例或完全支持 Mapping 抽象基类的类的实例。

  • creds – 关于执行操作的用户尽可能多的信息。此参数也可以是 oslo_context.context.RequestContext 的实例。

  • do_raise – 如果检查失败，是否引发异常。

  • exc – 如果检查失败，要引发的异常的类。传递给 enforce() 的所有剩余参数（位置参数和关键字参数）都将传递给异常类。如果未指定，将使用 PolicyNotAuthorized。

返回值:

False 如果策略不允许该操作，并且未提供 exc；否则，返回一个评估为 True 的值。注意：对于使用“case”表达式的规则，此 True 值将是表达式中指定的字符串。

load_rules(force_reload=False)

加载 policy_path 的规则。

策略文件被缓存，如果修改则会被重新加载。

参数：

force_reload – 是否从配置文件重新加载规则。

register_default(default)

注册一个 RuleDefault。

将 RuleDefault 添加到已注册规则的列表中。必须在注册规则后才能使用 Enforcer.authorize 方法。

参数：

default – 要注册的 RuleDefault 对象。

register_defaults(defaults)

注册一个 RuleDefaults 列表。

将每个 RuleDefault 添加到已注册规则的列表中。必须在注册规则后才能使用 Enforcer.authorize 方法。

参数：

default – 要注册的 RuleDefault 对象列表。

set_rules(rules, overwrite=True, use_conf=False)

基于提供的规则字典创建一个新的 Rules。

参数：

  • rules – 要使用的新规则。

  • overwrite – 是否覆盖当前规则或使用新规则更新它们。

  • use_conf – 是否从缓存或配置文件重新加载规则。

exception oslo_policy.policy.InvalidContextObject(error)

基础: Exception

exception oslo_policy.policy.InvalidDefinitionError(names)

基础: Exception

exception oslo_policy.policy.InvalidRuleDefault(error)

基础: Exception

exception oslo_policy.policy.InvalidScope(rule, operation_scopes, token_scope)

基础: Exception

当请求的范围与策略范围不匹配时引发。

class oslo_policy.policy.NotCheck(rule)

基类: BaseCheck

class oslo_policy.policy.OrCheck(rules)

基类: BaseCheck

add_check(rule)

添加要测试的规则。

允许将另一个规则添加到将要测试的规则列表中。为了方便起见，返回 OrCheck 对象。

pop_check()

从列表中弹出最后一个检查并返回它们

返回值:

self，弹出的检查

返回类型:

OrCheck，类：.Check

exception oslo_policy.policy.PolicyNotAuthorized(rule, target, creds)

基础: Exception

策略执行失败时引发的默认异常。

exception oslo_policy.policy.PolicyNotRegistered(name)

基础: Exception

class oslo_policy.policy.RuleCheck(kind, match)

基类：Check

class oslo_policy.policy.RuleDefault(name, check_str, description=None, deprecated_rule=None, deprecated_for_removal=False, deprecated_reason=None, deprecated_since=None, scope_types=None)

基类: _BaseRule

用于保存策略定义的一个类。

在创建时需要提供名称和值。鼓励也提供描述以帮助操作员。

参数：

  • name – 策略的名称。在从另一个规则或在策略执行期间引用它时使用。

  • check_str – 策略。这是一个字符串，定义符合文件顶部概述的策略语言的策略。

  • description – 策略的纯文本描述。这将用于注释部署者使用的示例策略文件。

  • deprecated_rule – DeprecatedRule

  • deprecated_for_removal – 指示该策略是否计划在未来的版本中删除。

  • deprecated_reason – 指示为什么该策略计划在未来的版本中删除。如果 deprecated_for_removal 为 False，则会被静默忽略。

  • deprecated_since – 指示该策略在哪个版本中被弃用。接受任何字符串，但鼓励使用有效的版本字符串。如果 deprecated_for_removal 为 False，则会被静默忽略。

  • scope_types – 包含正在执行的操作的预期范围的列表。

版本 1.29 中更改： 添加了 deprecated_rule 参数。

版本 1.29 中更改： 添加了 deprecated_for_removal 参数。

版本 1.29 中更改： 添加了 deprecated_reason 参数。

版本 1.29 中更改： 添加了 deprecated_since 参数。

版本 1.31 中更改： 添加了 scope_types 参数。

property deprecated_for_removal
property deprecated_reason
property deprecated_rule
property deprecated_since
property description
class oslo_policy.policy.Rules(rules=None, default_rule=None)

基础: dict

规则的存储。直接处理 default_rule 设置。

classmethod from_dict(rules_dict, default_rule=None)

允许从字典加载规则数据。

classmethod load(data, default_rule=None)

允许加载 YAML/JSON 规则数据。

在版本 1.5.0 中添加。

classmethod load_json(data, default_rule=None)

允许加载 YAML/JSON 规则数据。

警告

此方法在版本 1.5.0 中已弃用，以支持 load()，并且可能在 2.0 版本中删除。

oslo_policy.policy.parse_file_contents(data)

解析策略文件的原始内容。

解析策略文件的内容，目前可以采用 YAML 或 JSON 格式。两者都可以解析为 YAML。

参数：

data – 包含策略文件内容的字符串。

返回值:

一个字典，形式为 {'policy_name1': 'policy1', 'policy_name2': 'policy2,...}

oslo_policy.policy.pick_default_policy_file(conf, fallback_to_json_file=True)
oslo_policy.policy.register(name, func=None)

将函数或 Check 类注册为策略检查。

参数：

  • name – 提供检查类型的名称，例如“rule”、“role”等。如果 name 为 None，则将注册默认检查类型。

  • func – 如果提供，则提供要注册的函数或类。如果未提供，则将其作为装饰器使用，以便指定要注册的函数或类。

oslo_policy.shell 模块

class oslo_policy.shell.FakeEnforcer(rules, config)

基类: object

oslo_policy.shell.flatten(d, parent_key='')

展平嵌套字典

将具有嵌套值的字典转换为单层扁平字典，每个键都带有点符号。

oslo_policy.shell.main()
oslo_policy.shell.tool(policy_file, access_file, apply_rule, is_admin=False, target_file=None, enforcer_config=None)

oslo_policy.sphinxext 模块

用于美观格式化策略文档的 Sphinx 扩展。

class oslo_policy.sphinxext.ShowPolicyDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

基类: Directive

has_content = False

指令是否可以包含内容？

option_spec = {'config-file': <function unchanged>}

选项名称到验证器函数的映射。

run()
oslo_policy.sphinxext.setup(app)

oslo_policy.sphinxpolicygen 模块

生成示例策略文件。

oslo_policy.sphinxpolicygen.generate_sample(app)

生成示例策略文件。

oslo_policy.sphinxpolicygen.setup(app)

oslo_policy.version 模块

模块内容