Add RBAC policy admin guide.
This patch expands the RBAC policy guide to include information about the new scoped tokens and default roles. Change-Id: I12c1a9dacc8fef1ca991e14d143fa76b588eef07
This commit is contained in:
Michael Johnson
Erik Olof Gunnar Andersson
parent
5f87d207b4
commit
fa607f8f47
@ -1,6 +1,6 @@
|
||||
====================
|
||||
Policy Documentation
|
||||
====================
|
||||
==================
|
||||
Designate Policies
|
||||
==================
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -10,6 +10,135 @@ Policy Documentation
|
||||
|
||||
.. __: https://docs.openstack.org/oslo.policy/latest/cli/oslopolicy-convert-json-to-yaml.html
|
||||
|
||||
.. _oslo policy: https://docs.openstack.org/oslo.policy/latest/
|
||||
|
||||
.. _Keystone Default Roles: https://docs.openstack.org/keystone/latest/admin/service-api-protection.html
|
||||
|
||||
.. _Keystone Scoped Tokens: https://docs.openstack.org/keystone/latest/admin/tokens-overview.html#authorization-scopes
|
||||
|
||||
Designate, like most OpenStack services, supports Role Based Access Control
|
||||
(RBAC) using `oslo policy`_ to define default RBAC policies in the Designate
|
||||
code. These default policies can be overridden by operators using a yaml policy
|
||||
file. For a sample policy file, refer to :doc:`samples/policy-yaml`.
|
||||
|
||||
Currently Designate defaults to the OpenStack legacy "admin or owner" scheme,
|
||||
but Designate also supports a newer RBAC model using `Keystone Default Roles`_
|
||||
and `Keystone Scoped Tokens`_ via configuration settings.
|
||||
|
||||
Enabling Keystone Default Roles and Scoped Tokens
|
||||
-------------------------------------------------
|
||||
|
||||
Starting with the Xena release of Designate, Keystone token scopes and
|
||||
default roles can be enforced. By default, in the Xena release, `oslo policy`_
|
||||
will not be enforcing these new roles and scopes. However, at some point in the
|
||||
future they may become the default. You may want to enable them now to be ready
|
||||
for the later transition. This section will describe those settings.
|
||||
|
||||
The Oslo Policy project defines two configuration settings, among others, that
|
||||
can be set in the Designate configuration file to influence how policies are
|
||||
handled by Designate. Those two settings are `enforce_scope
|
||||
<https://docs.openstack.org/oslo.policy/latest/configuration/index.html#oslo_policy.enforce_scope>`_ and `enforce_new_defaults
|
||||
<https://docs.openstack.org/oslo.policy/latest/configuration/index.html#oslo_policy.enforce_new_defaults>`_.
|
||||
|
||||
When you enable `Keystone Default Roles`_ and `Keystone Scoped Tokens`_ the
|
||||
Designate policy honors the following roles:
|
||||
|
||||
* System scoped - Admin
|
||||
* System scoped - Reader
|
||||
* Project scoped - Reader
|
||||
* Project scoped - Member
|
||||
|
||||
[oslo_policy] enforce_scope
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Keystone has introduced the concept of `token scopes
|
||||
<https://docs.openstack.org/keystone/latest/admin/tokens-overview.html#authorization-scopes>`_.
|
||||
To ensure backward compatibility, Oslo Policy does not enforce scope validation
|
||||
of tokens by default.
|
||||
|
||||
In the Xena release, Designate supports enforcing Keystone token scopes. To
|
||||
enable Keystone token scoping, add the following to your Designate
|
||||
configuration file::
|
||||
|
||||
[oslo_policy]
|
||||
enforce_scope = True
|
||||
|
||||
The primary effect of this setting is to allow a system scoped admin token when
|
||||
performing administrative API calls to the Designate API. The Designate API
|
||||
already enforces the project scoping in Keystone tokens.
|
||||
|
||||
[oslo_policy] enforce_new_defaults
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Designate Xena release added support for `Keystone Default Roles`_ in
|
||||
the default policies.
|
||||
To be backward compatible, Oslo Policy currently uses deprecated policies
|
||||
that do not require the new `Keystone Default Roles`_ by default.
|
||||
|
||||
Designate supports requiring these new `Keystone Default Roles`_ as of
|
||||
the Xena release. To start requiring these roles in Designate, enable the new
|
||||
policies by adding the following setting to your Designate configuration file::
|
||||
|
||||
[oslo_policy]
|
||||
enforce_new_defaults = True
|
||||
|
||||
Example OpenStack Client Command
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
After you have enabled enforce_new_defaults and enforce_scope, administrative
|
||||
commands require a system scoped admin token. An example `OpenStack Client <https://docs.openstack.org/python-designateclient/latest/cli/index.html>`_ command
|
||||
to create a `Top Level Domain (TLD) <https://docs.openstack.org/designate/latest/admin/tlds.html>`_ would look like:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openstack --os-system-scope all --os-auth-url <identity endpoint URL> --os-password <admin password> --os-username admin --os-user-domain-name default create tld --name example.org
|
||||
|
||||
|
||||
Oslo Tools For Policy Management
|
||||
--------------------------------
|
||||
|
||||
This section describes how to use Oslo Policy tools to managing Designate
|
||||
policies.
|
||||
|
||||
Sample File Generation
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To generate a sample policy.yaml file from the Designate defaults, run the
|
||||
oslo policy generation script::
|
||||
|
||||
oslopolicy-sample-generator
|
||||
--config-file etc/designate/designate-policy-generator.conf
|
||||
--output-file policy.yaml.sample
|
||||
|
||||
Merged File Generation
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To generate a policy file which shows the effective policy in use by the
|
||||
project, including all registered policy defaults and the policy overrides
|
||||
included in a policy.yaml file, run this command::
|
||||
|
||||
oslopolicy-policy-generator
|
||||
--config-file etc/designate/designate-policy-generator.conf
|
||||
|
||||
This tool uses the output_file path from the config-file.
|
||||
|
||||
List Redundant Configurations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To generate a list of matches for policy rules that are defined in a
|
||||
configuration file where the rule does not differ from a registered default
|
||||
rule, run this command::
|
||||
|
||||
oslopolicy-list-redundant
|
||||
--config-file etc/designate/designate-policy-generator.conf
|
||||
|
||||
These are rules that can be removed from the policy file with no change
|
||||
in effective policy.
|
||||
|
||||
|
||||
Designate Default Policy Overview
|
||||
---------------------------------
|
||||
|
||||
The following is an overview of all available policies in Designate. For a
|
||||
sample configuration file, refer to :doc:`samples/policy-yaml`.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user