Update:

Blog post  has been published but we do not have any official docs.  I'm re-purposing this feature to cover documentation only.   

The blog does a good job of explaining why/when/how to use the different types of tokens but from a customer standpoint, there it does not explain that what APIs have limited usage.  It briefly mentions RBAC but we should go through the list of exposed endpoints and verify which requests (core Backstage included) can be used with service-service tokens and call out the ones that can't be used.  This would require engineering input

Goals

• Update the docs to include a service-service section under authentication
• Construct a table/list of endpoints that cannot be called using service-service auth
• Update the Plugin security Requirements  doc to include a link to the blog explaining the pitfalls of exposing everything by default. 

Feature Overview (aka. Goal Summary)

An elevator pitch (value statement) that describes the Feature in a clear,
concise way

Backstage supports a number of service to service auth flows . There's been some confusion over what we should support from the various discussions we've had in our forum and support channels. The most common questions have been around token usage in REST API calls. In order to understand the security needs of this feature, we need to define the usage scenarios and ask:

1. How is the token generated/extracted?
2. Where does it get used?
3. How often does it get rotated and can it be easily rotated?
4. Are there flows where audit logging is needed?

Goals (aka. expected user outcomes)

Work through the Backstage service-service auth and determine which scenarios are ideal for a particular flow. For example, static tokens may not be applicable in all cases, especially if customers need to rotate their passwords regularly. Backstage does not have the means to do this easily.

For customers that are using an OIDC auth provider, we can also explore the use of the oidc refresh endpoint as an alternative to static tokens. Customers can grab the backstageIdentity token from this endpoint and use it for their automation. This is a more secure approach since the token has a configurable expiry. See Slack discussion .

We should also try to understand which plugins support which flows, as there may be limitations that we want to document

The observable functionality that the user now has as a result of receiving
this feature. Include the anticipated primary user type/persona and which
existing features, if any, will be expanded.

<your text here>

Requirements (aka. Acceptance Criteria):

A list of specific needs or objectives that a feature must deliver in order
to be considered complete. If the feature spans across releases then good
to have scope for each release with acceptance criteria. Be sure to
include nonfunctional requirements such as security, reliability,
performance, maintainability, scalability, usability, etc.

03/06/25:
After discussing with rh-ee-mhild, the outcome of this feature would be to produce a whitepaper/blog/best practices doc describing the scenarios under which Static or JWKS tokens are acceptable for use. There may also be updates to product docs.

The following consumers will benefit from clearer docs:

1. Plugin vendors - Guidance is to limit the use of static tokens for API calls. Avoid non-GET requests for security purposes
2. Customers - product documentation on supported plugins to show which plugins have REST APIs that can use static tokens

There may be some manual testing to support our posture.

Reference tickets:

https://github.com/backstage/community-plugins/issues/2822
https://github.com/backstage/backstage/issues/28720
https://github.com/backstage/community-plugins/issues/2422
https://issues.redhat.com/browse/RHDHBUGS-110
https://access.redhat.com/support/cases/#/case/04091147

Out of Scope (Optional)

High-level list of items that are out of scope.

<your text here>

Customer Considerations (Optional)

Provide any additional customer-specific considerations that must be made
when designing and delivering the Feature. Initial completion during
Refinement status.

<your text here>

Documentation Considerations

Provide information that needs to be considered and planned so that
documentation will meet customer needs. If the feature extends existing
functionality, provide a link to its current documentation.

<your text here>