Best Practices for Securing Your Backstage Instance with OAuth Providers

Introduction

Modern organizations rely on internal developer portals to speed delivery and improve developer productivity. Backstage, the open-source developer portal framework now in the CNCF ecosystem, centralizes tools, services, and documentation into a single interface. Because it becomes a gateway to many development resources, securing Backstage is critical.

OAuth/OIDC-based authentication lets you delegate identity to your corporate provider (Azure AD, Okta, Google, GitHub, etc.), reducing credential surface area while preserving a smooth developer experience. This guide outlines pragmatic, Backstage-specific best practices for securing your instance with OAuth / OpenID Connect providers.

Why Backstage security differs from a regular web app?

Backstage aggregates many systems (source control, CI/CD, service metadata, cloud consoles, secrets, etc.). That centralization means:

• A single account compromise can expose multiple downstream systems.
• Plugins may request tokens to act on behalf of users (so plugin/token handling needs attention).
• The platform uses separate frontend (React) and backend (Node/Express) components and a sign-in resolver step to map external identities to Backstage users.

High-level OAuth / OIDC workflow in Backstage

1. A user selects an auth provider on the Backstage sign-in page.
2. Backstage (frontend) redirects the user to the provider for sign-in (OAuth/OIDC authorization code flow).
3. The provider returns an authorization code to the backend callback endpoint.
4. Backstage’s auth-backend exchanges the code for tokens and establishes a session.
5. Backstage maps the identity to an internal Backstage user via a Sign-In Resolver (guest resolver is default only for dev).

Note: Backstage supports both OAuth2 and OpenID Connect (OIDC) flows. Use OIDC when you need a standardized ID Token and claims.

Key implementation best practices

1) Secure configuration management

• Never commit client secrets, private keys, or provider credentials to source control. Use a secrets manager (Vault, AWS Secrets Manager, Azure Key Vault, etc.) and environment variables for runtime.
• Keep a separate app-config.yaml (or environment overlays) for dev/stage/prod to avoid leaking production credentials into non-prod environments.

Example (conceptual): Do not hardcode secrets:

2) Use the auth-backend properly

• Backstage separates frontend and backend auth responsibilities. The @backstage/plugin-auth-backend handles the provider exchange and session creation; plugins request delegated tokens from there. Ensure you run and configure the auth backend in production and protect its endpoints.

3) Session and token handling

• Backstage’s backend should handle token exchanges and session management rather than storing access tokens in the browser. Avoid storing sensitive tokens in localStorage or sessionStorage (XSS risk). Prefer server-side sessions or secure, HTTP-only cookies with appropriate attributes (HttpOnly, Secure, SameSite) when sessions are required. OWASP session guidance applies.
• When plugins need to call external APIs, use Backstage’s standardized auth utilities (GoogleAuthApi, GitHubAuthApi, etc.) that integrate with the auth backend to request tokens on behalf of the user.

4) Short-lived tokens + refresh

• Use short-lived access tokens and refresh tokens (where the provider supports them). Backstage should refresh tokens via the backend; refresh tokens (if persisted) must be stored securely server-side and rotated when possible. Monitor token lifecycles and treat refresh tokens as high-value.

5) Identity mapping: Sign-In Resolvers & RBAC

• Configure a Sign-In Resolver to map claims from your identity provider into Backstage user identities. Do not rely on the guest resolver in production, it maps everyone to a single “guest” identity. Implement mapping rules that extract email, group membership, or external IDs and convert them to Backstage user entity refs.
• Implement RBAC/authorization in Backstage: map provider groups/claims to roles and permissions inside Backstage. Apply the principle of least privilege for plugins and catalog operations.

6) Enforce multi-factor & conditional access at the provider level

• Enforce MFA via the identity provider (Azure AD Conditional Access, Okta MFA, etc.) and use provider conditional policies (device/platform/location risk) for step-up authentication on sensitive operations. Because Backstage delegates auth, these policies are enforced centrally by the provider.

7) Network and transport security

• Require HTTPS for all Backstage endpoints and set strong TLS configurations.
• Harden CORS to only allow the origins you control (Backstage UI, internal tooling origins).
• Protect your auth callback endpoints and ensure the OAuth redirect URIs registered in the provider exactly match production endpoints (including scheme, host, and path).

8) Plugin hygiene

• Audit plugins for what permissions and tokens they request. Avoid granting plugins broad scopes unnecessarily. Review plugin code and dependency supply chain risk before enabling them in production. Use Backstage’s auth utility APIs rather than ad-hoc token handling where possible.

9) Monitoring, logging & auditing

• Log authentication events (successful/failed sign-ins, refresh failures, token revocations) and integrate logs with your SIEM. Backstage’s backend provides hooks/services for authentication events and ingests these through centralized monitoring. Configure alerts for anomalous authentication patterns.

Common pitfalls to avoid

• Guest resolver in prod. The default guest sign-in resolver should only be used for development and demos, always configure a proper resolver for production.
• Storing access tokens in the browser. Avoid localStorage/sessionStorage for tokens. Use server-side sessions or secure cookies.
• Over-privileged scopes. Request the minimum scopes required for Backstage plugins to function.
• Missing redirect URI exact match. OAuth providers validate redirect URIs strictly, mismatches will break authentication.

Quick production checklist

• Run plugin-auth-backend on a hardened backend instance and restrict access.
• Configure a proper Sign-In Resolver (map provider claims to Backstage identity).
• Use secrets manager for client IDs/secrets and do not commit them.
• Enforce HTTPS, tighten CORS, and secure cookies.
• Limit scopes and review plugin permissions.
• Enable MFA/conditional access policies at the identity provider.
• Integrate auth logs with SIEM and set alerts for anomalous auth behavior.

Conclusion

Securing Backstage with OAuth/OIDC is best done by delegating authentication and policy enforcement to a trusted identity provider, running the Backstage auth backend correctly, using secure session/token handling, and applying organization-level controls (MFA, conditional access, monitoring).

Drop a query if you have any questions regarding Backstage and we will get back to you quickly.

About CloudThat