Welcome to the OPA Plugins Repository for Backstage

This repository contains a collection of plugins for Backstage that integrate with Open Policy Agent.

Blogs

• Going Backstage with OPA

Talks

• Can It Be Done? Building Fine-Grained Access Control for Backstage with OPA

Why use OPA with Backstage?

Integrating Open Policy Agent (OPA) with Backstage allows you to decouple policy from your code. This brings several benefits:

• Fine-Grained Access Control: Define complex RBAC and ABAC policies that go beyond standard permission systems.
• Centralized Policy Management: Manage policies for Backstage alongside your other infrastructure policies.
• Dynamic Policy Updates: Update policies without redeploying your Backstage instance.
• Consistency: Ensure consistent policy enforcement across your entire platform.

Architecture Overview

The plugins integrate with Backstage and OPA in two main ways.

1. Permissions Framework Integration

When using the permission-backend-module-opa-wrapper, the flow relies on the Backstage Permissions Framework:

graph LR
    User([User]) --> Frontend[Backstage Frontend]
    Frontend -->|Permission Request| PermBackend[Permission Backend]
    PermBackend -->|Delegate| OPAWrapper[OPA Wrapper]
    OPAWrapper <-->|Policy Decision| OPA[OPA Server]
    style User fill:#f9f,stroke:#333,stroke-width:2px
    style OPA fill:#ff9,stroke:#333,stroke-width:2px

Loading

2. Component Integrations

Other plugins interact with OPA for specific functionality, either by proxying through the backend or checking policies directly from a backend service.

graph LR
    User([User]) --> Frontend[Backstage Frontend]

    %% Flow 1: Frontend Authz (opa-authz-react)
    Frontend -- "Authz Request" --> OPABackend[OPA Backend Plugin]
    OPABackend -- "Policy Eval" --> OPA[OPA Server]

    %% Flow 2: Backend Node Service (opa-node)
    AnyBackend[Any Backend Plugin] -- "opa-node" --> OPA

    style User fill:#f9f,stroke:#333,stroke-width:2px
    style OPA fill:#ff9,stroke:#333,stroke-width:2px

Loading

Prerequisites

To use these plugins, you need:

1. A running Backstage instance.
2. A running Open Policy Agent (OPA) server.

You can deploy OPA in any way that suits your infrastructure (Docker, Kubernetes, Managed Service, etc.). Please refer to the official OPA deployment documentation.

Plugins & Modules

Backend

• backstage-opa-backend - A Backend Plugin that the backstage-opa-entity-checker and backstage-opa-authz-react plugins consume to evaluate policies.
• permission-backend-module-opa-wrapper - A Backstage backend module that integrates Open Policy Agent (OPA) with the Backstage Permission Framework for policy-based authorization.
• backstage-plugin-opa-entity-checker-processor - A standalone Backstage catalog processor that automatically validates entity metadata during catalog ingestion using OPA policies and adds validation status annotations.

Frontend

• backstage-opa-entity-checker - 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 - 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.
• backstage-opa-authz-react - A frontend plugin that allows you to control the visibility of components based on the result of an OPA policy evaluation.

Libraries & Utilities

• backstage-plugin-opa-common - Common types and functionality for the OPA plugins.
• backstage-plugin-opa-node - Provides a Node.js service for integrating Open Policy Agent (OPA) with Backstage backend modules and plugins. It allows you to secure your backend routes using OPA by providing a simple API for sending policy inputs and receiving policy results.

Configuration Overview

The OPA plugins use two separate configuration sections in your app-config.yaml:

Permission Framework Integration

permission:
  opa:
    baseUrl: 'http://localhost:8181'
    policies:
      permissions:
        policyEntryPoint: 'rbac_policy/decision'
        policyFallback: 'allow' # 'allow' or 'deny' (optional)

OPA Backend Services

openPolicyAgent:
  baseUrl: 'http://localhost:8181'
  entityChecker:
    enabled: true # Default: false
    policyEntryPoint: 'entity_checker/violation'
  entityCheckerProcessor:
    enabled: true # Default: false
    policyEntryPoint: 'entity_checker/violation'
  policyViewer:
    enabled: true # Default: false

Important: All OPA backend features are disabled by default. You must explicitly set enabled: true for each feature you want to use. This allows selective loading of only the functionality you need.

Additional Documentation

Each Plugin has its own documentation in the Plugins Folder, I am however, slowly moving things to Github pages. 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, 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 contains policy templates that will work with the plugin-permission-backend-module-opa-wrapper 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.

Please remember to sign your commits with git commit -s so that your commits are signed!