[🚨] Feature using OPA for Permissions (without the permissions framew…

…ork) (#230) Enhancement to OPA suite for Backstage allowing more flexible REBAC/RBAC for custom plugins! --------- Signed-off-by: Peter Macdonald <[email protected]>
Parsifal-M · Oct 31, 2024 · f7f9c6d · f7f9c6d
1 parent 2b9c391
commit f7f9c6d
Show file tree

Hide file tree

Showing 101 changed files with 4,385 additions and 1,255 deletions.
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -15,6 +15,16 @@ opa-permissions-wrapper:
       - any-glob-to-any-file:
           ['plugins/permissions-backend-module-opa-wrapper/**/*']
 
+opa-authz:
+  - changed-files:
+      - any-glob-to-any-file:
+          ['packages/opa-authz/**/*']
+
+opa-authz-react:
+  - changed-files:
+      - any-glob-to-any-file:
+          ['plugins/opa-authz-react/**/*']
+
 cicd:
   - changed-files:
       - any-glob-to-any-file: ['.github/workflows/**/*']

diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # Welcome to the OPA Plugins Repository for Backstage
 
+[![codecov](https://codecov.io/gh/Parsifal-M/backstage-opa-plugins/graph/badge.svg?token=IHZGVSXZY7)](https://codecov.io/gh/Parsifal-M/backstage-opa-plugins)
+
 This repository contains a collection of plugins for [Backstage](https://backstage.io) that integrate with [Open Policy Agent](https://www.openpolicyagent.org/).
 
 ## Blogs
@@ -17,6 +19,11 @@ This repository contains a collection of plugins for [Backstage](https://backsta
 - [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) - A frontend plugin that provides a component card that displays if an entity has the expected entity metadata according to an opa policy.
 - [backstage-opa-policies](./plugins/backstage-opa-policies/README.md) - A frontend component designed to be added to entity pages to fetch and display the OPA policy that entity uses based on a URL provided in an annotation in the `catalog-info.yaml` file.
 
+## Beta Plugins
+
+- [backstage-opa-authz](./plugins/opa-authz-react/README.md) - A frontend plugin that allows you to control the visibility of components based on the result of an OPA policy evaluation.
+- [backstage-opa-authz-backend](./packages/opa-authz/README.md) - A Backstage backend plugin that allows you to use OPA for authorization in the Backstage backend allowing you to protect api routes.
+
 ## Policies
 
 - [backstage-opa-policies](https://github.com/Parsifal-M/backstage-opa-policies#hello) - A collection of policies that can be used with the plugins in this repository. (WIP)

diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -14,8 +14,7 @@ services:
       - '--watch'
       - '--log-format=json-pretty'
       - '--set=decision_logs.console=true'
-      - '/policies/rbac_policy.rego'
-      - '/policies/entity_checker.rego'
+      - '/policies/'
     ports:
       - 8181:8181
     volumes:

diff --git a/docs/ADOPTERS.md b/docs/ADOPTERS.md
@@ -10,6 +10,8 @@ It's awesome to see that this project is being used by other companies and proje
 
 ## Open Source Projects
 
+None yet! Be the first to add your project here!
+
 ## How to Add Your Organization
 
 If you're using our project and want to be featured on this list, please follow these steps:

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,5 +1,7 @@
 # Contributing
 
-I am happy to accept contributions and suggestions for this plugin. Please fork the repository and open a PR with your changes. If you have any questions, please feel free to reach out to me on [Mastodon](https://hachyderm.io/@parcifal).
+I am happy to accept contributions and suggestions for these plugins, if you are looking to make significant changes, please open an issue first to discuss the changes you would like to make!
+
+Please fork the repository and open a PR with your changes. If you have any questions, please feel free to reach out to me on [Mastodon](https://hachyderm.io/@parcifal).
 
 Please remember to sign your commits with `git commit -s` so that your commits are signed!
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,19 +1,22 @@
-- [Home](/)
-- [OPA Permissions Wrapper Module](opa-permissions-wrapper-module/introduction.md)
-  - [Quick Start](opa-permissions-wrapper-module/quick-start.md)
-  - [Example Permissions (RBAC) Policy](opa-permissions-wrapper-module/example-rbac-policy.md)
-  - [Catalog Rules](opa-permissions-wrapper-module/catalog-rules.md)
-  - [Scaffolder Rules](opa-permissions-wrapper-module/scaffolder-rules.md)
-  - [Local Development](opa-permissions-wrapper-module/local-development.md)
-  - [Example Inputs and Outputs](opa-permissions-wrapper-module/inputs-and-outputs.md)
-  - [Architecture](opa-permissions-wrapper-module/architecture.md)
-- [OPA Backend](opa-backend/introduction.md)
-  - [Quick Start](opa-backend/quick-start.md)
-- [OPA Entity Checker](opa-entity-checker/introduction.md)
-  - [Quick Start](opa-entity-checker/quick-start.md)
-  - [Local Development](opa-entity-checker/local-development.md)
-  - [Example Entity Checker Policy](opa-entity-checker/example-entity-checker-policy.md)
-- [OPA Policies](opa-policies/introduction.md)
-  - [Quick Start](opa-policies/quick-start.md)
-- [Contributing](CONTRIBUTING.md)
-- [Adopters](ADOPTERS.md)
+- [Home](home/home.md#welcome-to-the-opa-plugins-repository-for-backstage)
+- [Deploying OPA](deploying-opa/deploying-opa.md#how-to-deploy-opa)
+- [OPA Permissions Wrapper Module](opa-permissions-wrapper-module/introduction.md#simplify-permissions-with-opa-in-backstage)
+  - [Quick Start](opa-permissions-wrapper-module/quick-start.md#quick-start)
+  - [Example Permissions (RBAC) Policy](opa-permissions-wrapper-module/example-rbac-policy.md#example-permissions-rbac-policy)
+  - [Catalog Rules](opa-permissions-wrapper-module/catalog-rules.md#catalog-rules)
+  - [Scaffolder Rules](opa-permissions-wrapper-module/scaffolder-rules.md#scaffolder-rules)
+  - [Local Development](opa-permissions-wrapper-module/local-development.md#using-the-plugin-in-local-development)
+  - [Example Inputs and Outputs](opa-permissions-wrapper-module/inputs-and-outputs.md#example-inputs-and-outputs-for-policy-evaluation)
+  - [Architecture](opa-permissions-wrapper-module/architecture.md#open-policy-agent-opa-plugins-architecture)
+- [OPA Authz](opa-authz/introduction.md#opa-authz-client)
+- [OPA Backend](opa-backend/introduction.md#backstage-opa-backend-plugin)
+  - [Quick Start](opa-backend/quick-start.md#quick-start)
+- [OPA Entity Checker](opa-entity-checker/introduction.md#keep-your-entity-data-in-check-with-opa-entity-checker)
+  - [Quick Start](opa-entity-checker/quick-start.md#quick-start)
+  - [Local Development](opa-entity-checker/local-development.md#using-the-plugin-in-local-development)
+  - [Example Entity Checker Policy](opa-entity-checker/example-entity-checker-policy.md#example-entity-checker-policy)
+- [OPA Authz React](opa-authz-react/introduction.md#opa-authz-react)
+- [OPA Policies](opa-policies/introduction.md#opa-policies-plugin-overview)
+  - [Quick Start](opa-policies/quick-start.md#quick-start)
+- [Contributing](CONTRIBUTING.md#contributing)
+- [Adopters](ADOPTERS.md#project-adopters)
diff --git a/docs/deploying-opa/deploying-opa.md b/docs/deploying-opa/deploying-opa.md
@@ -0,0 +1,90 @@
+# How To Deploy OPA!
+
+The official documentation provided by the Open Policy Agent (OPA) community is a great resource to get started with OPA. You can find the documentation [here](https://www.openpolicyagent.org/docs/latest/deployments/).
+
+However, if you're looking for just a quick way to get started with OPA, here's a simple guide to help you deploy OPA as a sidecar to your Backstage instance.
+
+## Deploying OPA
+
+There are many ways to deploy OPA, and there is no one size fits all. A good way is to deploy OPA as a sidecar to your Backstage instance. This way, you can ensure that OPA is always available when your Backstage instance is running.
+
+Here is an example of how you could update your Backstage `k8s` deployment to include OPA, this would be an extension of the `k8s` deployment that you are using for your Backstage instance.
+
+```yaml
+#... Backstage deployment configuration with OPA
+spec:
+  containers:
+    - name: backstage
+      image: your-backstage-image
+      ports:
+        - name: http
+          containerPort: 7007
+    - name: opa
+      image: openpolicyagent/opa:0.65.0 # Pin a version of your choice
+      ports:
+        - name: http
+          containerPort: 8181
+      args:
+        - 'run'
+        - '--server'
+        - '--log-format=json-pretty'
+        - '--set=decision_logs.console=true'
+        - '--ignore=.*'
+        - '--watch' # Watch for policy changes, this allows updating the policy without restarting OPA
+        - '/policies'
+      volumeMounts:
+        - readOnly: true
+          name: opa-rbac-policy
+          mountPath: /policies
+  volumes:
+    - name: opa-rbac-policy
+      configMap:
+        name: opa-rbac-policy
+```
+
+> [!ATTENTION|style:flat]
+> The below is a policy designed to work with the [OPA Permissions Wrapper Module](../opa-permissions-wrapper-module/introduction.md#simplify-permissions-with-opa-in-backstage). If you are using [opa-authz](../opa-authz/introduction.md#opa-authz-client) or [opa-authz-react](../opa-authz-react/introduction.md#opa-authz-react), you will need to adjust the policy accordingly!
+
+For simplicity you can then create a policy in a `ConfigMap` and mount it into the OPA container.
+
+> [!NOTE|style:flat]
+> Note: Update "kind:namespace/name" in the policy to match your user entity claims.
+
+```yaml
+# opa-rbac-policy.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: opa-rbac-policy
+data:
+  rbac_policy.rego: |
+    package rbac_policy
+
+    import rego.v1
+
+    # Helper method for constructing a conditional decision
+    conditional(plugin_id, resource_type, conditions) := {
+        "result": "CONDITIONAL",
+        "pluginId": plugin_id,
+        "resourceType": resource_type,
+        "conditions": conditions,
+    }
+
+    permission := input.permission.name
+
+    claims := input.identity.claims
+
+    # An Example Admin Group
+    is_admin if "kind:namespace/name" in claims
+
+    # Catalog Permission: Allow users to only delete entities they claim ownership of.
+    # Allow admins to delete any entity regardless of ownership.
+    decision := conditional("catalog", "catalog-entity", {"anyOf": [{
+     "resourceType": "catalog-entity",
+     "rule": "IS_ENTITY_OWNER",
+     "params": {"claims": claims},
+    }]}) if {
+     permission == "catalog.entity.delete"
+     not is_admin
+    }
+```
diff --git a/docs/home/home.md b/docs/home/home.md
@@ -0,0 +1,57 @@
+# Welcome to the OPA Plugins Repository for Backstage
+
+[![codecov](https://codecov.io/gh/Parsifal-M/backstage-opa-plugins/graph/badge.svg?token=IHZGVSXZY7)](https://codecov.io/gh/Parsifal-M/backstage-opa-plugins)
+
+This repository contains a collection of plugins for [Backstage](https://backstage.io) that integrate with [Open Policy Agent](https://www.openpolicyagent.org/).
+
+## Blogs
+
+- [Going Backstage with OPA](https://www.styra.com/blog/going-backstage-with-opa/)
+
+## Talks
+
+- [Can It Be Done? Building Fine-Grained Access Control for Backstage with OPA](https://www.youtube.com/watch?v=N0n_czYo_kE&list=PLj6h78yzYM2P4KPyeDFexAVm6ZvfAWMU8&index=15&ab_channel=CNCF%5BCloudNativeComputingFoundation%5D)
+
+## Plugins
+
+- [backstage-opa-backend](./plugins/backstage-opa-backend/README.md) - A Backend Plugin that the [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) consumes to evaluate policies.
+- [plugin-permission-backend-module-opa-wrapper](./plugins/permission-backend-module-opa-wrapper/README.md) - An isolated OPA Client and a Policy Evaluator that integrates with the Backstage permissions framework and uses OPA to evaluate policies, making it possible to use OPA for permissions (like RBAC). Does not require the `backstage-opa-backend` plugin!
+- [backstage-opa-entity-checker](./plugins/backstage-opa-entity-checker/README.md) - A frontend plugin that provides a component card that displays if an entity has the expected entity metadata according to an opa policy.
+- [backstage-opa-policies](./plugins/backstage-opa-policies/README.md) - A frontend component designed to be added to entity pages to fetch and display the OPA policy that entity uses based on a URL provided in an annotation in the `catalog-info.yaml` file.
+
+## Beta Plugins
+
+- [backstage-opa-authz](./plugins/opa-authz-react/README.md) - A frontend plugin that allows you to control the visibility of components based on the result of an OPA policy evaluation.
+- [backstage-opa-authz-backend](./packages/opa-authz/README.md) - A Backstage backend plugin that allows you to use OPA for authorization in the Backstage backend allowing you to protect api routes.
+
+## Policies
+
+- [backstage-opa-policies](https://github.com/Parsifal-M/backstage-opa-policies#hello) - A collection of policies that can be used with the plugins in this repository. (WIP)
+
+## Additional Documentation
+
+Each Plugin has its own documentation in the [Plugins](./plugins/) Folder, I am however, slowly moving things to [Github pages](https://parsifal-m.github.io/backstage-opa-plugins/#/). Feel free to help out!
+
+## Local Development
+
+Step by step guide to developing locally:
+
+1. Clone this repository
+2. Create an `app-config.local.yaml` file in the root of the repository copying the contents from `app-config.yaml`
+3. Create a PAT (Personal Access Token) for your GitHub account with these scopes: `read:org`, `read:user`, `user:email`. This token should be placed under `integrations.github.token` in the `app-config.local.yaml` file.
+4. Run `yarn install --immutable` in the root of the repository
+5. Use `docker-compose up -d` to start the OPA server and postgres database (this will also load the two policies in the `example-opa-policies` folder automatically)
+6. Update the OPA rbac policy in here [rbac_policy.rego](./example-opa-policies/rbac_policy.rego), or use your own! If you want to use the default policy, you'll have to update `is_admin if "group:twocodersbrewing/maintainers" in claims` to what ever your user entity claims are.
+7. Run `yarn dev` or `yarn debug` in the root of the repository to start the Backstage app (use debug if you want to see what is happening in the OPA plugin)
+
+## Ecosystem
+
+- [PlaTT Policy Template](https://github.com/ap-communications/platt-policy-template) contains policy templates that will work with the [plugin-permission-backend-module-opa-wrapper](./plugins/permission-backend-module-opa-wrapper/README.md) plugin!
+
+## Contributing
+
+Contributions are welcome! However, still figuring out the best approach as this does require user and group entities to be in the system.
+
+Please open an issue or a pull request. You can also contact me on mastodon at [@parcifal](https://hachyderm.io/@parcifal).
+
+Please remember to sign your commits with `git commit -s` so that your commits are signed!
diff --git a/docs/index.html b/docs/index.html
@@ -17,13 +17,7 @@
     <!-- Theme: Simple (light + dark) -->
     <link
       rel="stylesheet"
-      media="(prefers-color-scheme: light)"
-      href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"
-    />
-    <link
-      rel="stylesheet"
-      media="(prefers-color-scheme: dark)"
-      href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"
+      href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css"
     />
     <!-- Favicon -->
     <link rel="icon" href="path/to/your/favicon.ico" type="../img/logo.png" />
@@ -56,7 +50,6 @@
     <!-- Recommended -->
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>
     <!--Copy To Clipboard-->
     <script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
     <!--Mermaid-->
@@ -70,5 +63,14 @@
       window.mermaid = mermaid;
     </script>
     <script src="//unpkg.com/[email protected]/dist/docsify-mermaid.js"></script>
+    <!--Language Support-->
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-rego.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-diff.min.js"></script>
+    <!-- Alerts Plugin -->
+    <script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
   </body>
 </html>