Skip to main content

Backstage

Visualize your Backstage software catalog in JupiterOne — components, APIs, systems, domains, resources, groups, and users — map which components provide and consume which APIs and depend on which resources, how systems roll up into domains, and which teams and people own each catalog entity, then monitor ownership gaps and catalog changes through queries and alerts.

Installation​

This integration connects to your self-hosted Backstage instance using the Backstage Software Catalog API and ingests the catalog entities of seven kinds: Components, APIs, Systems, Domains, Resources, Groups, and Users. It only reads GET /entities/by-query, filtered by kind. Backstage is usually hosted on your own network, so the integration normally runs on a JupiterOne Collector that can reach the Backstage backend over HTTP or HTTPS.

Configuration in Backstage​

Before you configure the integration in JupiterOne, prepare the following:

  • The Catalog API base URL of your Backstage backend. This is usually your backend.baseUrl with /api/catalog appended, for example https://backstage.example.com/api/catalog. The JupiterOne Collector must be able to reach it.

  • A static access token for the integration, unless your catalog allows unauthenticated reads. Backstage backends are secure by default, so in most installations you need one. To create it, add a static entry under the backend.auth.externalAccess key of your app-config (for example app-config.production.yaml) and restart the backend:

    backend:
      auth:
        externalAccess:
          - type: static
            options:
              token: ${JUPITERONE_BACKSTAGE_TOKEN}
              subject: jupiterone-integration
            accessRestrictions:
              - plugin: catalog
                permissionAttribute:
                  action: read

    The token can be any string without whitespace, but should be long enough that it cannot be guessed. Backstage suggests generating one with node -p 'require("crypto").randomBytes(24).toString("base64")'. The subject is any string without whitespace that identifies the caller in Backstage.

    The accessRestrictions block is optional, but recommended: without it, the token has unlimited access to every Backstage backend plugin. plugin: catalog limits the token to the catalog, and permissionAttribute with action: read limits it to read actions. Backstage applies the permissionAttribute restriction only where permission checks are enabled. See Service to Service Auth for details.

    The integration sends the token in the Authorization: Bearer <token> request header.

  • If the Backstage backend presents a self-signed or internal-CA TLS certificate, get the CA certificate in PEM format so the collector can verify the connection.

Once you have obtained the information above, proceed to JupiterOne to finalize the integration.

Configuration in JupiterOne​

To install the Backstage integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Backstage. Click New Instance to begin configuring your integration.

Creating an instance requires the following:

  • The Account Name used to identify the Backstage account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • The Catalog API Base URL of your Backstage catalog, for example https://backstage.example.com/api/catalog. It is required and must be an http or https URL that includes the /api/catalog path.

  • Optionally, the API Token created above. Leave it blank only if your catalog allows unauthenticated reads.

  • Optionally, under Additional Options, a CA Certificate to trust a self-signed or internal-CA certificate, or enable Disable TLS Verification to skip certificate validation (not recommended).

When you save the instance, JupiterOne checks the configuration by requesting one catalog entity. A rejected token, or a URL that cannot be reached, fails this check.

Data Sources​

Each data source can be enabled or disabled on its own. All data sources are disabled by default. If you enable none of them, the integration ingests only the backstage_account entity that represents your Backstage instance, so enable the catalog kinds you want to ingest. To get the full catalog graph, enable all seven.

Data SourceDescriptionEntities Created
Fetch ComponentsBackstage catalog Components (kind=component), with their type, lifecycle, and namespacebackstage_component
Fetch APIsBackstage catalog APIs (kind=api), with their type, lifecycle, and namespacebackstage_api
Fetch SystemsBackstage catalog Systems (kind=system)backstage_system
Fetch DomainsBackstage catalog Domains (kind=domain)backstage_domain
Fetch ResourcesBackstage catalog Resources (kind=resource), such as databases, buckets, and queuesbackstage_resource
Fetch GroupsBackstage catalog Groups (kind=group), such as teams and business unitsbackstage_group
Fetch UsersBackstage catalog Users (kind=user), with their display name and emailbackstage_user

Every ingested entity is linked to the backstage_account entity with a HAS relationship. The relationships between catalog entities are built only when the data sources on both sides are enabled:

  • Component to API (PROVIDES and USES) requires Fetch Components and Fetch APIs.
  • Component to resource (USES) requires Fetch Components and Fetch Resources.
  • Component to subcomponent (HAS) requires Fetch Components.
  • System to component, API, and resource (HAS) requires Fetch Systems and, respectively, Fetch Components, Fetch APIs, or Fetch Resources.
  • Domain to system (HAS) requires Fetch Domains and Fetch Systems.
  • Domain to subdomain (HAS) requires Fetch Domains.
  • Group to subgroup (HAS) requires Fetch Groups.
  • Group to user (HAS) requires Fetch Groups and Fetch Users.
  • Group ownership (OWNS) of components, APIs, systems, domains, and resources requires Fetch Groups and the data source of the owned kind.
  • User ownership (OWNS) of components and APIs requires Fetch Users and, respectively, Fetch Components or Fetch APIs.

Relationships are built from the relations Backstage reports for each entity. A relation that points at an entity that was not ingested, because its data source is disabled or it is not registered in the catalog, is skipped. An owner written without a kind (for example owner: team-a) is treated as a Group, as in Backstage. The integration does not create mapped relationships to entities from other integrations.

The integration does not collect:

  • Entity annotations (metadata.annotations).
  • API definitions (spec.definition). Each backstage_api only records whether a definition is configured, in isDefinitionConfigured.
  • Catalog kinds other than the seven listed above, such as Locations and Templates.

Click Create once all values are provided to finalize the integration.

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.

Additional resources​