Skip to main content
Version: Next

Glossary

Access Token​

A token that represents the authorization to access resources on behalf of the end-user in a way that hides the user's actual identity. It will commonly have a short expiry time, and be limited to a set of scopes. Part of the OAuth protocol, see their docs for details.

Administrator​

Someone responsible for installing, configuring, and maintaining a Backstage app for an organization. A user role.

API​

A software interface consisting of defined rules, protocols, and tools, that allows two applications or components to communicate and exchange data or functionality.

APIs are key abstractions that allow large software ecosystems to be scaled efficiently. Within the Backstage model, APIs are first-class citizens, and are the primary method for discovering existing functionality across the ecosystem. See Backstage System Model.

App​

An installed instance of Backstage. An app can be local, intended for a single developer or development group, or organizational, for use by an entire enterprise.

Authentication​

The process of verifying the identity of a user, system, or entity attempting to access a resource, system, or network. It answers the question: "Are you who you claim to be?" See this Wikipedia article for more details.

Authorization​

The process of determining which operations an authenticated user or system is allowed to perform within a system, application, or resource. It comes after authentication, and answers the question: "What are you allowed to access or do?" It involves assigning specific privileges, access rights, or roles to the user. See this Wikipedia article for more details.

Authorization Code Grant​

See Code Grant.

Backstage​

  1. An open source framework for creating and deploying developer portals, originally created at Spotify. Backstage is an incubation-stage open source project of the Cloud Native Computing Foundation.

  2. The Backstage Framework.

Backstage Framework​

The actual framework that Backstage plugins sit on. The framework spans the frontend and backend, and includes core functionality such as declarative integration, config reading, database management, and much more.

Bundle​

  1. A collection of deployment artifacts.

  2. The output of the bundling process, which brings a collection of packages into a single collection of deployment artifacts.

Catalog​

See Software Catalog.

Cloud Native Computing​

A set of technologies that "empower organizations to build and run scalable applications in modern, dynamic environments such as public, private, and hybrid clouds. Containers, service meshes, microservices, immutable infrastructure, and declarative APIs exemplify this approach." (CNCF Cloud Native Definition v1.1).

Cloud Native Computing Foundation (aka CNCF)​

A foundation dedicated to the promotion and advancement of Cloud Native Computing. The mission of the Cloud Native Computing Foundation (CNCF) is "to make cloud native computing ubiquitous" (CNCF Charter).

CNCF is part of the Linux Foundation.

Code Grant​

In the context of OAuth 2.0, refers to the process where an application receives an authorization code after a user grants it permission to access their resources. This code is then exchanged for an access token and possibly a refresh token, which the application uses to access the user's data on their behalf. It's a secure way for applications to access protected resources without directly handling the user's credentials. See the OAuth docs for details.

Collator (search plugin)​

A specialized component of Backstage that's responsible for ordering or indexing data according to a specific set of rules. In Backstage search, collators are used to define what can be searched. Specifically, they're readable object streams of documents that contain a minimum set of fields (including document title, location, and text), but can contain any other fields as defined by the collator itself. A single collator is responsible for defining and collecting documents of a specific type.

Backstage includes "default" collators for Catalog and TechDocs that you can use out-of-the-box to start searching across Backstage quickly. More collators are available from the Backstage community. Learn more at Collators.

Component (catalog plugin)​

  1. A modular, independent, reusable software-based unit that encapsulates specific functionality. It has well-defined interfaces, explicitly specified dependencies, and is designed to be integrated with other components to build larger software systems.

  2. A software product that Backstage manages in the Software Catalog. A component can be a service, website, library, data pipeline, or any other software artifact that's managed as a single entity.

A Backstage component can implement APIs for other components to consume. In turn, it might consume APIs implemented by other components, or directly depend on components or resources that are attached to it at runtime.

See the Backstage System Model.

Condition (permission plugin)​

A criterion, evaluated on an entity, that a user must meet to be granted permission to perform an action on that entity within a permission plugin. Examples might include isOwner or hasRole.

Conditional Decision (permission plugin)​

A decision mechanism, common in permission plugins, that evaluates real-time conditions (predicates) on a per-user basis to determine access or actions against a resource. This enables highly granular, context-aware control. See Conditional Decisions.

Contributor​

A volunteer who helps to improve an open source product such as Backstage. This volunteer effort includes coding, testing, technical writing, user support, and other work. A user role.

Declarative Integration​

A new paradigm for Backstage frontend plugins, allowing definition in config files instead of hosting complete React pages. See the Frontend System.

Decorator (search plugin)​

A transform stream that operates during the indexing process, positioned between a Collator (read stream) and an Indexer (write stream). Document Decorators are used to modify documents by adding, removing, or filtering metadata, or even injecting new documents, as they are being prepared for the search index.

To illustrate, while the Software Catalog understands software entities, it might not track their usage or quality. A decorator can add this extra metadata, which can then be used to bias search results or enhance the search experience within your Backstage instance.

Deployment Artifacts​

An executable or package file with all of the necessary information required to deploy at runtime. Deployment artifacts can be hosted on package registries.

Developer​

  1. A professional who designs, builds, tests, deploys, and maintains software applications and systems. Developers essentially turn ideas or requirements into functional digital products.

  2. A user role defined as someone who creates, modifies, or uses a Backstage app. Might or might not actually be a software developer.

Developer Portal​

  1. A centralized, self-service interface providing developers with all the necessary resources, tools, documentation, and information to effectively build, integrate, deploy, and manage software products within an organization.

  2. Backstage is a specific example of a developer portal, designed as a centralized system with a user interface and database to streamline development and maintenance of an organization's software projects. It features a robust Software Catalog that centralizes and organizes access to the organization's services, websites, mobile features, libraries, and other software components. Backstage also includes Software Templates that simplify the creation of new projects and components.

Backstage is both a developer portal and a plugin-based framework for creating new custom developer portals.

Document (search plugin)​

  1. A piece of information or data that is recorded on some medium for the purpose of retention and conveyance.

  2. An abstract representation of information or data that can be discovered and retrieved. For search purposes, a document might represent a software entity, a TechDocs page, or any other type of data that is indexed. In Backstage, a document is structured with metadata fields that must include at least a title, a body (containing its core text content), and a location (such as a URL pointing to its source).

Domain​

  1. A collection of systems that share terminology, domain models, metrics, KPIs, business purpose, or documentation; that is, it forms a bounded context.

  2. Typically the unique, human-readable address that is used to identify websites, email servers, and other resources on the internet, such as google.com or example.store. More narrowly, it can refer to the Top-Level Domain (TLD), which is the part of a web address after the last dot, such as .com or .org; the country code, such as .us or .uk; or the sponsored TLD such as .gov or .edu.

  3. An area that relates systems or entities to a business unit. See Domain in the System Model.

Entity​

  1. Something that exists as a separate and distinct unit. Its existence can be real or abstract, physical or conceptual, persistent or ephemeral.

  2. What is cataloged in the Backstage Software Catalog. An entity is identified by a unique combination of kind, namespace, and name. See The Life of an Entity for related key concepts and how it's handled.

Evaluator​

Someone who assesses whether Backstage is a suitable solution for their organization and needs. The only user role with a pre-deployment use case.

ID Token​

A security token used in authentication processes, primarily defined by the OpenID Connect (OIDC) standard. Its main purpose is to prove that a user has been successfully authenticated by an identity provider. See JSON Web Token.

Index (search plugin)​

A collection of documents that a search engine uses to quickly locate relevant information within your developer portal. It's essentially a lookup table that allows you to quickly find documents without having to scan the entire dataset.

Indexer (search plugin)​

In Backstage's Search Platform, the term indexer isn't a component or concept that developers typically interact with. Instead, it refers to the overall process or the write stream within the Search backend that takes processed documents and adds them to the chosen search engine's index.

To understand indexer in Backstage, it's helpful to understand the flow of data into the Search system:

  1. A Collator reads raw data from a specific source and transforms it into a stream of documents, where each document is formatted in a way the search platform understands (e.g., having title, text, location fields, and potentially other metadata).

  2. As the stream of documents flows from the collator, a decorator can intercept them. The decorator optionally adds, removes, or modifies fields within the documents to enrich them with context that the original collator might not have (such as adding ownership information from the Catalog to TechDocs documents).

  3. After optional decoration, the stream of finalized search documents is then written to the search engine's index. This is what the term indexer implicitly refers to. It's the functionality that takes these structured documents and inserts them into the chosen search engine (like Lunr, PostgreSQL, or Elasticsearch) so they become searchable.

The plugin-search-backend-node package in Backstage is responsible for orchestrating this entire indexing process. It manages the collators, decorators, the connection to the specific search engine, and the scheduling of when these indexing tasks run.

Integrator​

  1. Someone who develops one or more plugins that enable Backstage to interoperate with another software system. A user role.

  2. May refer to someone who develops software that integrates with Backstage.

JSON Web Token (aka JWT)​

A popular, compact, and self-contained open standard for securely transmitting information between parties as a JSON object. It is commonly used to verify a user's identity (authentication) and permissions (authorization). Each JWT consists of a header, payload, and digital signature separated by dots. JWTs are often encrypted, and are always signed for integrity.

This standard is a key component of OpenID Connect. For more details, see this Wikipedia article.

Kind​

Classification of an entity in the Backstage Software Catalog, for example service, database, or team. An element of the kind|namespace|name triplet that is an important concept for uniqueness.

Kind|namespace|name triplet​

The primary reference for Software Catalog entities. It is human-readable and should be unique across your Backstage instance.

Kubernetes (Backstage plugin)​

A core Backstage plugin enabling a service owner-focused view of Kubernetes resources.

Kubernetes (CNCF Project)​

Kubernetes (K8s) is an open-source platform that automates the deployment, scaling, and management of containerized applications. Originally developed at Google to manage its production workloads, it was later offered to the Cloud Native Computing Foundation (CNCF) for open-source support and maintenance.

According to its official website, Kubernetes automatically handles rollouts, rollbacks, and load balancing. It mounts storage systems, dynamically allocates containers based on resource requirements and other constraints, manages batch execution, restarts crashed containers, and more. For additional information, see the Kubernetes article on Wikipedia.

Local Package​

One of the packages within a monorepo. A package may or may not also be published to a package registry.

Monorepo​

  1. A single repository for a collection of related software projects, such as all projects belonging to an organization.

  2. A project layout that consists of multiple packages within a single project, where packages are able to have local dependencies on each other. Often enabled through tooling such as lerna and yarn workspaces

Name​

To be completed. An element of the kind|namespace|name triplet that is an important concept for uniqueness.

Namespace (catalog plugin)​

An optional attribute that can be used to organize entities. An element of the kind|namespace|name triplet that is an important concept for uniqueness.

OAuth​

Refers to OAuth 2.0, an industry-standard authorization framework that allows a website or application (the "client") to access protected resources (like user data or functionality) on a different service (the "resource server") on behalf of a user (the "resource owner"), without sharing the user's login credentials with the client application.

See OAuth 2.0 explained for descriptions of OAuth 2.0 and OIDC (which is built on top of OAuth 2.0).

Objective​

A high-level goal of a user role interacting with Backstage. For example, some objectives of the administrator user role are to maintain an instance (app) of Backstage, to add and update functionality via plugins, and to troubleshoot issues.

Offline Access​

OAuth 2.0 flow that results in both a refresh token and an access token, where the refresh token has a long expiration or never expires, and can be used to request more access tokens in the future. This lets the user go "offline" with respect to the token issuer, but still be able to request more tokens at a later time without further direct interaction for the user.

OpenID Connect (aka OIDC)​

A layer on top of OAuth 2.0 which standardises authentication. See this Wikipedia article for details.

OSS​

Open source software.

Package​

  1. A bundled collection of executable files, libraries, configuration files, metadata, and other necessary components that allow a piece of software (or a group of related software) to be easily installed, managed, and used. It's a standardized format for distributing software that simplifies installation by ensuring all dependencies are included or easily resolvable, provides integrity checks, and enables easy upgrades or removal.

  2. A package in the Node.js ecosystem, often published to a package registry.

Package Registry​

A service that hosts packages. The most prominent example is NPM.

Package Role​

The declared role of a package, see package roles.

Permission​

Specific rules or settings that define the level of access and types of actions that a user, group, or system process is allowed to perform on a particular resource. Permissions are a core component of authorization that determine "what you can do" after you've been authenticated. Permissions are properties of objects or resources. Closely related to Privilege (the terms are often used interchangeably).

Permission (permission plugin)​

  1. A core Backstage plugin and framework that allows actions to be limited to specific users.

  2. A rule that determines whether a user is authorized to access a specific resource or set of resources if a specified set of conditions exists.

By default, Backstage endpoints are unprotected; any user can perform any action on any resource. The Permission framework addresses this by enabling integrators to configure rules that specify precisely which users can access which resources and actions. Within this framework, a permission is a uniquely named set of rules (or conditions) and the results to return based on their evaluation.

An example might be a permission rule that returns false if an entity is not part of a system, where the entity and system are configured for the rule. (See Defining custom permission rules for the example.)

See the Permissions Overview and Concepts for details.

Persona (use cases)​

Alternative term for a User Role.

Plugin​

The fundamental building block that adds specific features, functionalities, and integrations to your developer portal. All functionality outside of the Backstage framework, even core features, are implemented as plugins. This modular architecture is a key differentiator of Backstage, making it highly customizable and extensible.

A plugin is a self-contained unit of code designed to perform a specific task or integrate with an external system. Instead of a monolithic application, Backstage is assembled from a collection of these independent plugins.

A single logical plugin often consists of both a frontend (UI) component and a backend (API) component.

  • Frontend plugins are typically written in React and TypeScript to provide the user interface elements such as pages, cards, sidebar items, and dashboards that developers interact with.
  • Backend plugin are written in Node.js and TypeScript, and handle data fetching, business logic, integrations with external services (like Git providers, CI/CD systems, and cloud platforms), and expose APIs for the frontend to consume.

There are different types of plugins (run yarn new to see them). The current list includes:

  • plugin - A new frontend plugin
  • backend-plugin - A new backend plugin
  • backend-module - A new backend module
  • web-library - A new web-library package
  • plugin-common - A new isomorphic common plugin package
  • plugin-node - A new Node.js library plugin package
  • plugin-react - A new web library plugin package

See Introduction to Plugins for how to create a plugin, suggest a plugin, and integrate a plugin into the Software Catalog. See Create a Backstage Plugin for how to create a frontend plugin.

See Plugin directory for a list of community driven plugins, although there is a community plugins repository that contains many more that might not be in that page.

Policy (permission plugin)​

The central component of the Backstage permission framework that dictates who can do what, to which resources, and under what conditions.

Backstage policies are implemented as functions or sets of rules that receive a request (containing information about a user and a desired permission/action on a resource) and return an authorization decision (allow, deny, or a conditional decision). Policies are independent of the authorization model, such as role-based access control or attribute-based access control. See Policy.

Policies are defined in Typescript code in the permissions framework. See Writing a permission policy for examples.

Policy Decision (permission plugin)​

A specific response to a user's request to perform an action on a list of resources. Can be either Approve, Deny or Conditional. In Backstage, policies are only responsible for decisions regarding whether requests can be approved; the requestors (typically the backend) are responsible for enforcing those decisions. See Policy decision versus enforcement.

A separate browser window that opens on top of the previous one.

Privileges​

The term privilege is not a defined abstraction in the context of the Backstage permission framework's core concepts. Instead, Backstage's authorization model is built around permissions, policies, and conditions to determine what actions a user can take on a resource. If you encounter privilege in a Backstage context, it's likely being used in a more general, colloquial sense of "level of access" or referring to a concept.

Outside of Backstage contexts, privilege typically refers to specific rules or settings that define what a user or process is allowed to do within the system, often relating to system-wide operations or capabilities. Privilege is closely related to Permission; the terms are often used interchangeably.

Procedure (use cases)​

A set of actions that accomplish a goal, usually as part of a use case. A procedure can be high-level, containing other procedures, or can be as simple as a single task.

Query Translators (search plugin)​

An abstraction layer between a search engine and the Backstage Search backend. It is an optional backend component that takes an abstract search query---which includes search terms, filters, and desired document types from a Backstage search client—--and transforms it into a concrete query that's optimized for a specific Search Engine used by Backstage.

This translation layer is crucial because it enables Backstage components to utilize the distinct features of individual search engines (like Elasticsearch or Solr) while maintaining loose coupling from their detailed interfaces. Although Backstage's pre-packaged Search Engines come with simple, built-in translators, you can implement custom Query Translators to significantly enhance and tune search results for your organization's unique context.

Refresh token​

A special token that an OAuth client can use to get a new access token when the latter expires. See OAuth Refresh Tokens.

Resource (catalog plugin)​

An entity that represents a piece of physical or virtual infrastructure, such as a database, that's required by a component. See the System Model.

Resource (permission plugin)​

A representation of an object that a user interacts with and that can be permissioned. Not to be confused with Software Catalog resources.

Role​

See User Role.

Rule (permission plugin)​

A specific type of dynamic access control associated with a resource it protects. A simple example might be "the current user can access Resource X if Condition Y is true." The catalog plugin defines a resource for catalog entities and rules to check if an entity has a given annotation.

Scaffolder​

Another name for Software Templates. (The term comes from the use of Software Templates as scaffolds for building new components and projects.)

Scope​

A string that describes a certain type of access that can be granted to a user using OAuth, usually in conjunction with access tokens.

In OAuth, access control is managed through scopes that define specific permissions granted to the application. An OAuth service can issue Access Tokens that are tied to particular sets of scopes, such as viewing profile information, or reading or writing user data. The format and handling of scopes are unique to each OAuth provider, with available scopes typically detailed in their authentication solution's documentation (see https://developers.google.com/identity/protocols/oauth2/scopes for an example).

For more information about scopes and OAuth, see OAuth and OpenID Connect.

A Backstage plugin that provides a framework for searching a Backstage app, including the Software Catalog and TechDocs. A core feature of Backstage.

Existing search technology that Backstage Search can take advantage of through its modular design. Lunr is the default search in Backstage Search. Can be one of the search engines that are pre-packaged with Backstage or chosen specifically for your instance.

Software Catalog​

  1. A centralized system that keeps track of ownership and metadata for all software in your ecosystem (services, websites, libraries, data pipelines, etc.). The catalog is built around metadata YAML files that are stored with the code, and are harvested and visualized in Backstage.

  2. The Backstage plugin that implements the Software Catalog feature. A core feature of Backstage.

The Software Catalog is a core feature of Backstage. See Backstage Software Catalog for an overview, the life of an entity in the catalog, how to configure the catalog, its architecture and high-level design, how to configure and customize it, and its API. The overview describes how the catalog works, how to add components to it, how to find software in it, and more.

Software Templates (aka Scaffolder)​

  1. A "skeleton" software project created and managed in the Backstage Software Templates tool.

  2. A Backstage plugin for creating components in Backstage. By default, it has the ability to load skeletons of code, template in some variables, and then publish the template to some locations like GitHub or GitLab.

Software Templates is a core feature of Backstage. It's also known as the Scaffolder for its utility in building new software components and projects. See Backstage Software Templates for an overview, how to configure it, add your own templates, write a template, test it, and more. The overview describes such information as how to get started, choose a template, verify your inputs, run the template, and see a demo.

System (catalog plugin)​

A collection of entities that cooperate to perform a function. A system generally consists of a handful of components, resources, and private or public APIs. See the catalog docs.

Task (use cases)​

A low-level step-by-step procedure to achieve a particular result.

TechDocs​

A documentation solution for generating and managing technical documentation in Markdown files that are stored with software component code. A core feature of Backstage. See TechDocs Documentation.

Token​

A string containing information. The format and content depend on its purpose and how it's used.

Use Case​

A purpose for which a user role interacts with Backstage. Related to Objective: An objective is what a user wants to accomplish; a use case is how the user does it.

User​

Any consumer of Backstage or Backstage products/applications. This includes individuals like employees and contractors, as well as software that interacts with the backend through an API or acts as a proxy for a person by operating the user interface.

User Role​

A class of Backstage user who has permissions to use Backstage for a particular set of use cases. One of: evaluator; administrator; developer; integrator; and contributor.