From aa5b2808a8198caa691b1aa1857b254116ad4713 Mon Sep 17 00:00:00 2001
From: Slawek Kaplonski <skaplons@redhat.com>
Date: Tue, 23 Jul 2024 18:10:55 +0200
Subject: [PATCH] [Docs] Add document with description of the RBAC roles

This patch adds short document with description of the roles supported
by the default Neutron's API policies.

Change-Id: Id8106478fc32cd2da283fa4b5763d535372127a6
---
 doc/source/admin/intro-api-srbac-policies.rst | 66 +++++++++++++++++++
 doc/source/admin/intro.rst                    |  1 +
 doc/source/configuration/policy.rst           |  2 +
 3 files changed, 69 insertions(+)
 create mode 100644 doc/source/admin/intro-api-srbac-policies.rst

diff --git a/doc/source/admin/intro-api-srbac-policies.rst b/doc/source/admin/intro-api-srbac-policies.rst
new file mode 100644
index 00000000000..b84017bddea
--- /dev/null
+++ b/doc/source/admin/intro-api-srbac-policies.rst
@@ -0,0 +1,66 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+Neutron API policies and supported roles
+========================================
+
+As part of the ``Consistent and Secure Default RBAC`` community goal [#]_
+Neutron implemented support for various scopes and personas in all of the API
+policies which are defined in the Neutron code.
+
+Roles supported by the default Neutron API policies
+---------------------------------------------------
+
+Roles supported by the default Neutron API policies are:
+
+* PROJECT_READER - this role is intented to have read only access to the
+  project owned resources.
+* PROJECT_MEMBER - this role inherits all of the privileges from the
+  PROJECT_READER role and also has access to ``create``, ``update`` and
+  ``delete`` project owned resources.
+* PROJECT_MANAGER - this role inherits all of the privileges from the
+  PROJECT_MEMBER role and additionally is allowed to do more operations on the
+  project owned resources.
+* ADMIN - this role is the same as it was in the "old" default policies. A user
+  with granted ADMIN role is allowed to do almost every possible modifications
+  on all resources, even those which belong to different projects.
+* SERVICE - this is a special role designed to be used for the service to
+  service communication only (like e.g. between nova and neutron), it doesn't
+  inherit any privileges from any other roles mentioned above.
+
+Default API policies defined in Neutron
+---------------------------------------
+
+By default all of the existing API policies can be used with the ``project``
+scoped tokens only. Tokens with ``service`` scope are not supported by any of
+the policies defined in Neutron code.
+
+Default API policies
+--------------------
+
+Default API policies defined in the Neutron code can be found in the
+:ref:`Policy Reference` document.
+
+References
+----------
+
+.. [#] https://governance.openstack.org/tc/goals/selected/consistent-and-secure-rbac.html
diff --git a/doc/source/admin/intro.rst b/doc/source/admin/intro.rst
index c24a61637f2..fbdc2716fcf 100644
--- a/doc/source/admin/intro.rst
+++ b/doc/source/admin/intro.rst
@@ -70,4 +70,5 @@ components:
    intro-network-namespaces
    intro-nat
    intro-os-networking
+   intro-api-srbac-policies
    fwaas
diff --git a/doc/source/configuration/policy.rst b/doc/source/configuration/policy.rst
index 616dd986aa6..07aa30b9650 100644
--- a/doc/source/configuration/policy.rst
+++ b/doc/source/configuration/policy.rst
@@ -1,3 +1,5 @@
+.. _Policy Reference:
+
 ================
 Policy Reference
 ================