How Backstage sign-in with OpenShift works and what it depends on
Platform teams want people to sign in to Backstage with the identity they already use on the cluster, and the answer depends on which Backstage auth provider is available in the release you run. The supported paths described here are a generic OIDC setup against the cluster's OAuth server, or an authenticating proxy placed in front of Backstage. Before any design work, confirm against your exact Backstage version whether a dedicated OpenShift provider exists, because the supplied material does not confirm one. The Backstage authentication documentation lists 19 built-in providers, and none of the names in that list is confirmed here as an OpenShift provider.
The integration is an identity handshake. Backstage redirects the user to the cluster's OpenID Connect endpoints, receives a token, and then resolves that identity to a catalog user through a sign-in resolver. Kubernetes itself does not represent normal users as API objects; it trusts identities presented through certificates, OpenID Connect tokens, webhooks or an authenticating proxy, so the cluster side of the design is an OIDC client registration plus the claims you choose to rely on. Confirm which claims your cluster's OAuth server emits, and whether group membership is included, before deciding how catalog ownership will be derived.
What the integration does not do is equally important. It does not grant Backstage permissions by itself, it does not replace the authorization model you configure for catalog and plugin actions, and it does not make a cluster role binding meaningful inside the portal. Sign-in only proves who the user is. Plan a separate decision for who may read or change catalog entities, run templates and see Kubernetes resources, and confirm that the OpenShift identity you map to a catalog user cannot be impersonated by a user who simply shares an email address or a name.
What you need in place before configuring OpenShift sign-in
Sign-in with OpenShift depends on five things that must agree before any configuration file changes. Each card below is a parallel prerequisite, and the team should settle them in roughly the order shown so the redirect, the cluster OAuth setup and the catalog users line up on the first attempt.
Backstage release and Node.js
Pin the Backstage release you will run and confirm its Node.js runtime before building the image. The versioning policy lists Node.js 22 and 24 as the supported pair for Backstage 1.46.0, so check that line against the release you pick. Confirm the Node.js version your build pipeline uses matches it, because a mismatch here blocks the build before sign-in is ever tested.
OpenShift version and OAuth access
Confirm the exact OpenShift version of your cluster and its OAuth server endpoints with your platform team and the OpenShift documentation for that release. The OAuth configuration is cluster-scoped, so a cluster administrator must agree to register the Backstage client and set its redirect. Ask who owns that change and how it is approved before you plan the rollout.
PostgreSQL for the backend
Provision PostgreSQL for the Backstage backend before sign-in is enabled, because the backend stores its plugin databases there in production. Sign-in tokens and session state depend on a working backend, so a SQLite development database is not a suitable base for this work. Agree on the database owner, backup schedule and who can rotate its credentials.
DNS name and TLS certificate
Choose the public hostname for the Backstage base URL and issue a TLS certificate that covers it. The OAuth redirect registered on the cluster must match this base URL exactly, including scheme, host, port and path. Any drift, such as a changed hostname after registration, produces redirect errors that look like sign-in failures.
Catalog repository with User entities
Identify the repository that holds your User and Group entities, since the sign-in resolver matches each OpenShift identity to a catalog user. Confirm that every platform user who needs access has a User entity, and decide whether those entities are maintained by hand or ingested from a source. Without a matching entity, a valid cluster login still fails to resolve.
Backstage sign-in with OpenShift or an authenticating proxy: which to choose
With the generic OIDC provider, Backstage redirects users to the OpenShift OAuth server, then receives an ID token back from the cluster's identity front end. Backstage keeps its own sign-in page, so your team controls the provider configuration and the sign-in button. Backstage's auth backend validates the token, and a sign-in resolver maps the claims to a catalog user. The Backstage authentication documentation describes this flow for each provider module.
- Login page: Users see the Backstage sign-in screen, then the OpenShift login page for the identity provider configured on the cluster.
- Identity verification: The Backstage backend validates the OIDC token. Confirm which claims your cluster emits, especially email and any group claim.
- Group delivery: Groups reach Backstage only if the token carries them or the resolver looks them up. Agree the scope and claim names with the platform team before the build.
- Attack surface: No extra component sits in the login path, but the Backstage backend stores the OAuth client secret and must receive the redirect.
- Maintenance: The OAuth client, redirect URIs and client secret must match each Backstage base URL. Retest sign-in after each cluster and Backstage upgrade.
Check that the redirect URI and sign-out behavior match the Backstage base URL in every environment.
A dedicated OpenShift provider, if your Backstage release includes one, would replace generic OIDC wiring with configuration written for the OpenShift OAuth server. Whether one exists, and which resolver and group settings it supports, depends on the release you run. Confirm this in the authentication documentation for that version before you plan around it. Do not assume a provider exists because the cluster runs OpenShift.
- Availability: Verify the provider name, module and configuration keys in the exact release you will deploy, since provider modules change between releases.
- Login page and verification: The cluster's OAuth server still presents the login page, and the Backstage backend still verifies the identity it receives.
- Groups: Confirm whether the provider maps OpenShift groups into Backstage ownership, or whether you need a custom resolver to do it.
- Maintenance: Review provider module changes during each Backstage upgrade, because provider modules follow the framework's release line.
- Fallback: If no dedicated provider exists for your release, the generic OIDC path is the documented route. Treat any community module as a plugin to vet before use.
Ask for the provider's documented options and test them against a non-production cluster before you choose this tab.
An authenticating proxy handles sign-in before requests reach Backstage, and Backstage's proxy provider reads the identity the proxy forwards. Backstage supports AWS ALB, Google IAP and Cloudflare Access as proxy providers, and these services verify signed identity assertions before forwarding them. oauth2-proxy is a separate choice. It is not one of those managed proxies, it runs as a component you operate, and it carries its own risk that needs a deliberate review.
- Login page: The proxy presents the login page, so Backstage does not handle passwords or the redirect flow itself.
- Identity verification: AWS ALB, Google IAP and Cloudflare Access verify signed assertions. Confirm each provider's verification steps in its own documentation.
- Groups: Groups come from what the proxy forwards. Confirm that the header or claim carries them and that the resolver reads it.
- Attack surface: The proxy becomes a trust boundary. If Backstage is reachable without passing through it, forwarded identity can be spoofed, so restrict network paths to the Backstage backend.
- oauth2-proxy risk: Its configuration, secrets and upgrades become part of your Backstage security surface, and a misconfigured instance can weaken the trust boundary.
Check that the Backstage backend accepts requests only through the proxy path in every environment.
Choose one sign-in path before the build starts, record it with the platform team, and name an owner for each layer. The choice affects the Backstage configuration, the cluster OAuth setup, the resolver design and the upgrade test plan. Changing it after the build starts means reworking all four, so treat the record as a design input rather than a late review item.
- Owner per layer: Name who owns the cluster OAuth client, the Backstage configuration, any proxy and the catalog user mapping.
- Trust boundary: Write down which component verifies identity and every path by which a request could bypass it.
- Groups: Record the group source, the claim or header name, and the resolver that turns groups into owners.
- Guest access: Confirm that guest sign-in is disabled in production, as the authentication documentation advises.
- Upgrade tests: Add sign-in to the regression checklist for each Backstage release and each cluster upgrade.
Have the security team approve the decision record before any production sign-in is configured.
Setting up Backstage sign-in with OpenShift in order
This sequence takes a Backstage instance from an unauthenticated install to a state where platform users sign in with their OpenShift identity, resolve to a catalog User entity, and cannot enter through a guest path. Each step ends with a check you can run before moving on.
Confirm the OpenShift OAuth endpoints and admin access
The platform team confirms that it can create OAuth clients on the target OpenShift cluster and identifies the cluster's OAuth server address and API endpoint. Confirm with your cluster administrators which identity source the cluster uses, since the sign-in resolver depends on the claims that source returns. The step is done when someone with cluster-admin rights agrees, in writing, to register the client and you have recorded the exact OAuth server address for the Backstage host. Confirm the exact endpoint names and token claims with the OpenShift documentation for your cluster version, not from memory.
Register the Backstage client with the OpenShift OAuth server
A cluster administrator creates an OAuth client for Backstage on the OpenShift OAuth server and sets its redirect URI to the Backstage auth callback path for the provider, built from the public base URL of your Backstage frontend and backend. Record the client ID and the generated client secret in your secrets vault at this point. The step is done when the OAuth client exists and its redirect URI matches the callback path character for character, including scheme, host, port and trailing path. Check the callback path against the Backstage authentication documentation for your release before registering it.
Store the client secret outside source control
The client secret goes into a secret store that the Backstage deployment reads at runtime, such as a Kubernetes Secret delivered through your normal secret workflow or an external secret manager. Reference it from the app configuration by environment variable name rather than writing the value into app-config.yaml or a Git repository. The step is done when a search of the configuration repository finds no client secret value, and the running pod or process can read the variable without printing it in logs. Restrict read access to the secret to the Backstage workload only.
Configure the OpenShift provider in app configuration
The platform team adds the OpenShift auth provider block to the Backstage app configuration, setting the OAuth server URL, the client ID and the secret reference, and the app's base URL and backend base URL so that the callback resolves to the same host users open. The configuration keys and provider module names differ by Backstage release, so confirm each key in the authentication documentation for the release you run before editing. The step is done when the backend starts without configuration errors and the sign-in page lists the OpenShift provider.
Set the sign-in resolver and remove guest access
Choose a sign-in resolver that maps the OpenShift identity to exactly one catalog User entity, typically by matching a user identifier or email claim that your catalog already uses, and do not let a missing match create a session. Remove or disable the guest provider in every environment that serves real users, because the authentication documentation advises against guest access in production. The step is done when the configuration contains a resolver for the OpenShift provider, the guest provider is absent from the production configuration, and a code review of both changes is recorded.
Test sign-in as a user with a catalog entity
Sign in with a test account that has a matching catalog User entity and confirm the browser returns to the Backstage callback path with a session, and that the session shows the expected catalog identity and group memberships. Check the backend logs for the resolved entity reference rather than inferring it from the user interface. The step is done when the login completes and the resolved entity matches the catalog record you expected, and the result is saved with the change ticket.
Confirm that users without an entity are refused
Sign in with a cluster account that has no catalog User entity and confirm that Backstage refuses the session instead of creating one or falling back to a default identity. Repeat the check with an account that has an entity but is outside any allowed domain, if your resolver enforces one. The step is done when both attempts are rejected with an error that the backend logs, and no new User entity appears in the catalog. Keep these two negative tests in the runbook so they run again after every upgrade or configuration change.
How OpenShift identities map to Backstage catalog users
This table traces each identity attribute that OpenShift can supply to the Backstage catalog field it feeds, the resolver or annotation that reads it, and the check to run first. Backstage's authentication documentation advises that every provider resolves to the same identity, so confirm which claims your cluster's token actually carries before you choose a resolver.
| OpenShift attribute or claim | Backstage field it feeds | Resolver or annotation that uses it | Check to run before choosing a resolver |
|---|---|---|---|
| User name | User entity name in the catalog | Username-based sign-in resolver matching the token to a User entity | Compare the token's username with a catalog User name for the same person, including letter case and any domain suffix |
| Email address | Profile email on the User entity | Email resolver, with allowedDomains limiting which domains can sign in | Confirm the token carries an email claim for every user, and that the value matches the profile email in the catalog |
| Group membership | Member-of relations on User and Group entities | Group membership ingested by the catalog, not set by the sign-in resolver alone | Sign in as a user in a nested group and confirm the expected Group entities appear on the user's profile |
| Subject identifier | Stable reference linking the sign-in identity to the catalog User entity | Annotation-based resolver that matches a stable ID stored on the User entity | Check whether the token includes a stable subject or UID, since display names and usernames can change |
| Token issuer and audience | Not stored in the catalog; determines whether the sign-in is trusted | Auth provider configuration that verifies the token against the cluster's OAuth endpoints | Confirm the provider validates signatures and the expected audience, and that clients cannot supply their own identity |
| Unmatched identity | No catalog entity exists for the signed-in person | Resolver order and NotFoundError, which should reject the sign-in | Test with an OpenShift user who has no User entity and confirm sign-in fails instead of creating a guest session |
Why sign-in resolvers decide who gets access
A sign-in resolver turns an identity that the provider has already verified into a Backstage catalog user, and that mapping decides what a successful login can actually do. With the OpenShift provider, the cluster has authenticated the person, but Backstage still has to decide which catalog user, and therefore which ownership and permissions, that identity receives. A weak resolver can let a valid cluster login gain access that the organization never intended. The main example is a login that succeeds in the cluster but matches no catalog entity, which should be refused rather than accepted with a default or empty identity. The Backstage authentication documentation advises against guest access in production for this reason. Confirm that every cluster user who lacks a catalog entity is denied sign-in, and test that with an account you know has no entity.
The identifier the resolver matches on matters as much as the resolver itself. Matching on a display name or a mutable email address means a renamed or reassigned account can inherit another person's catalog ownership. A stable identifier, such as the subject claim that the identity provider issues for each user, changes far less often. Before you choose, confirm with the cluster administrator which claim or user attribute OpenShift passes through for your identity provider, whether that value stays fixed when an account is renamed, and whether the same person can appear under more than one identity. Those answers decide whether a catalog entity can safely carry that identifier as an annotation or whether the mapping must rely on an attribute that is already in the catalog.
When more than one resolver is configured, the order decides which one wins. Resolvers run in the order they are listed, and a broad resolver placed first can match a user before a stricter one is ever tried. Treat the order as a security control, not as a convenience setting. Write down which resolver should handle each kind of user, place the strictest matching rules first, and make the final fallback deny access. The detailed design of individual resolvers, including allowed domains and custom resolvers, is covered on its own page, so this section only sets the OpenShift decisions: the identifier to match, the resolver order, and the behavior for users without an entity. Record those choices before the configuration is written.
Security settings to lock down for OpenShift sign-in
Backstage trusts whatever identity it resolves at sign-in, so the settings around that step decide who reaches the portal and its plugins. The cards below cover the controls that connect the cluster's identity system to Backstage. Confirm each setting against your own OpenShift and Backstage configuration before you rely on it.
Disable guest access in production
Backstage ships a guest sign-in option that is useful for local development but gives anyone who reaches the portal an identity. Confirm that the guest provider is absent from the production app-config.production.yaml and that no build or environment variable re-enables it. Test by opening the production sign-in page from a browser with no session and confirming that only the OpenShift option appears.
Store the client secret and rotate it
The OAuth client secret registered with the cluster lets Backstage exchange sign-in codes for tokens, so it should be read from a secrets store at runtime and never committed to Git or baked into the image. Record who can read the secret and set a rotation date with the platform team. After each rotation, confirm sign-in still works and that the old secret no longer authenticates.
Limit redirect and base URLs
The redirect URI and the app base URL decide where the browser returns after sign-in, so a loose value can send tokens to an unintended host. Set both to the production Backstage hostname only, and match the redirect URI registered with the OpenShift OAuth client exactly. Remove development hostnames and wildcards from both the cluster registration and the Backstage configuration.
Restrict sensitive plugins by group
Signing in proves who the user is, not what they may open. Map OpenShift groups to Backstage permissions so that only approved groups reach plugins such as scaffolder actions, Kubernetes views or audit tooling. Test with a user from each group and with a user in no group, and confirm that the denied user receives a clear refusal rather than an empty page.
Verify tokens in the backend
The Backstage backend should validate the OpenShift token or proxy assertion itself, and should not accept identity headers that the browser can set. If you front Backstage with an authenticating proxy, confirm the backend checks the proxy's signed assertion. Decide with the platform team which system is authoritative, because the Kubernetes authentication model accepts OpenID Connect tokens and authenticating proxies, and mixed trust creates gaps.
Log sign-in events
Record each sign-in attempt, successful or refused, with the user identity, the resolver used and the time, and send these records to your central log store. Logs are only useful if someone reviews failures and unexpected resolver matches, so assign that review to a named team. Confirm with your security team how long these records must be kept and who may read them.
How to verify sign-in before users depend on it
Run four checks against a staging Backstage before any platform user is told to sign in. The first is a login test for a dedicated cluster account that has a matching User entity in the catalog. Sign in through the OpenShift provider, confirm the session resolves to that catalog entity, and check that the identity shown in the portal matches the user name and groups the cluster returns. If the resolver maps the user by a different attribute than the one you expected, this is where it shows up, so record which resolver produced the match and why.
The second is a refusal test for a valid cluster user who has no catalog entity. Sign in with that account and confirm Backstage rejects the session instead of creating an entity or granting a default identity. Pair it with a check that guest access is off in the production configuration. Then run a session rejection test: replay an expired or tampered session cookie, and sign in with an account whose identity does not match the catalog user it would resolve to. Both should fail with an error, not a partial session. Confirm the exact error text with your own configuration, since messages change between releases.
Finally, test the redirect and sign-out URIs against the production hostname, not only localhost or a staging name, because the OAuth client registered in OpenShift must match the public address exactly. Repeat all four checks after every version bump made with yarn backstage-cli versions:bump, and review the template changes the Backstage Upgrade Helper shows for that range, since auth configuration is a common place for them. Use dedicated test users and cluster accounts for this work, separate from any real administrator, and remove them from the cluster groups that drive catalog access when testing ends.
Why OpenShift sign-in fails and how to fix it
This table maps common OpenShift sign-in failures in Backstage to their usual causes and the configuration check that resolves each one. Work from the symptom you see, confirm the cause in the cluster OAuth settings and Backstage backend configuration, then apply the fix, and use the sign-in troubleshooting guidance for your Backstage release for any remaining errors. Most failures trace back to a mismatch between the callback URL, the base URLs and the identity the resolver expects, so check those first.
| Symptom | Likely cause | Fix to check |
|---|---|---|
| Redirect URI mismatch after clicking sign-in | The redirect URI registered on the cluster OAuth client differs from the callback URL Backstage sends | Copy the callback URL from the backend auth config and register it exactly, including scheme, hostname and port |
| Sign-in succeeds but shows a user not found error | The resolver cannot match the cluster identity to a catalog User entity | Confirm the resolver's lookup key matches the User entity name or annotation, and that the catalog has ingested that user |
| Group membership missing from the signed-in user | Cluster groups are not synced, or group names differ between the cluster and the catalog | Confirm the groups exist on the cluster, the sync job runs, and group names in the catalog match the cluster names exactly |
| Sign-in fails after the client secret was rotated | The cluster secret was changed, but the backend still reads the old value | Update the secret in your secret store, restart the backend so it loads the new value, and keep one value per environment |
| Redirects go to an internal address or cookies do not persist | app.baseUrl or backend.baseUrl points to an internal host instead of the external route behind the load balancer or router | Set both base URLs to the external hostname and confirm the router forwards the original host and protocol headers |
| Only administrators can sign in | A group-based or fallback resolver runs before the general matching resolver in the resolver order | Reorder the resolvers so the general matching resolver runs first, then test a non-admin account in a staging environment |
| Identity headers from a proxy are trusted without checks | The backend accepts identity headers from the router or proxy without verifying signature or source | Restrict backend ingress to the proxy only, and accept identity only through a provider that verifies signatures or a trusted source |
Backstage sign-in with OpenShift: cost, effort and what you provide
Can our platform team set up Backstage sign-in with OpenShift in-house?
Yes, if your team already administers the cluster OAuth configuration, owns a Backstage instance and has engineers who can write and test sign-in resolvers. The work touches three areas that are often owned by different people: cluster identity, the Backstage auth configuration in the app config, and the catalog user model. Teams that lack one of these skills usually spend the most time on the seams between them. A partner is useful when the cluster team, the portal team and the security reviewers need a written scope and a single owner for the sign-in path.
What drives the effort of OpenShift sign-in for Backstage?
Effort is driven by five factors that interact:
- The cluster OAuth configuration, including the identity providers already attached to the cluster and how they issue tokens to users.
- The identity claims returned for each user, and whether they carry the email and the stable identifier your catalog expects.
- Resolver design, which decides how a signed-in identity is matched to a User entity and what happens when no match exists.
- The choice between the OpenShift auth provider and an authenticating proxy in front of Backstage.
- Testing across Backstage and OpenShift upgrades, because both move on their own release schedules.
What must our team provide before sign-in work starts?
The team needs to provide cluster admin access or an administrator who can make OAuth changes, a non-production test cluster that matches production identity settings, and a catalog of User entities that represent the people who should sign in. You also need to decide how groups are used, including which groups grant access to which parts of the portal and whether groups come from the cluster or from another directory. Access to a Backstage development environment and a named owner for approvals are also required. Missing any of these usually extends the engagement because the design cannot be tested end to end.
How long does OpenShift sign-in for Backstage take?
No duration is supplied for this work, so no timeline should be assumed. The time depends on how many identity sources are involved, how many resolvers you need, how complete the catalog of users is, and whether an authenticating proxy is also in scope. The scope, deliverables and timeline are agreed in writing before any work starts, so ask for a written plan that lists each phase and the reviews that gate it. Ask the provider which parts of the timeline depend on your team, such as approvals and test cluster access.
Is an authenticating proxy simpler than the OpenShift auth provider?
A proxy can be simpler to start with because it moves sign-in out of Backstage, but it changes what you must secure and operate. With a proxy, the proxy becomes the trust boundary, so you must confirm how it passes identity to Backstage and that users cannot bypass it to reach the backend directly. The OpenShift auth provider keeps sign-in inside Backstage and uses the cluster identity, which is often easier to audit for platform users. The right choice depends on whether the proxy already exists in your estate, how your security team reviews it, and whether frontend assets must also be protected. Confirm these points with your security team before deciding.
What should a quote for this work include?
A quote should follow from a written scope and list the components so you can compare providers on the same basis. Ask for the scope statement, the list of deliverables such as the configured auth provider, the resolver code and the runbook, the test cases for each sign-in path and failure mode, and the handover plan that names who receives documentation and what training is included. Also ask which items are one-time work and which recur, such as retesting after upgrades, and what changes would trigger a new quote. Ask how access to your clusters and test environments is handled during the engagement.
What goes wrong most often with OpenShift sign-in in Backstage?
The most frequent problems are mismatched identities, where the same person appears as two catalog users, and overly permissive resolvers that let users without a catalog entity sign in. Teams also see sign-in break after a cluster or Backstage upgrade because claims or configuration keys changed. Guest access left enabled in a non-development setting is another common gap. Plan test cases for each of these before go-live so that failures are caught in the test cluster rather than by users.
How DeployOpen scopes, delivers and supports Backstage sign-in with OpenShift
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including Backstage sign-in with OpenShift. Work starts from a written, fixed scope that names the cluster, the identity path and the resolver rules before any configuration changes are made.
How we scope
- We confirm the OpenShift cluster versions, the identity providers behind the cluster and the Backstage version in use.
- The written scope states whether Backstage will use the OpenShift auth provider or sit behind an authenticating proxy.
- We agree which catalog user matching rules, resolver order and guest access settings are in and out of scope.
- Scope names the Backstage and Kubernetes environments, plus any retained support after the initial build.
How we build
- We configure the OpenShift OAuth client, redirect URIs and sign-in resolvers in a non-production Backstage first.
- We test sign-in for users with and without catalog entities, and confirm unmatched identities are refused.
- We verify that guest access is disabled and that sign-in and integration tokens are kept separate.
- Configuration is kept in version control so changes to the auth setup can be reviewed and reproduced.
How we hand over
- You receive the configuration, resolver decisions and a runbook covering sign-in setup and known failure modes.
- We document how the cluster identity maps to catalog users, so platform owners can extend the rules safely.
- A handover session walks your team through testing sign-in, rotating client secrets and reviewing logs.
- Deliverables are listed in the written scope, so you can check each item against the agreed plan.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after the initial engagement.
- Retained work can cover Backstage version bumps, OpenShift upgrades and re-testing of the sign-in path.
- Support terms, response expectations and any service levels are defined in the written agreement, not assumed.
- We will ask you to confirm which upgrade and release line your organization follows before quoting ongoing work.
