This section describes how Backstage allows plugins to request OAuth Access Tokens and OpenID Connect ID Tokens on behalf of the user, to be used for auth to various third party APIs.
There are occasions when the user wants to perform actions towards third party services that require authorization via OAuth. Backstage provides standardized Utility APIs such as the GoogleAuthApi for that use-case. Backstage also includes a set of implementations of these APIs that integrate with the auth-backend plugin to provide a popup-based OAuth flow.
Access control in OAuth is implemented in terms of scope, which is a list of permissions given to the app. An OAuth service can issue Access Tokens that are tied to a certain set of scopes, such as viewing profile information, reading and/or writing user data in the service. The scope format and handling is specific to each OAuth provider, and the set of available scopes are typically found in the documentation describing the auth solution of the provider, for example developers.google.com/identity/protocols/oauth2/scopes.
As a part of logging in with an OAuth provider, the user needs to consent to both the login itself and the set of scopes that the app is requesting to use. This is done by loading a page provided by the OAuth provider, where a user can choose an account to log in with, and accept or reject the request. If the user accepts the login request, a token is issued, and any holder of the token can use it to make authenticated requests towards the third party service.
OAuth in @backstage/core-api and auth-backend
The default OAuth implementation in Backstage is based on an OAuth server-side offline access flow, which means that it uses the backend as a helper in order to trade credentials. A benefit of this type of flow is that it does not require the use of third party cookies, and is robust on a wide selection of browsers and privacy browsing plugins, strict security settings, etc.
The implementation also uses a popup-based flow, where auth requests are handled in a new popup window that is opened by the app. By using a popup-based flow it is possible to request authentication at any point in the app, without requiring a redirect. Because of this there is no need to ask for all scopes upfront, or interrupt the app with a redirect and forcing plugin authors to take care in restoring state after a redirect has been make. All in all it makes it much easier to make authenticated requests inside a plugin.
Component and APIs can request Access or ID Tokens from any available Auth provider. If there already exists a cached fresh token that covers (at least) the requested scopes, it will be returned immediately. If the OAuth provider implements token refreshes, this check will also trigger a token refresh attempt if no session is a available.
If new scopes are requested, or the user is not yet logged in with that provider, a dialog is shown informing the user that they need to log in with the specified provider. If the user agrees to continue, a separate popup window is opened that implements the entire consent flow.
The popup window is pointed to the
/start endpoint of the auth provider in the
auth-backend plugin, which then redirects to the OAuth consent screen of the
provider. The consent screen is controlled by the OAuth provider, and will do
things like prompting the user to log in with an account, and possibly reviewing
the set of requested scopes. If the login request is accepted, the popup window
will be redirected back to the
/handler/frame endpoint of the auth backend.
The redirect URL will contain a short-term authorization code, which is picked
up by the backend and exchanged for long-term tokens via a call to the OAuth
provider. The Access and possibly ID Token is then handed back to the main
Backstage page via
postMessage. If the OAuth provider implements offline
refresh, a refresh token will be stored in an HTTP-only cookie scoped to the
specific provider in the
To protect against certain attacks, the above flow also includes a simple nonce
check and a lightweight CSRF protection header. The nonce check is done to
protect against attacks where an attacker tricks a user to log in with an
account of the attacker's choosing in order to gather data. In the first part of
the flow where the popup is directed to the
/start endpoint, a nonce is
generated and placed in both a cookie and the OAuth state. The nonces received
in the cookie and OAuth state in the redirect handler are then checked, and the
auth attempt will fail if they're not valid. The CSRF protection for the
/logout endpoints is implemented by simply checking for the
presence of a
The target origin of the
postMessage is also of importance to keep the flow
secure. It is configured to a single value for each auth provider and
environment. Without a single configured origin, any page could open a popup and
request an access token.
The following diagram visualizes the flow described in the previous section.