From f33d042391b0a8ebc797a8dd4c5ccc5688762252 Mon Sep 17 00:00:00 2001 From: ashwini-orchestral Date: Tue, 19 Oct 2021 15:43:53 +0000 Subject: [PATCH 1/2] Added section to describe the RBAC behavior for key value pairs --- .../_includes/available_permission_types.rst | 22 ++++--- .../runner_parameters/quick_reference.rst | 2 +- docs/source/rbac.rst | 58 ++++++++++++++++++- 3 files changed, 71 insertions(+), 11 deletions(-) diff --git a/docs/source/_includes/available_permission_types.rst b/docs/source/_includes/available_permission_types.rst index e56c7aa2d..ce19001d5 100644 --- a/docs/source/_includes/available_permission_types.rst +++ b/docs/source/_includes/available_permission_types.rst @@ -150,15 +150,19 @@ Api Key Key Value Pair ~~~~~~~~~~~~~~ -+---------------------------+-----------------------------------------------+ -| Permission name | Description | -+===========================+===============================================+ -| **key_value_pair_view** | Ability to view Key-Value Pairs. | -+---------------------------+-----------------------------------------------+ -| **key_value_pair_set** | Ability to set a Key-Value Pair. | -+---------------------------+-----------------------------------------------+ -| **key_value_pair_delete** | Ability to delete an existing Key-Value Pair. | -+---------------------------+-----------------------------------------------+ ++---------------------------+----------------------------------------------------------------------+ +| Permission name | Description | ++===========================+======================================================================+ +| **key_value_pair_list** | Ability to list (view all) Key-Value Pairs. | ++---------------------------+----------------------------------------------------------------------+ +| **key_value_pair_view** | Ability to view Key-Value Pairs. | ++---------------------------+----------------------------------------------------------------------+ +| **key_value_pair_set** | Ability to set a Key-Value Pair. | ++---------------------------+----------------------------------------------------------------------+ +| **key_value_pair_delete** | Ability to delete an existing Key-Value Pair. | ++---------------------------+----------------------------------------------------------------------+ +| **key_value_pair_all** | Ability to perform all the supported operations on a Key-Value Pair. | ++---------------------------+----------------------------------------------------------------------+ Rule ~~~~ diff --git a/docs/source/_includes/runner_parameters/quick_reference.rst b/docs/source/_includes/runner_parameters/quick_reference.rst index 1950f5e23..b224a491d 100644 --- a/docs/source/_includes/runner_parameters/quick_reference.rst +++ b/docs/source/_includes/runner_parameters/quick_reference.rst @@ -1,4 +1,4 @@ -.. table:: +.. table:: +--------------+-------------------+---------------------+-------------------+---------------------+---------------------+---------------------+---------------------+ | Runner | local-shell-cmd | local-shell-script | remote-shell-cmd | remote-shell-script | winrm-cmd | winrm-ps-cmd | winrm-ps-script | diff --git a/docs/source/rbac.rst b/docs/source/rbac.rst index 530754f98..40fad9415 100644 --- a/docs/source/rbac.rst +++ b/docs/source/rbac.rst @@ -138,11 +138,12 @@ Permission grants can be applied to the following resource types: * executions * webhooks * inquiries +* key value pair A resource is identified by a ``uid``, and referenced as such in permission grants. UID is an identifier which is unique for each resource in the |st2| installation. UIDs follow this format: ``:`` (e.g. ``pack:libcloud``, -``action:libcloud:list_vms``, etc.). +``action:libcloud:list_vms``, ``key_value_pair:st2kv.system:key1``, ``key_value_pair:st2kv.user:key2`` etc.). You can retrieve the UID of a particular resource by listing all the resources of a particular type or by retrieving details of a single resource using either API or CLI. @@ -702,3 +703,58 @@ Lets take this for a spin using the |st2| CLI. # Expect failure $ st2 action get core.local $ st2 run core.local hostname + +Applying RBAC to Key Value Pair +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Note + +This functionality is only available in |st2| v3.6.0 and above. + +|st2| offers functionality to apply RBAC to KeyValuePair by invoking API and granting permission depending on the user logged in. +Prior to 3.6 release, RBAC was not implemented to KeyValuePair. + +By default, user has access to his/her own user scoped KVPs without requiring specific permission grant. +A non-admin user can explicitly grant permission to one or more system scoped KVPs. +A non-admin user cannot access another user's KVPs. +By default, admin and system_admin has ALL access to system scoped KVPs. +Admin has full access to another user's KVPs (behavior in current version). + +Apart from role creation, follow the same steps as mentioned in RBAC example. + +Need to do some change in resource_uid to set role for KeyValuePair - +Follow below example for system scope - + +Create ``/opt/stackstorm/rbac/roles/key_value_pair_set.yaml`` with the +following content: + +.. sourcecode:: yaml + + --- + name: "key_value_pair_set" + description: "Owner of key value pair example" + enabled: true + permission_grants: + - + resource_uid: "key_value_pair:st2kv.system:key1" + permission_types: + - "key_value_pair_set" + +Follow below example for user scope - + +Create ``/opt/stackstorm/rbac/roles/key_value_pair_view.yaml`` with the +following content: + +.. sourcecode:: yaml + + --- + name: "key_value_pair_view" + description: "Owner of key value pair example" + enabled: true + permission_grants: + - + resource_uid: "key_value_pair:st2kv.user:user1:key1" + permission_types: + - "key_value_pair_view" + + + From 047acc62cd66c61fa48065a02fb188f1fa769163 Mon Sep 17 00:00:00 2001 From: W Chan Date: Fri, 10 Dec 2021 21:59:57 +0000 Subject: [PATCH 2/2] Minor change to organization and wording to KVP section in RBAC Move the KVP section in the same RBAC page so the flow makes more sense. Change the supported version from v3.6.0 to v3.7.0. Reword the KVP section for accuracy and readability. --- .../_includes/available_permission_types.rst | 2 + docs/source/rbac.rst | 92 +++++++------------ 2 files changed, 37 insertions(+), 57 deletions(-) diff --git a/docs/source/_includes/available_permission_types.rst b/docs/source/_includes/available_permission_types.rst index 6de77e980..db662374a 100644 --- a/docs/source/_includes/available_permission_types.rst +++ b/docs/source/_includes/available_permission_types.rst @@ -56,6 +56,8 @@ Global +----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ | **execution_views_filters_list** | Ability view all the distinct execution filters. | +----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| **key_value_pair_list** | Ability to list (view all) Key-Value Pairs. | ++----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ | **webhook_list** | Ability to list (view all) webhooks. | +----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------+ | **timer_list** | Ability to list (view all) timers. | diff --git a/docs/source/rbac.rst b/docs/source/rbac.rst index 40fad9415..c0a5ee618 100644 --- a/docs/source/rbac.rst +++ b/docs/source/rbac.rst @@ -138,7 +138,10 @@ Permission grants can be applied to the following resource types: * executions * webhooks * inquiries -* key value pair +* key value pairs + +.. note:: + The support of key value pairs is only available in |st2| v3.7.0 and above. A resource is identified by a ``uid``, and referenced as such in permission grants. UID is an identifier which is unique for each resource in the |st2| installation. UIDs follow this format: @@ -228,7 +231,6 @@ There are some exceptions, described below: ``/aliasexecutions/``) using hubot is the |st2| user that is configured in hubot (``ST2_AUTH_USERNAME`` - by default that is ``chatops_bot``). - Enabling RBAC ------------- @@ -311,6 +313,37 @@ In the example above we assign two roles to the user named ``user4``: * ``role_one`` (a custom role which needs to be defined as described above) and * ``observer`` (system role). +Key Value Pairs +~~~~~~~~~~~~~~~ + +.. note:: + This functionality is only available in |st2| v3.7.0 and above. + +Users with admin and system_admin roles have all access to system scoped KVPs. In v3.6.0 +and before, users with admin role have full access to other users' KVPs. This behavior is +unchanged. + +By default, a user has access to his/her own user scoped KVPs without requiring specific +permission grants. A non-admin user by default cannot access system scoped KVPs or other +users' KVPs. A non-admin user can be explicitly granted permission to one or more system +scoped KVPs similar to how access to other resources are granted to users. Currently, +there is no option or plan to grant non-admin user access to another user's set of KVPs. + +The following is an example to assign a ``system scoped`` KVP to a role. +Create ``/opt/stackstorm/rbac/roles/key1_write_role.yaml`` with the +following content. Assign this role to a user and then apply the RBAC definitions. + +.. sourcecode:: yaml + + --- + name: key1_write_role + description: Role that allow users to set system key1 + enabled: true + permission_grants: + - resource_uid: "key_value_pair:st2kv.system:key1" + permission_types: + - "key_value_pair_set" + Applying RBAC Definitions ------------------------- @@ -703,58 +736,3 @@ Lets take this for a spin using the |st2| CLI. # Expect failure $ st2 action get core.local $ st2 run core.local hostname - -Applying RBAC to Key Value Pair -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note - -This functionality is only available in |st2| v3.6.0 and above. - -|st2| offers functionality to apply RBAC to KeyValuePair by invoking API and granting permission depending on the user logged in. -Prior to 3.6 release, RBAC was not implemented to KeyValuePair. - -By default, user has access to his/her own user scoped KVPs without requiring specific permission grant. -A non-admin user can explicitly grant permission to one or more system scoped KVPs. -A non-admin user cannot access another user's KVPs. -By default, admin and system_admin has ALL access to system scoped KVPs. -Admin has full access to another user's KVPs (behavior in current version). - -Apart from role creation, follow the same steps as mentioned in RBAC example. - -Need to do some change in resource_uid to set role for KeyValuePair - -Follow below example for system scope - - -Create ``/opt/stackstorm/rbac/roles/key_value_pair_set.yaml`` with the -following content: - -.. sourcecode:: yaml - - --- - name: "key_value_pair_set" - description: "Owner of key value pair example" - enabled: true - permission_grants: - - - resource_uid: "key_value_pair:st2kv.system:key1" - permission_types: - - "key_value_pair_set" - -Follow below example for user scope - - -Create ``/opt/stackstorm/rbac/roles/key_value_pair_view.yaml`` with the -following content: - -.. sourcecode:: yaml - - --- - name: "key_value_pair_view" - description: "Owner of key value pair example" - enabled: true - permission_grants: - - - resource_uid: "key_value_pair:st2kv.user:user1:key1" - permission_types: - - "key_value_pair_view" - - -