From ddfeada98095ee2fd1de4f4fa844f31c85f036bd Mon Sep 17 00:00:00 2001 From: Aramis Date: Tue, 30 Jan 2024 22:43:23 -0500 Subject: [PATCH] remove lengthy definitions Signed-off-by: Aramis --- docs/permissions/concepts.md | 8 ++++++++ docs/references/glossary.md | 12 ++++++------ 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/permissions/concepts.md b/docs/permissions/concepts.md index 8e348373cf..7c8b9e9f69 100644 --- a/docs/permissions/concepts.md +++ b/docs/permissions/concepts.md @@ -4,6 +4,14 @@ title: Concepts description: A list of important permission framework concepts --- +### Permission + +Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a [software template](../references/glossary.md#software-templates), may require [authorization](../references/glossary.md#authorization) for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. [Plugins](../references/glossary.md#plugin) are responsible for defining and exposing the permissions they enforce as well as enforcing restrictions from the permission framework. + +### Policy + +User [permissions](../references/glossary.md#permission-permission-plugin) are authorized by a central, user-defined permission policy. At a high level, a policy is a function that receives a Backstage user and permission, and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular [authorization](../references/glossary.md#authorization) model, like role-based access control (RBAC) or attribute-based access control (ABAC). + ### Policy decision versus enforcement Two important responsibilities of any authorization system are to decide if a user can do something, and to enforce that decision. In the Backstage permission framework, policies are responsible for decisions and plugins (typically backends) are responsible for enforcing them. diff --git a/docs/references/glossary.md b/docs/references/glossary.md index 773e7bfb50..45c2bbcd35 100644 --- a/docs/references/glossary.md +++ b/docs/references/glossary.md @@ -91,9 +91,7 @@ A new paradigm for Backstage frontend plugins, allowing definition in config fil ## Decorator (search plugin) -A transform stream. Decorators allow you to add additional information to documents outside of the [collator](#collator-search-plugin). They sit between the collators and the [indexers](#indexer-search-plugin) and can add extra fields to documents as they're being collated and indexed. - -Possible use cases for a decorator could be to bias search results or otherwise improve the search experience in your Backstage instance. Decorators can also be used to remove [metadata](#metadata), filter out, or even add extra documents at index-time. +A transform stream that allows you to add additional information to [documents](#document-search-plugin). ## Deployment Artifacts @@ -205,11 +203,13 @@ A service that hosts [packages](#package). The most prominent example is [NPM](h The declared role of a package, see [package roles](../local-dev/cli-build-system.md#package-roles). -## Permission +## Permission (core Backstage plugin) A core Backstage plugin and framework that allows restriction of actions to specific users. See [their docs](https://backstage.io/docs/permissions/overview) for more information. -Any action that a user performs within Backstage may be represented as a permission. More complex actions, like executing a [software template](#software-templates), may require [authorization](#authorization) for multiple permissions throughout the flow. Permissions are identified by a unique name and optionally include a set of attributes that describe the corresponding action. [Plugins](#plugin) are responsible for defining and exposing the permissions they enforce as well as enforcing restrictions from the permission framework. +## Permission (permission plugin) + +A restriction on any action that a user can perform against a specific [resource](#resource-permission-plugin) or set of resources. See [the permission framework docs](../permissions/concepts.md#permission) for more details. ## Persona (use cases) @@ -221,7 +221,7 @@ A module in Backstage that adds a feature. All functionality outside of [the Bac ## Policy (permission plugin) -User [permissions](#permission) are authorized by a central, user-defined [permission](#permission) policy. At a high level, a policy is a function that receives a Backstage user and [permission](#permission), and returns a decision to allow or deny. Policies are expressed as code, which decouples the framework from any particular [authorization](#authorization) model, like role-based access control (RBAC) or attribute-based access control (ABAC). +A construct that takes in a Backstage user and a [permission](#permission-permission-plugin) and returns a [policy decision](#policy-decision-permission-plugin). ## Policy Decision (permission plugin)