Adding Managing policies docs (#1426)

* adding managing policies * Update content/docs/details/managing-policies/index.md Co-authored-by: Jussi Hallila <[email protected]> * Update content/docs/details/managing-policies/index.md Co-authored-by: Jussi Hallila <[email protected]> * requested changes * remove warning * change disclaimer to policies --------- Co-authored-by: Jussi Hallila <[email protected]>
RoadieHQ · Nov 6, 2024 · 7bacc41 · 7bacc41
1 parent e6ca0f0
commit 7bacc41
Show file tree

Hide file tree

Showing 3 changed files with 59 additions and 14 deletions.
diff --git a/content/docs/details/managing-policies/index.md b/content/docs/details/managing-policies/index.md
@@ -0,0 +1,42 @@
+---
+title: Policies Management
+publishedDate: '2024-11-05T21:00:00.0Z'
+description: How to configure and manage policies in Roadie for access control.
+---
+
+## Introduction
+
+**This feature is currently in the process of being rolled out. If you want access, please contact our support or sales teams.**
+
+In Roadie, **policies** are integral components of the permissions framework, governing access control within the platform. They define the rules and conditions under which users can perform specific actions on various resources, such as services, components, or documentation.
+
+**Key aspects of policies:**
+
+- **Authorization Decisions:** Policies determine whether a user is permitted to execute a particular action. For instance, a policy might allow only the owner of a service to delete it from the catalog. For more on policy definitions, refer to the [Backstage documentation](https://backstage.io/docs/permissions/writing-a-policy/).
+- **Conditional Logic:** Policies can incorporate complex conditions, such as verifying if a user belongs to a specific group or possesses certain attributes, to make nuanced authorization decisions. Details are available in the [Backstage documentation on custom rules](https://backstage.io/docs/permissions/custom-rules/).
+- **Customization:** Administrators have the flexibility to craft custom policies tailored to their organization's unique requirements, ensuring that access controls align with internal processes and security standards. Read more in the [Backstage custom rules documentation](https://backstage.io/docs/permissions/custom-rules/).
+
+By implementing policies, Roadie ensures that access to resources is managed effectively, enhancing security and maintaining the integrity of the development environment.
+
+To configure this in Roadie we provide a UI for **Policies Management** and you can access it at: `https://<tenant name>.roadie.so/administration/settings/policies`.
+
+Currently, a set of permissions is available from the upstream Backstage project, with the option to create and validate new permissions.
+
+- Built-in policies cannot be modified or removed, but they can be added to or removed from roles.
+- Each policy can be configured with an effect to either **ALLOW** or **DENY** the specified permissions and the conditions set for the policy.
+
+### Conditions for Configurable Permissions
+
+Some permissions allow configuration with a set of conditions, particularly those starting with `catalog.entity.`. These conditions enable access customization based on defined rules. Currently, these are the available rules:
+
+| Rule Name             | Parameters            | Description                                                                 |
+| --------------------- | --------------------- | --------------------------------------------------------------------------- |
+| isEntityOwner         | None                  | Checks if the user is the owner of the entity.                              |
+| isUserEntity          | None                  | Checks if the entity represents the current user.                           |
+| hasOwnEntityName      | None                  | Validates that the entity has its own unique name.                          |
+| hasOwnEntityNamespace | None                  | Confirms that the entity has its own designated namespace.                  |
+| hasEntityKind         | `kinds`               | Checks if the entity is of a specific kind (e.g., Component, API).          |
+| hasSpec               | `key`, `value`        | Verifies the entity’s specification includes a specific key-value pair.     |
+| hasMetadata           | `key`, `value`        | Ensures the entity metadata contains a specific key-value pair.             |
+| hasLabel              | `label`               | Checks if the entity includes a specific label in its metadata.             |
+| hasAnnotation         | `annotation`, `value` | Validates the presence of a particular annotation in the entity’s metadata. |
diff --git a/content/docs/details/permissions/index.md b/content/docs/details/permissions/index.md
@@ -8,11 +8,11 @@ description: How to configure access control permissions in Roadie.
 
 Roadie comes with RBAC out of the box. We provide 4 default roles: `admin`, `viewer`, `maintainer` and `tech-insights-admin`. It is possible to also define custom roles - please contact our sales team if this is something you are interested in.
 
-| Name | Description |
-|------|-------------------|
-| admin | Can perform any action in Roadie |
-| viewer | Can only view data within Roadie |
-| maintainer | Can read and write data, but cannot access administration settings or tech insights editing |
+| Name                | Description                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| admin               | Can perform any action in Roadie                                                                                               |
+| viewer              | Can only view data within Roadie                                                                                               |
+| maintainer          | Can read and write data, but cannot access administration settings or tech insights editing                                    |
 | tech-insights-admin | Can edit scorecards, checks and data sources in tech insights. This role requires one of viewer / maintainer to work correctly |
 
 ## Assigning Roles
@@ -24,7 +24,7 @@ There are two ways to assign a role to a user in Roadie:
 
 ### User Management
 
-- Visit the user management page in `https://<tenant name>.roadie.so/administration/manage-users`.
+- Visit the user management section in `https://<tenant name>.roadie.so/administration/settings/manage-users`.
 - Find the name of the user you would like to assign a role to.
 - Click the edit pencil and then add the roles you would like to assign the user.
 
@@ -35,17 +35,17 @@ If your Roadie tenant is using a custom identity provider, you can choose to inc
 ```json
 {
   "sub": "77d0c4cb-706c-4aa4-b18e-bed538a33aa7",
-  "roles": ["viewer", "tech-insights-admin"],
-  ...
+  "roles": ["viewer", "tech-insights-admin"]
 }
 ```
 
 ## Setting the default roles
+
 If a user has no role associated yet, e.g. if it is the first time they have logged in and there are no roles associated with the user, then the user is allowed the policies associated with the default roles. There can be many default roles.
 
 To edit the default roles:
 
-- Visit `http://<tenant name>.roadie.so/administration/roles`
+- Visit `http://<tenant name>.roadie.so/administration/settings/roles`
 - Click the edit pencil beside the roles you would like to be the default roles
 - The click "Set as default role" and save.
-- You can perform similar steps to make a role no longer a default role.
+- You can perform similar steps to make a role no longer a default role.
diff --git a/content/docs/docs-nav.yaml b/content/docs/docs-nav.yaml
@@ -101,6 +101,9 @@ nav:
       - Working with plugins:
           - Required metadata: '/docs/details/required-metadata/'
           - Requesting plugins: '/docs/details/requesting-plugins/'
+      - Setting secrets: '/docs/details/setting-secrets/'
+      - Permissions:
+          - Managing Policies: '/docs/details/managing-policies/'
       - Updating the UI: '/docs/details/updating-the-ui/'
   - Custom plugins:
       - Overview: '/docs/custom-plugins/overview'
@@ -119,11 +122,11 @@ nav:
   - Scaffolder:
       - Overview: '/docs/scaffolder/writing-templates/'
       - Scaffolder Actions:
-        - Actions Directory: '/docs/scaffolder/scaffolder-actions-directory/'
-        - Custom Scaffolder Actions: '/docs/scaffolder/self-hosted-scaffolder-actions/'
+          - Actions Directory: '/docs/scaffolder/scaffolder-actions-directory/'
+          - Custom Scaffolder Actions: '/docs/scaffolder/self-hosted-scaffolder-actions/'
       - Scaffolder Parameters:
-        - Paremeters Guide: '/docs/scaffolder/scaffolder-parameters'
-        - Custom Scaffolder Parameters: '/docs/scaffolder/custom-fields/'
+          - Paremeters Guide: '/docs/scaffolder/scaffolder-parameters'
+          - Custom Scaffolder Parameters: '/docs/scaffolder/custom-fields/'
       - Recipes:
           - Create RFC: '/docs/scaffolder/create-rfc/'
           - Debug template: '/docs/scaffolder/debug-template/'