STAC-22208: make separation between standalone & rancher RBAC clearer

Author: fvlankvelt

setup/security/authentication/oidc.md

@@ -53,10 +53,10 @@ stackstate:
       secret: "<oidc-secret>"
       baseUrl: "<rancher-url>"
 ```
-You can override and extend some of the OIDC config for Rancher with the following fields:
-- `discoveryUri`
-- `redirectUri`
-- `customParams`
+You can override and extend the OIDC config for Rancher with the following fields:
+   * **discoveryUri** - URI that can be used to discover the OIDC provider. Normally also documented or returned when creating the client in the OIDC provider.
+   * **redirectUri** - Optional \(not in the example\): The URI where the login callback endpoint of SUSE Observability is reachable. Populated by default using the `stackstate.baseUrl`, but can be overridden. This must be a fully qualified URL that points to the `/loginCallback` path.
+   * **customParameters** - Optional map of key/value pairs that are sent to the OIDC provider as custom request parameters. Some OIDC providers require extra request parameters not sent by default.
 
 If you need to disable TLS verification due to a setup not using verifiable SSL certificates, you can disable SSL checks with some application config (don't use in production):
 ```yaml

setup/security/rbac/README.md

@@ -8,6 +8,10 @@ Access Management helps you manage who has access to the specific topology eleme
 
 RBAC is an authorization system that provides fine-grained access management of SUSE Observability resources, a clean and easy way to audit user privileges and to fix identified issues with access rights.
 
+There are two different ways to configure RBAC:
+* **Kubernetes RBAC** - Roles and RoleBindings are provisioned on both the cluster running SUSE Observability as well as any monitored cluster.  The supported way to do this is by using Rancher.
+* **Standalone RBAC** - Configuration is done via the SUSE Observability application itself.
+
 ## What can I do with RBAC?
 
 Here are some examples of what you can do with RBAC:
@@ -24,9 +28,7 @@ This depends a bit on how SUSE Observability is deployed.  Both modes of deploym
 ## More on RBAC configuration
 
 * [Rancher RBAC](rbac_rancher.md)
-* [Permissions](rbac_permissions.md)
-* [How to set up roles](rbac_roles.md)
-* [Scopes](rbac_scopes.md)
+* [Standalone RBAC](rbac_roles.md)
 * [How to configure authentication](../authentication/)
 
 

setup/security/rbac/rbac_permissions.md

@@ -6,6 +6,10 @@ description: SUSE Observability Self-hosted
 
 ## Overview
 
+{% hint style="warning" %}
+This page only applies to "Standalone RBAC".  Details on permissions in "Rancher RBAC" can be found in [Resource details](rbac_rancher.md#resource-details).
+{% endhint %}
+
 Permissions in SUSE Observability allow Administrators to manage the actions that each user or user group can perform inside SUSE Observability and the information that will be shown in their SUSE Observability UI. Only the feature set relevant to each user's active role will be presented. The actions, information and pages that a user doesn't have access to are simply not displayed in their SUSE Observability UI.
 
 {% hint style="info" %}

setup/security/rbac/rbac_rancher.md

@@ -4,7 +4,8 @@ description: SUSE Observability Self-hosted
 
 ## Overview
 
-The SUSE Rancher Prime Observability Extension allows RBAC configuration of users access in SUSE Observability.
+The SUSE Rancher Prime Observability Extension uses Kubernetes RBAC to grant access to Rancher users in SUSE Observability.
+If you do not use Rancher, look at [How to set up roles](rbac_roles.md) in a standalone installation.
 
 Two kinds of roles are used for accessing SUSE Observability:
 * A *scope role* (Observer) grants access to data - either all data in a SUSE Observability instance, data coming from a cluster, or just the data for a namespace.  This role is provisioned in a cluster to be observed.
@@ -20,13 +21,16 @@ The observer role grants a user the permission to read topology, metrics, logs a
 * **Cluster Observer** - grants access to all data coming from a Cluster.  This template can be used in the "Cluster Membership" section of the cluster configuration.
 * **Instance Observer** - grants access to all data in a SUSE Observability instance.  This template can be used on the Project that includes SUSE Observability itself.
 
+In order to use these observer roles, it is recommended that the following role is granted on the Project running SUSE Observability itself:
+* **Recommended Access** - has recommended permissions for using SUSE Observability.
+
 ### Instance roles
 
-There are four roles predefined in SUSE Observability:
+There are two roles predefined in SUSE Observability, allowing for configuring the system - setting up views, monitors, notitifications etcetera:
+As these concern "global" settings of SUSE Observability, these roles include access to all data in an observability instance.
 
-* **Recommended Access** - has recommended permissions for using SUSE Observability.
-* **Instance Troubleshooter** - has all permissions required to use SUSE Observability for troubleshooting, including the ability to enable/disable monitors, create custom views and use the Cli.  This role includes access to all data in an observability instance.
-* **Instance Administrator** - has full access to all views and has all permissions.  This role includes access to all data in an observability instance.
+* **Instance Troubleshooter** - has all permissions required to use SUSE Observability for troubleshooting, including the ability to enable/disable monitors, create custom views and use the Cli. 
+* **Instance Administrator** - has full access to all views and has all permissions.
 
 The permissions assigned to each predefined SUSE Observability role can be found below. For details of the different permissions and how to manage them using the `sts` CLI, see [Role based access control (RBAC) permissions](/setup/security/rbac/rbac_permissions.md)
 

setup/security/rbac/rbac_roles.md

@@ -273,6 +273,8 @@ suse-observability \
 suse-observability/suse-observability
 ```
 
+For details on the `topologyScope`, see [RBAC Scopes](rbac_scopes.md).
+
 ### Custom roles via the CLI
 
 To set up a new role called `development-troubleshooter`, which will allow the same permissions as the normal troubleshooter role, but only for the `dev-test` cluster, a new subject needs to be created. Further more this subject needs to be assigned the required set of permissions:

setup/security/rbac/rbac_scopes.md

@@ -2,23 +2,27 @@
 description: SUSE Observability Self-hosted
 ---
 
-# Scopes
+# Topology Scopes
 
-## How do scopes work?
+{% hint style="warning" %}
+The topology scopes discussed here only apply to a *Standalone RBAC* deployment.  See [Rancher RBAC](Rancher RBAC) for the available scopes in a *Rancher RBAC* deployment.
+{% endhint %}
 
-The scope is an [STQL query](../../../develop/reference/k8sTs-stql_reference.md) that's added as a prefix to every query executed in SUSE Observability. Whenever a user wants to select a view or pass a query in SUSE Observability, this prefix query is executed as a part of the user's query. This limits the results accordingly to match the user's role.
+## How do topology scopes work?
+
+The topology scope is an [STQL query](../../../develop/reference/k8sTs-stql_reference.md) that's added as a prefix to every query executed in SUSE Observability. Whenever a user wants to select a view or pass a query in SUSE Observability, this prefix query is executed as a part of the user's query. This limits the results accordingly to match the user's role.
 
 Note: Please note that function calls like `withCauseOf` and `withNeighborsOf` aren't supported as they would not be performant in this context.
 
-If a user belongs to multiple groups, then this user can have multiple scopes, which translates to multiple prefixes. In this situation, the prefix is executed as an OR of all scopes that this user has.
+If a user belongs to multiple groups, then this user can have multiple topology scopes, which translates to multiple prefixes. In this situation, the prefix is executed as an OR of all topology scopes that this user has.
 
 Users need to log out and authenticate again to SUSE Observability whenever any changes to roles or permissions are made.
 
-## Why scopes?
+## Why topology scopes?
 
-Scopes are introduced as a security feature that's mandatory for every subject within SUSE Observability. The predefined SUSE Observability users Administrator, Power User and Guest roles have no scope defined.
+Topology scopes are introduced as a security feature that's mandatory for every subject within SUSE Observability. The predefined SUSE Observability users Administrator, Power User and Guest roles have no scope defined.
 
-It's possible to specify a scope as a query wildcard, however, this will result in access to everything and isn't recommended. If there is a need for access without a scope, it's recommended to use one of the [predefined roles](rbac_permissions.md#predefined-roles) instead.
+It's possible to specify a topology scope as a query wildcard, however, this will result in access to everything and isn't recommended. If there is a need for access without a topology scope, it's recommended to use one of the [predefined roles](rbac_permissions.md#predefined-roles) instead.
 
 ## Examples
 
@@ -34,7 +38,7 @@ The query for this view is the same as for the others, but without any prefix:
 'layer = "Infrastructure" AND domain IN ("Customer1", "Customer2")'
 ```
 
-### Below user is in a group with configured subject X with the following scope:
+### Below user is in a group with configured subject X with the following topology scope:
 
 ```text
 'domain = "Customer1"'
@@ -48,7 +52,7 @@ Query with the prefix for this view is:
 '(domain = "Customer1") AND (layer = "Infrastructure" AND domain IN ("Customer1", "Customer2"))'
 ```
 
-### Another user who is a part of a group with a configured subject Y that has the following scope:
+### Another user who is a part of a group with a configured subject Y that has the following topology scope:
 
 ```text
 'domain = "Customer2"'