backstage-auth

Backstage Authentication and Identity

Wire an identity provider into Backstage, map its users onto catalog entities, and tell apart the five ways sign-in fails.

Preconditions

• Release line from backstage.json. Backend generation: createBackend() + backend.add(import('@backstage/plugin-auth-backend')) is the new backend system; a createRouter in packages/backend/src/plugins/auth.ts is legacy — migrate it before adding auth modules.
• Frontend generation: SignInPageBlueprint from @backstage/plugin-app-react + createFrontendModule is NFS; a components: { SignInPage } option on createApp from @backstage/app-defaults is legacy.
• Which provider is meant for sign-in and which only delegates access to third-party APIs. These are different jobs on the same config tree and most misconfigurations start here.
• Exact factory and resolver signatures (createOAuthProviderFactory, createProxyAuthProviderFactory, authProvidersExtensionPoint, the ctx helpers) read from the installed @backstage/plugin-auth-node types, not from memory.
• Anything requiring a new OAuth app registration, a client-secret rotation, or an IdP-side change is external mutation: stop and return a BLOCKED report with the exact redirect URI and scopes needed.

Procedure

1. Inventory before changing. Read every auth: block across app-config.yaml, app-config.production.yaml and local overrides, the auth imports in packages/backend/src/index.ts, and the app's sign-in component. Print the effective merge with yarn backstage-cli config:print --lax. Note auth.environment — only the provider sub-block matching it is loaded.
2. Classify each provider. A provider is a sign-in provider only if it has signIn.resolvers in config or a signInResolver in code. Providers used purely for API delegation (SCM tokens, Google APIs) are configured under auth.providers.<id>.<env> with client credentials and no resolver, and are consumed in the frontend through their *AuthApiRef. Adding a resolver to a delegation-only provider silently creates a second sign-in path.
3. Configure the provider block and register its module.
   • Credentials live at auth.providers.<id>.<env>.clientId / clientSecret, sourced from env vars.
   • callbackUrl is optional and defaults to <backend.baseUrl>/api/auth/<id>/handler/frame. Set it explicitly only when an ingress rewrites the path.
   • Add backend.add(import('@backstage/plugin-auth-backend-module-<id>-provider')) after @backstage/plugin-auth-backend. Confirm the package name and its exports from the installed package; provider ids and module names do not always match the vendor's name.
4. Ingest users and groups before wiring a resolver. Every built-in resolver is a catalog lookup and cannot work against an empty catalog. Use an org provider — @backstage/plugin-catalog-backend-module-github-org (config under catalog.providers.githubOrg), or the MS Graph / GitLab / LDAP equivalents — or a custom EntityProvider (backstage-catalog). Verify the User entities exist before touching sign-in config.
5. Choose exactly one sign-in resolver, in the provider's signIn.resolvers list.
   • Provider-agnostic built-ins: emailMatchingUserEntityProfileEmail, emailLocalPartMatchingUserEntityName. Provider-specific ones such as GitHub's usernameMatchingUserEntityName are listed in that provider's doc page.
   • Always set allowedDomains on emailLocalPartMatchingUserEntityName; without it any account whose email local part matches an entity name can sign in.
   • More than one resolver, or more than one sign-in provider, is acceptable only when they provably resolve the same human to the same entity ref. Otherwise it is an account-takeover path.
6. Write a custom resolver only when no built-in fits.
   • Backend module with pluginId: 'auth' (exact) and a unique moduleId, registering through authProvidersExtensionPoint with providerId matching the config key exactly.
   • Pass signInResolver to createOAuthProviderFactory({ authenticator, ... }); proxy-based providers use the proxy factory instead. Read both signatures from the installed @backstage/plugin-auth-node.
   • Remove signIn.resolvers from config first: config resolvers take priority over code resolvers, so leaving them in makes the module dead code.
   • Prefer ctx.signInWithCatalogUser. Drop to ctx.findCatalogUser + ctx.resolveOwnershipEntityRefs + ctx.issueToken({ claims: { sub, ent } }) only for custom ownership. resolveOwnershipEntityRefs includes only groups with a direct MEMBER_OF relation by default — the usual cause of missing ownership in nested group trees (backstage-permissions).
7. Use profileTransform on the same factory for authorization and display fields. That is where you validate the upstream response, shape displayName / email / picture, and throw to reject a user outright — not the resolver.
8. Wire the app-side sign-in page.
   • NFS: SignInPageBlueprint.make({ params: { loader: async () => props => <SignInPage {...props} provider={{ id, title, message, apiRef }} /> } }), registered via createFrontendModule({ pluginId: 'app', extensions: [signInPage] }).
   • SignInPage and ProxiedSignInPage come from @backstage/core-components; the providers array form accepts 'guest' alongside provider configs, and can be selected conditionally off configApi.getString('auth.environment').
   • Behind an auth proxy (AWS ALB, Azure EasyAuth, Cloudflare Access, Google IAP, OAuth2 Proxy) use ProxiedSignInPage provider="<id>"; it only calls /refresh. Extra provider headers go through its headers prop, which may be sync or async.
   • enableExperimentalRedirectFlow: true at the config root replaces the popup with a full redirect.
9. Keep guest access out of production. auth.providers.guest: {} is development-only; userEntityRef and ownershipEntityRefs customise the identity. dangerouslyAllowOutsideDevelopment: true is required anywhere else — never set it without explicit authorization.
10. Attach tokens correctly in frontend plugin clients.
    • Calls to Backstage backends: use fetchApiRef from @backstage/core-plugin-api, which adds the Backstage token itself. Do not read identityApiRef.getCredentials() and build the header by hand. Resolve base URLs through discoveryApiRef.
    • Calls to third-party services: take a short-lived token from that provider's *AuthApiRef (githubAuthApiRef and friends) with the scopes actually needed, or from scmAuthApiRef when the target host varies. Extend SCM coverage with ScmAuth.merge(ScmAuth.forGithub(...)) in the app's API factories.
11. Use the auth core services for backend-to-backend calls.
    • httpAuth.credentials(req) turns an incoming request into credentials; auth.getPluginRequestToken({ onBehalfOf, targetPluginId }) mints the outgoing token; await auth.getOwnServiceCredentials() supplies onBehalfOf for self-initiated work such as scheduled tasks.
    • Mint a token immediately before each request. Never store or reuse one.
    • Narrow principals with auth.isPrincipal(credentials, 'user' | 'service').
    • In the new backend system ownership refs are not read off the token's ent claim; get them from the userInfo service.
12. Grant non-browser callers access through backend.auth.externalAccess.
    • type: static with options.token and options.subject; generate the token with node -p 'require("crypto").randomBytes(24).toString("base64")'.
    • type: jwks with url, issuer, algorithm, audience, subjectPrefix; verified subjects get an external: prefix.
    • Always add accessRestrictions (plugin, permission, permission attribute). An entry without them has unlimited access to every plugin.
    • backend.auth.pluginKeyStore static ES256 keys are for multi-replica deployments needing stable plugin-to-plugin signing.
13. Treat the OAuth allowlists as hardened. These apply where Backstage acts as an OAuth server for MCP clients.
    • CIMD is stable: auth.clientIdMetadataDocuments.enabled: true, with optional allowedClientIdPatterns and allowedRedirectUriPatterns. auth.experimentalClientIdMetadataDocuments survives as a deprecated alias.
    • The block belongs under the top-level auth:, never backend.auth:.
    • Patterns are matched per URL component, not against the whole URL string. Wildcards do not cross host or path boundaries; a pattern without an explicit protocol is rejected; redirect URIs with embedded credentials are always rejected; a wildcard port no longer implies any path, so write http://localhost:*/*, http://127.0.0.1:*/*, http://[::1]:*/*.
    • Setting allowedClientIdPatterns replaces the built-in Claude and VS Code defaults entirely; the Backstage CLI client stays allowed regardless.
    • CIMD requires the new frontend system plus the @backstage/plugin-auth frontend plugin in packages/app. On a legacy app it cannot work at all.
    • auth.experimentalDynamicClientRegistration (DCR) is deprecated, logs a startup warning, and must not be used for new setups. Migrate existing ones to CIMD.
14. Pin signing keys when tokens must survive restarts. auth.keyStore.provider: static with ES256 keys (privateKeyFile in PKCS#8, publicKeyFile in SPKI; the first key signs, later keys only validate, which is what makes rotation safe). The default is ephemeral in-memory keys.