docs(admin-ui): access control using cedarling docs

docs/admin/admin-ui/access-control.md

@@ -0,0 +1,253 @@
+---
+tags:
+  - administration
+  - admin-ui
+  - access control
+  - cedarling
+  - security
+---
+
+# Access Control in Admin UI
+
+The role of the user logged-in to Gluu Flex Admin UI decides if the user will have access to a certain Admin UI's feature or not. After user authentication the user's role and other claims are packed in bundle of tokens (access_token, id_token and userinfo_token). [Cedarling](https://docs.jans.io/stable/cedarling) PDP embedded with GUI, processes the tokens and decides if the action (like Read, Write or Delete) is allowed on this resource (feature). The Cedarling's Token-based Access Control (TBAC) is used for managing access control in Gluu Flex Admin UI.
+
+## Admin UI Features (Resources)
+
+The Admin UI features (or resources) are categorised into following parent groups. This categorization is done for resource grouping in cedar policies used for governing the authorization decision taken by Cedarling.
+
+- System and monitoring
+    - Dashboard
+    - Health
+    - License
+    - MAU
+    - Settings
+    - Security
+    - Webhooks
+    - Assets
+    - AuditLogs
+- AuthServer and configuration
+    - Clients
+    - Scopes
+    - Keys
+    - AuthServerProperties
+    - Logging
+    - SSA
+    - Authn
+    - ConfigAPIProperties
+    - Sessions
+- Identity and Access
+    - Users
+    - Scripts
+    - UserClaims
+- Service
+    - Cache
+    - Persistence
+    - SMTP
+    - SCIM
+    - FIDO
+    - SAML
+    - Lock
+
+In the Policy Store we use [default_entities](https://docs.jans.io/stable/cedarling/cedarling-policy-store/#default-entities) to map the parent group with the sub features. For e.g. here we are showing the default entity json to map the features under `System and monitoring` parent group.
+
+```json
+{
+	"1694c954f8d9": {
+		"uid": {
+			"type": "Gluu::Flex::AdminUI::Resources::Features",
+			"id": "Dashboard"
+		},
+		"attrs": {},
+		"parents": [
+			{
+				"type": "Gluu::Flex::AdminUI::Resources::ParentResource",
+				"id": "SystemAndMonitoring"
+			}
+		]
+	},
+	"2694c954f8d8": {
+		"uid": {
+			"type": "Gluu::Flex::AdminUI::Resources::Features",
+			"id": "License"
+		},
+		"attrs": {},
+		"parents": [
+			{
+				"type": "Gluu::Flex::AdminUI::Resources::ParentResource",
+				"id": "SystemAndMonitoring"
+			}
+		]
+	},
+	"3694c954f8d7": {
+		"uid": {
+			"type": "Gluu::Flex::AdminUI::Resources::Features",
+			"id": "MAU"
+		},
+		"attrs": {},
+		"parents": [
+			{
+				"type": "Gluu::Flex::AdminUI::Resources::ParentResource",
+				"id": "SystemAndMonitoring"
+			}
+		]
+	},
+	"4694c954f8d6": {
+		"uid": {
+			"type": "Gluu::Flex::AdminUI::Resources::Features",
+			"id": "Security"
+		},
+		"attrs": {},
+		"parents": [
+			{
+				"type": "Gluu::Flex::AdminUI::Resources::ParentResource",
+				"id": "SystemAndMonitoring"
+			}
+		]
+	},
+	"6494c954f8d6": {
+		"uid": {
+			"type": "Gluu::Flex::AdminUI::Resources::Features",
+			"id": "Settings"
+		},
+		"attrs": {},
+		"parents": [
+			{
+				"type": "Gluu::Flex::AdminUI::Resources::ParentResource",
+				"id": "SystemAndMonitoring"
+			}
+		]
+	},
+...
+}
+```
+
+## Managing Admin UI's Policy Store
+
+After installation, Admin UI uses a default Policy Store for GUI access control. The logged-in user can use the [Cedarling configuration screen](./configuration.md#cedarling-configuration) to configure a remote Policy Store generated by [Agama-Lab](https://cloud.gluu.org/agama-lab) using its URL. When the Policy Store URL is configured, the backend parses the Policy Store to determine the roles and the role-to-scope mappings. The Policy Store is used for managing GUI access control. The aggregated role-to-scope mapping (obtained by parsing the Policy Store) ensures that only the mapped scopes are added in the authorization tokens to access the appropriate protected Config API endpoints.
+
+```mermaid
+C4Context
+    title Access Control in Gluu Flex Admin UI
+
+    Enterprise_Boundary(flex, "Gluu Flex") {
+        Container(JansAuthServer, "Janssen Authentication Server", "Auth Server and OpenID Provider")
+
+        Container_Boundary(ConfigApiBoundary, "Config API") {
+            Container(AdminUIBackend, "Admin UI Backend", "The backend used by Admin UI")
+        }
+
+        Container_Boundary(AdminUIBoundary, "Admin UI") {
+            Container(Cedarling, "Cedarling", "PDP")
+            Container(Frontend, "Admin UI Frontend", "Web Interface")
+        }
+
+        ContainerDb(PolicyStore, "Default Policy Store", "Default Policy Store JSON File")
+    }
+
+    Enterprise_Boundary(AgamaLab, "Agama Lab") {
+        Container(PolicyDesigner, "Policy Designer", "Policy Designer for Cedarling")
+    }
+
+    Enterprise_Boundary(GitHub, "GitHub") {
+        ContainerDb(PolicyStoreProject, "Policy Store Project", "GitHub repository for storing remote Policy Stores")
+    }
+
+    Rel(AdminUIBackend, PolicyStore, "Use default Policy Store if <br>remote Policy Store URL not configured")
+    Rel(AdminUIBackend, PolicyStoreProject, "Use remote Policy Store if <br> remote Policy Store URL is configured")
+    Rel(AdminUIBackend, Cedarling, "Request Policy <br>Store for initialization")
+    Rel(PolicyDesigner, PolicyStoreProject, "Save Policy Store project to GitHub")
+    Rel(Frontend, Cedarling, "Check user permissions<br>for UI features and actions", "TBAC Authorization")
+```
+
+## Policies
+
+The Cedar policies in the Policy Store empowers the administrator with following:
+
+### Manage the access control in Admin UI
+
+The Cedar policies are rules which decide if the logged-in user can perform Read, Write or Delete action on a feature or not. By writing the appropriate cedar policies the administrator can manage access control in Admin UI. For e.g the below policy allows the user with role **admin** to perform **Read**, **Write** or **Delete** actions on all the features under the parent group **AuthServerAndConfiguration**.
+
+```cedar
+@id("AdminCanManageAuthServerConfiguration")
+permit (
+  principal in Gluu::Flex::AdminUI::Role::"admin",
+  action in [Gluu::Flex::AdminUI::Action::"read",
+  Gluu::Flex::AdminUI::Action::"write",
+  Gluu::Flex::AdminUI::Action::"delete"],
+  resource in Gluu::Flex::AdminUI::Resources::ParentResource::"AuthServerAndConfiguration"
+);
+```
+
+Below policy gives the users with role **viewer** the **Read** access to all the features under the **IdentityAndAccess** parent group.
+
+```cedar
+@id("ViewerCanViewUserIdentityAndAccess")
+permit (
+  principal in Gluu::Flex::AdminUI::Role::"viewer",
+  action in Gluu::Flex::AdminUI::Action::"read",
+  resource in Gluu::Flex::AdminUI::Resources::ParentResource::"IdentityAndAccess"
+);
+```
+
+Below policy gives the users with role **auditor** the **Read**, **Write** and **Delete** access to only the **Clients** feature of Admin UI.
+
+```cedar
+@id("AuditorCanManageClients")
+permit (
+  principal in Gluu::Flex::AdminUI::Role::"auditor",
+  action in [Gluu::Flex::AdminUI::Action::"read",
+  Gluu::Flex::AdminUI::Action::"write",
+  Gluu::Flex::AdminUI::Action::"delete"],
+  resource in Gluu::Flex::AdminUI::Resources::Features::"Clients"
+);
+```
+
+### Adding new Roles in Admin UI
+
+To add new Admin UI user roles, the administrator just need to introduce the policies associated with those roles in the Policy Store. On saving the Policy Store the Admin UI parses it and aggregates the roles and role-to-scope mapping. The aggregated data is saved into the persistence.
+
+### Writing policies: Parent Groups as resources
+
+The principal element in a [Cedar policy](https://docs.cedarpolicy.com/) represents a user, service, or other identity that can make a request to perform an action on a resource in your application. We will learn how to write an Admin UI policy using a sample scenario: a logged-in user with the **admin** role can manage the **Auth Server and its configuration**.
+
+```cedar
+@id("AdminCanManageAuthServerConfiguration")
+permit (
+  principal in Gluu::Flex::AdminUI::Role::"admin",
+  action in [Gluu::Flex::AdminUI::Action::"read",
+  Gluu::Flex::AdminUI::Action::"write",
+  Gluu::Flex::AdminUI::Action::"delete"],
+  resource in Gluu::Flex::AdminUI::Resources::ParentResource::"AuthServerAndConfiguration"
+);
+```
+**Principal :**
+We are using the administrator's **role** as principal while writing the policies for Admin UI. Here `Gluu::Flex::AdminUI::` is the namespace in cedar schema where the `Role` entity resides. The **admin** surrounded by inverted commas is the Entity Id of the **Role** entity and is basically the role name.
+
+**Action :**
+In this policy, we are allowing **Read**, **Write** and **Delete** actions on the resource. Here we have `action in [Gluu::Flex::AdminUI::Action::"read", Gluu::Flex::AdminUI::Action::"write", Gluu::Flex::AdminUI::Action::"delete"]`. The `Gluu::Flex::AdminUI::` is the namespace where all action entities reside.
+
+**Resource :**
+As we have categorised Admin UI features (or resources) into the parent groups, `resource in Gluu::Flex::AdminUI::Resources::ParentResource::"AuthServerAndConfiguration"` allows the user with role **admin** to perform **Read**, **Write** and **Delete** actions on all the features under **AuthServerAndConfiguration** parent group. Here `Gluu::Flex::AdminUI::Resources::` is the namespace where **ParentResource** entity resides. The **ParentResource** entity represents the parent group and **AuthServerAndConfiguration** in inverted commas is the entity id representing name of the parent group.
+
+### Writing policies: Specific Admin UI Feature
+
+To define policies for a specific Admin UI feature (e.g., Clients, Scopes, Users), use the format `Gluu::Flex::AdminUI::Resources::Features` followed by the resource’s Entity ID enclosed in quotation marks in resource clause. For e.g. below policy allows **Read**, **Write** and **Delete** action to the user with role **auditor** on **Clients** resource.
+
+```cedar
+@id("AuditorCanManageClients")
+permit (
+  principal in Gluu::Flex::AdminUI::Role::"auditor",
+  action in [Gluu::Flex::AdminUI::Action::"read",
+  Gluu::Flex::AdminUI::Action::"write",
+  Gluu::Flex::AdminUI::Action::"delete"],
+  resource in Gluu::Flex::AdminUI::Resources::Features::"Clients"
+);
+```
+Please see the Entity Ids of the Parent Groups and their underlying features in this table:
+
+|Parent Group|Features|
+|------------|--------|
+|AuthServerAndConfiguration|Clients, Scopes, Keys, AuthenticationServerConfiguration, Logging, SSA, Authentication, ConfigApiConfiguration, Session|
+|IdentityAndAccess|Users, Scripts, Attributes|
+|SystemAndMonitoring|Dashboard, License, MAU, Security, Settings, Webhooks, Assets, AuditLogs|
+|Service|Persistence, SMTP, SCIM, FIDO, SAML, Lock|

docs/admin/admin-ui/auth-server-interaction.md

@@ -97,10 +97,10 @@ To ensure security and access control, Gluu Flex Admin UI leverages API protecti
 
 1. The Jans Config API's endpoints are protected and can only be accessed using a token (`AT2`) with the required scopes.
 2. To generate an AT2, the frontend requests the Token Server via the backend. **The Token Server and Authorization Server can be the same or different.**
-3. The Token Server employs an introspection script that validates the UJWT and refers to the role-scope mapping in the Token Server persistence.
-4. The introspection script validates the UJWT and includes the appropriate scopes in AT2 based on the user's role.
+3. The Token Server employs an update-token script that validates the UJWT and refers to the role-scope mapping in the Token Server persistence.
+4. The update-token script validates the UJWT and includes the appropriate scopes in AT2 based on the user's role.
 5. The frontend receives AT2 and associated scopes from the backend.
-6. Features in the frontend are enabled or disabled based on the scopes provided in AT2. Refer this [doc](./admin-menu.md/#gui-access-control) for GUI access control.
+6. The scopes provided in AT2 determine which Config API–protected endpoints the Admin UI can access. Refer this [doc](./access-control.md) for GUI access control.
 
 ```mermaid
 
@@ -116,9 +116,8 @@ Jans Token Server->>Jans Token Server: Add scopes to token based on role (AT2)
 Jans Token Server->>Admin UI Backend: AT2
 Admin UI Backend->>Gluu Flex Admin UI: AT2
 Gluu Flex Admin UI->>Gluu Flex Admin UI:extracts scopes from AT2
-Gluu Flex Admin UI->>Gluu Flex Admin UI: GUI access control based on scopes from AT2
+Gluu Flex Admin UI->>Gluu Flex Admin UI: AT2 determine which Config API–protected endpoints the Admin UI can access
 ```
-
 ## Accessing Config-API Endpoints
 
 To access config-api endpoints, the following steps are taken: