STAC-23290: Make a small reference to the commands that are helpful t…

docs/latest/modules/en/pages/setup/security/authentication/troubleshooting.adoc

@@ -32,3 +32,9 @@ stackstate:
 Now run the `helm upgrade` command you used before but include this one extra yaml file (so `+helm upgrade .... --values debug-auth.yaml+`) to enable debug logging. No pods will be restarting, the logging configuration changes will be loaded automatically after about 30 seconds.
 
 To disable the debug logging run the `+helm upgrade ....+` command again but omit the `--values debug-auth.yaml`. After 30 seconds the updated logging configuration is loaded and the debug logging stops.
+
+
+== Troubleshooting issues with permissions
+
+* xref:/setup/security/rbac/rbac_permissions.adoc#_list_subjects_for_a_user[Inspect the user subjects] (user and roles) and verify the configuration depending on the authentication model being used.
+* xref:/setup/security/rbac/rbac_permissions.adoc#_show_granted_permissions[Inspect a subject permission] and verify the configuration depending on the authorization model being used.

docs/latest/modules/en/pages/setup/security/rbac/rbac_permissions.adoc

@@ -176,35 +176,42 @@ suse-observability-agent-clusterA          | Observability
 
 === List subjects for a user
 
-List all subjects that are assigned to the context:
+List all subjects that are assigned to the context, the first entry shown is the username, and potential roles the user has:
 
 [,text]
 ----
 sts user-session roles
 
-keycloakoidc_group://suse-observability-instance-troubleshooter                                                            
+user-dkzwh
+keycloakoidc_group://suse-observability-instance-troubleshooter
 keycloakoidc_group://suse-observability-instance-observer
 keycloakoidc_group://suse-observability-cluster-observer
 keycloakoidc_group://suse-observability-instance-admin
 keycloakoidc_group://suse-observability-observer
 ----
 
-List all subjects that are assigned to a user, by providing their `api-token`:
+List all subjects that are assigned to a user, by providing their `api-token`(useful as the admin can help debug users with less privileges):
 
 [,text]
 ----
 sts user-session roles --api-token [api-token]
 
-keycloakoidc_group://suse-observability-instance-admin
+u-3p775e7w7l
+keycloakoidc_group://suse-observability-cluster-observer
 ----
 
 === Show granted permissions
 
-Show the permissions granted to a specific role.
+Show the permissions granted to a specific user or role.
 
 [,text]
 ----
 sts rbac describe-permissions --subject [role-name]
+
+PERMISSION   | RESOURCE
+get-topology | cluster-name:rbac-t2
+get-traces   | k8s.cluster.name:rbac-t2
+get-metrics  | k8s:rbac-t2:__any__
 ----
 
 [NOTE]

docs/latest/modules/en/pages/setup/security/rbac/rbac_rancher.adoc

@@ -144,3 +144,15 @@ To grant additional permissions beyond Recommended Access, create a custom Proje
 image::rancher-custom-role.png[Custom RoleTemplate for richer access]
 
 You can specify any resource and verb combination defined in the xref:/setup/security/rbac/rbac_permissions.adoc[RBAC Permissions].  Note that the dashes (`-`) are dropped from resource names, so the permission `get-metric-bindings` becomes the Kubernetes RBAC resource `metricbindings` with the verb `get`.
+
+== Troubleshooting
+
+* Verify that the Rbac Agent for the cluster is able to communicate with the platform.
+
+NOTE: the Rbac Agent must authenticate using service tokens.
+
+* xref:/setup/security/rbac/rbac_permissions.adoc#_list_subjects_for_a_user[Inspect the user subjects] (user and roles).
+  ** Verify any roles configuration on the OIDC provider.
+* xref:/setup/security/rbac/rbac_permissions.adoc#_show_granted_permissions[Inspect the subject permission]
+  ** Verify that the relevant (Cluster)RoleBindings that match the user with a (Cluster)Role are present.
+  ** Inspect the (Cluster)Role to verify that it grants the correct permissions.