How Backstage sign-in with Okta works and what it takes
Most platform teams want Okta users to sign in to Backstage and land on a catalog identity they already own. The supported method is the Backstage Okta auth provider, which is built on OIDC. Setting it up takes three things: an Okta Web Application that Backstage can authenticate against, a sign-in resolver that turns the Okta login into a catalog user, and an agreed rule for matching Okta accounts to catalog entries. Backstage ships Okta among its 19 built-in authentication providers, so no custom authentication code is needed, but the provider configuration is only half the job. The resolver is where access decisions are made, and it has to be designed deliberately.
The most important design point is that every provider should resolve to the same identity. If a user can reach Backstage through Okta, GitHub or another provider, each route should land on the same catalog user entity, or the same person can end up with duplicate identities and inconsistent ownership. Decide early which attribute is the anchor, usually the Okta email claim, and confirm that the same value exists on catalog user entities. Also decide whether guest access stays off. The authentication documentation advises against offering guest access in production, so sign-in with Okta should be the only way in. Confirm these choices with your identity team before you write the resolver.
What you need before configuring Okta with Backstage
Okta sign-in only works when the Backstage instance, the Okta organization and the software catalog are ready together. The cards below cover the items to confirm on each side before you create the Web Application. Check each one first, because a gap in the catalog or the hostnames usually shows up later as a sign-in failure.
Backstage instance on a supported line
Run a Backstage instance on the current release line, which the releases page lists as v1.55.3, and use Node.js 22 or 24, the two even-numbered releases the versioning policy supports for Backstage 1.46.0. Confirm the Node.js version in your build image and CI pipeline, not only on your laptop. Older Node.js versions are a common reason a freshly scaffolded app fails to start after an upgrade.
Okta org with Web Application rights
You need an Okta organization and an administrator account that can create an OIDC Web Application for Backstage. Confirm with Okta which admin roles your plan grants for app integrations and whether your tenant has any app creation restrictions. Ask the identity team who owns the Okta tenant, because the client ID and secret it issues will need a secure home in your secrets store.
Populated User entities in the catalog
Okta sign-in resolves each authenticated user to a User entity in the Backstage catalog. If the catalog has no User entities, sign-in succeeds at Okta but the user has no matching identity in Backstage. Confirm that your organization's users are ingested from a directory or defined as descriptors, and that each entity carries the email address that Okta returns, since the email-based resolver depends on it.
PostgreSQL for the backend
Backstage uses PostgreSQL in production and SQLite only for development, and each backend plugin gets its own logical database through Knex. Sign-in state and catalog data both depend on this database, so a production sign-in test should run against PostgreSQL rather than SQLite. Confirm the database is provisioned, reachable from the backend host and backed up before you change the auth configuration.
HTTPS hostnames for frontend and backend
Okta redirects the browser back to the Backstage backend, so you need a stable HTTPS hostname for the frontend and another for the backend that match the URIs you register in Okta. Decide the final hostnames before you create the app, because changing them later means updating redirect and sign-out URIs in Okta and in the Backstage configuration together. Confirm the certificates and DNS records with your network team.
Configure the Okta Web Application and Backstage in sequence
This sequence takes a team from an empty Okta tenant to a working Backstage sign-in, with the Okta application, the redirect and sign-out URIs, secrets, the auth provider block, the groups scope and a sign-in resolver all configured in an order that makes each check meaningful.
Create the Okta Web Application
An Okta administrator creates a new application integration in the Okta admin console, selects the OIDC sign-in method and the Web Application application type, and gives it a name the workforce will recognize on the sign-in page. Keep the assignment rules for the application in mind, because only users assigned to it or allowed by its policy can complete sign-in. The step is done when the application exists with a client ID and a client secret shown on its General tab, and the administrator has confirmed which Okta groups or users are assigned to it. Confirm the exact menu labels against the Okta version your tenant runs, since the console layout changes over time.
Set the sign-in redirect and sign-out URIs
In the same Okta application, add the sign-in redirect URI that points to the Backstage backend auth handler for Okta, using your Backstage backend base URL and the callback path documented for the Okta provider. Then add the sign-out URI for the Backstage frontend. Both values must match the scheme, host, port and path that users actually reach, because Okta rejects any mismatch. The step closes when a test sign-in attempt from a browser reaches Okta and returns to a Backstage page without a redirect URI error. Confirm the exact callback path in the Backstage authentication documentation for your release before you enter it.
Store the client ID and secret outside app-config
Copy the client ID and client secret from Okta into the secret store your platform uses, such as a Kubernetes secret, a vault or a CI variable store, and reference them from the Backstage configuration through environment variables. Do not commit the secret to the repository or paste it into app-config.yaml. Restrict read access to the service account that runs the Backstage backend. The step is done when the backend starts with the variables set and the secret does not appear in the rendered configuration or in logs. Rotate the secret through Okta if it was ever stored in plain text during setup.
Add the Okta auth provider block to app-config
Add the Okta provider under the auth section of the Backstage backend configuration, with the Okta domain of your tenant, the client ID and client secret references, and the audience of the Okta authorization server you are using. Keep the provider key and environment name consistent between the frontend sign-in component and the backend so the sign-in button and the callback resolve to the same provider. Start the backend and open the login page in a browser. The step is done when the Okta sign-in button appears and the Okta login page loads with your tenant's name.
Request the groups scope
Add the groups scope to the Okta provider's requested scopes in the auth configuration, alongside the default OpenID scopes, so the identity token carries group membership that Backstage can use for ownership and access decisions. In Okta, confirm that a groups claim is included for this application, either by adding a groups claim filter to the authorization server or by checking the claim in the token preview. The step closes when a test user's sign-in response includes the group claim in the backend log or in the decoded token preview. If the claim is missing, check the authorization server policy before changing Backstage.
Wire the sign-in resolver to catalog users
Configure a sign-in resolver for the Okta provider that maps the Okta identity to an existing User entity in the Backstage software catalog, usually by matching the Okta email claim to the catalog entity's email or by a custom annotation. Keep the resolver strict so that a user without a matching catalog entity is refused rather than created on the fly, and avoid offering guest access in production. Make sure the catalog contains the user entities that the resolver expects before testing. The step is done when a signed-in test user reaches the Backstage home page and the backend log shows the resolved user entity with the expected user reference.
Verify the full sign-in round trip
Run an end-to-end test with at least one user who belongs to each relevant Okta group, and one user who has no catalog entity, using a fresh browser session each time. Confirm that the first user signs in, sees the identity and group-based ownership they should see, and signs out, which should return to the sign-out URI you configured. Confirm that the second user is refused with a clear error and that the backend logs record the failed resolution. Record the results with the Backstage release and Okta tenant configuration so the same test can be repeated after upgrades or changes.
How Okta identities resolve to Backstage catalog users
Sign-in to Backstage with Okta is not finished when Okta accepts the user. The browser is redirected to Okta, Okta returns an ID token to the Backstage auth backend, and the backend then runs a sign-in resolver that must find exactly one matching User entity in the software catalog. The resolver is the step that decides who the session belongs to, so the identity it trusts is the identity your access model depends on. Plan the resolver before you configure the Okta application, because the claims you request in the token determine what the resolver can match on.
The two identifiers to decide on are the Okta user's email address and the Okta user ID. Email is the common choice because catalog User entities usually carry an email, and the built-in email resolver can match on it. The Okta user ID is more stable, since email addresses change when people marry, rename or move between domains. If you match on email, confirm that your Okta profiles hold verified, unique addresses and that the catalog users were imported with the same values. A mismatch in capitalization, a personal address in one system and a work address in the other, or a contractor without a catalog entry will all produce a failed sign-in rather than a silent error the user can fix.
An Okta user with no matching catalog entity should be rejected, not created on the fly. If the resolver creates users automatically, anyone who can authenticate to your Okta tenant can obtain a Backstage session, and their group memberships may be treated as trusted without a catalog record to review. Keep the rejection path deliberate: test a user who exists in Okta but not in the catalog, confirm the error message is clear, and assign ownership of the catalog import so that new joiners appear before they need access. The Backstage authentication documentation describes the resolver options and the guidance on keeping every provider resolving to the same identity.
Mapping Okta attributes and groups to Backstage identities
This table maps each Okta profile claim to the Backstage user entity field it feeds, the resolver that uses it, and the scope or Okta setting that must be in place. Read it as a checklist: confirm each claim is returned in the ID token or userinfo response before you build the resolver that depends on it. The main takeaway is that the email claim and group membership are the two values that decide whether an Okta user lands on the correct catalog User.
| Okta claim or source | Backstage field or reference | Resolver that uses it | Scope and Okta setting to confirm |
|---|---|---|---|
| User entity metadata email, and the user:default name match | Email resolver (matches the catalog User by email) | Default openid and email scopes. Confirm the email claim is present in the ID token for your authorization server and that the user profile has a verified email. | |
| sub (Okta user ID) | Stored in the sign-in identity, not the catalog User name by default | Available for custom resolvers that match on a stable identifier | Returned with the default openid scope. Use it when emails change or are reused, and confirm it is stable in your Okta org. |
| preferred_username or login | User entity name (the metadata name used in the catalog reference) | Custom resolver only, when catalog names follow Okta login names | Requires the profile scope. Confirm the claim is included in the Okta authorization server claims and that the value matches your catalog naming standard. |
| groups (custom claim) | spec.memberOf on the User entity, which drives Group ownership | Group membership is read during sign-in and used for ownership and access decisions | Requires the groups scope added to the Backstage Okta provider. Confirm a custom groups claim exists on the authorization server and filters to the groups you intend to expose. |
| Okta group filter (for example, app-specific groups) | Limits which groups become memberOf references in the catalog | Applies before the resolver maps groups to Group entities | Set in the Okta authorization server claim rules. Confirm group names match the Group entity names in your catalog, since mismatches produce orphaned ownership. |
| Catalog User reference (user:default/name) | spec.profile and the owner field on components | Resolver must return this reference or throw NotFoundError | Not an Okta setting. Confirm every Okta user you permit has a matching User entity, or sign-in fails for users without one. |
| Resolver order and allowedDomains | Determines which Okta identity becomes the signed-in User reference | Built-in resolvers run in the order you configure, with allowedDomains limiting accepted email domains | Not an Okta setting. Confirm the resolver chain rejects unmatched users rather than creating new identities from unverified claims. |
Choosing a resolver for Okta users
The email resolver takes the email claim from the Okta token and looks for a catalog User entity with the same metadata.name or email reference. It is the simplest option and the one most teams start with, because the catalog usually already carries emails from the directory import. The trade-off is that email is a mutable attribute. People change surnames, aliases get reused, and a contractor's address may later belong to someone else. Treat the email match as a convenience for linking identities, not as proof that the person is the same one.
- Simple setup: No extra annotations are needed if your catalog users already have accurate emails.
- Mutable key: An email can change or be reassigned, so the link between a sign-in and a catalog user can drift over time.
- Case and alias issues: Confirm how Okta normalizes email case and whether aliases are stored in the catalog.
- Fallback behavior: Decide what happens when no catalog user matches, and make sure that outcome is a rejection, not an empty identity.
- Review trigger: Re-check the match whenever the directory import changes shape.
Before you choose this option, check that every catalog user's email is maintained from the same source as Okta, and confirm the exact claim your Okta authorization server returns.
An Okta-derived identifier, such as the stable user ID or a value copied from a custom claim, is harder to change than an email. The resolver can match it against an annotation on the catalog User entity, so the link survives renames and address changes. The cost is the upkeep: every catalog user needs that annotation populated, usually by the same process that imports people from the directory. Users missing the annotation cannot sign in through this path, which is the intended behavior but needs a clear support route.
- Stable link: A directory-issued ID does not change when an employee's email or name changes.
- Annotation upkeep: The catalog import must write the identifier for every user, or sign-in fails for those users.
- Claim choice: Confirm which claim Okta sends for the identifier and whether it needs a custom attribute or scope.
- Mismatch handling: A value copied in error can attach one person to another account, so audit how annotations are written.
- Support path: Tell users without an annotation who to contact, instead of letting them retry indefinitely.
Ask your Backstage and Okta administrators which identifier is stable across your tenant and who owns the import that writes it.
A custom resolver lets you combine lookups and add rules that the built-in resolvers do not enforce. A common pattern is to accept only tokens whose email domain is on an allowed list, then require a matching catalog User entity before issuing a Backstage token. This narrows who can sign in, which matters when your Okta tenant has users outside the organization, such as partners or test accounts. The risk is that custom code becomes part of the security boundary, so it needs review and tests like any other access control.
- Domain allow list: Restrict sign-in to the domains you own, and reject tokens from any other domain before lookup.
- Catalog requirement: Refuse sign-in when no catalog entity exists, rather than creating a user on the fly.
- Resolver order: Confirm how a NotFoundError from one resolver moves control to the next, so a failed match does not fall through to a looser rule.
- Testing: Cover unknown users, mixed-case domains and users with two catalog entries.
- Ownership: Name the team that maintains the resolver after it is deployed.
The main risk to avoid is signing in users who have no catalog entity, because that gives them an identity Backstage cannot govern. Verify with your security team that every accepted sign-in maps to a catalog user you have reviewed.
Hardening Okta sign-in for production Backstage
Okta sign-in works in a demo long before it is safe for production. The cards below cover the settings that decide who can reach the portal, where secrets live, and which identities can create a session. Work through them together, because a gap in Okta assignment or resolver logic undoes the protection of the Backstage settings.
Turn off guest access
The Backstage authentication documentation advises against offering guest access in production. Guest sign-in lets anyone reach the portal without an Okta identity, which bypasses the assignment and resolver controls in this section. Confirm that the guest provider is absent from the production app-config.yaml and that no environment variable re-enables it. Test sign-out and sign-in with an unassigned Okta user to confirm they are refused.
Keep the client secret out of files
The Okta client secret authenticates Backstage to Okta, so anyone who reads it can impersonate the application. Do not commit it to app-config.yaml or the Git repository. Inject it at runtime through an environment variable or a secret store your platform already operates, and reference it by name in configuration. Rotate it on a schedule and after any staff change that touched the secret.
Restrict app assignments to intended groups
In Okta, the Backstage application should be assigned only to groups that should reach the portal. Assignment is the first gate, so a user outside those groups never reaches the Backstage resolver. Ask the Okta admin to confirm that the group rules do not assign everyone by default and that contractor or service accounts are excluded unless intended. Review assignments on the same cadence as your other access reviews.
Use HTTPS for all redirect URIs
The sign-in redirect and sign-out URIs registered in Okta must use HTTPS in production, and they must match the Backstage backend base URL exactly. Plain HTTP or a mismatched host lets authorization codes travel unprotected or fail in ways that tempt teams to add loose wildcards. Register only the production hostnames, remove development URIs from the production app, and confirm the sign-out URI with a real logout test.
Limit which resolver creates sessions
A sign-in resolver decides which catalog user a verified Okta identity becomes. Keep one resolver, and make it fail closed: if no catalog user matches, deny sign-in rather than creating a user on the fly. Pair it with the allowed domain checks described in the resolver guidance so that an account from an unexpected tenant or domain cannot map to a privileged identity. Test with an identity that has no catalog entry.
Confirm Okta session lifetimes
Session length, token lifetime and idle timeout are set in Okta, and they shape how long a removed or disabled user can keep using Backstage. Backstage's own session settings do not replace them. Ask the Okta admin for the current values, confirm that they match your access policy, and agree who changes them and how changes are logged.
Common Okta sign-in failures in Backstage and how to fix them
This table pairs each Okta sign-in failure teams hit in Backstage with its usual cause and the fix to apply. Read it by matching the error you see to a row, then checking the cause in your Okta app and your app-config before changing anything. The main takeaway is that most failures trace back to a mismatch between Okta's configuration and the values Backstage expects.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch error from Okta | The sign-in callback URL in the Okta Web Application does not exactly match the backend auth URL, including protocol, host, port and path. | Set the sign-in redirect URI in Okta to the backend auth handler URL for your Backstage host, then confirm it matches app-config exactly. |
| Sign-in succeeds but no groups appear | The Okta authorization server does not return a groups claim, or the groups scope was never requested by Backstage. | Add the groups scope to the provider configuration, add a groups claim filter in Okta, and confirm the claim appears in a test token. |
| NotFoundError after Okta login | The sign-in resolver found no catalog User entity matching the Okta identity, usually because the email or annotation does not match. | Align the Okta email with the catalog User email or add the matching annotation, then check the resolver order and the allowed domains setting. |
| Wrong or failing sign-out behavior | The post-logout redirect URI is not registered in the Okta app, or the sign-out target points at a host that differs from the Backstage frontend. | Register the sign-out redirect URI in Okta and set the matching frontend base URL so users return to the portal after logout. |
| Sign-in breaks after client secret rotation | The new Okta client secret was created but the running backend still holds the old value, or the secret was not stored in the environment the pods read. | Update the secret in your secrets store, roll the Backstage backend so it reloads the value, and remove the old secret in Okta only after sign-in is confirmed. |
| Browser CORS or cookie errors during sign-in | The frontend and backend are served from different origins, or the baseUrl values in app-config use a hostname that differs from the one users open. | Make the frontend and backend baseUrl values use the same public hostname and scheme, and align cookie domain and CORS origin settings with that host. |
Questions teams ask before configuring Okta with Backstage
How much effort does Okta sign-in for Backstage take?
Effort depends mostly on how many Okta app integrations, groups and identity sources you need, and on how cleanly your Okta users already map to catalog users. A single OIDC sign-in for one Backstage instance is a bounded task, but the work grows when you add group-based access, additional scopes or a second environment. Ask any partner for a written scope that lists the Okta objects to configure, the resolver logic to write and test, and the environments covered. That list is what drives the quote, and it is the same list your own team would use to estimate internal effort.
How long does a first Okta login for Backstage take to set up?
No fixed duration applies to every environment, because the time depends on access approvals, DNS and TLS readiness and how quickly someone can confirm the Okta Web Application settings. The fastest path is usually a non-production instance with a known Okta tenant, a working redirect URI and a test user whose email matches a catalog user. Plan separate time for resolver testing and for sign-out behavior, since those are often where first attempts fail. Confirm the timeline in writing with your partner or internal team once access and the environment list are agreed.
What does our team need to provide for the Okta setup?
Expect to provide four things before work starts:
- Okta administrator access, or an admin who can create a Web Application, assign it to users and configure scopes and groups
- Catalog user data, such as the user entities or the source that populates them, with emails that match Okta profiles
- DNS records and a TLS certificate for the Backstage base URL, because the redirect and sign-out URIs must match it exactly
- A named owner who can approve Okta and Backstage configuration changes and test sign-in with real accounts
Missing any of these usually stalls the work at the first login attempt.
Can an in-house platform team configure Okta sign-in for Backstage?
Yes, a platform team that already runs Backstage and manages Okta can do this work using the Backstage authentication documentation and the Okta admin console. The areas that most often need experience are resolver design, so that every identity resolves to one catalog user, and keeping production free of guest access. A partner adds value when the team lacks Okta or Backstage experience, needs an independent review of resolver logic, or must hand the setup over with written runbooks. Decide based on who will own the configuration after go-live.
Why does the redirect URI have to match exactly?
Okta rejects sign-in when the redirect URI registered in the Web Application does not match the callback that Backstage sends. The callback path is built from the Backstage base URL, so a mismatch in scheme, host, port or path will break login even when the rest of the configuration is correct. Set the base URL in the Backstage configuration first, then register the matching redirect and sign-out URIs in Okta. Re-check both after any change to DNS, a load balancer or the TLS hostname.
What changes when we add resolvers or groups later?
Adding a resolver changes how Backstage decides which catalog user a signed-in Okta identity becomes, so it should be tested against existing accounts before rollout. Adding groups usually means requesting the groups scope in Okta, confirming that the groups claim is returned, and updating permission or ownership logic that reads it. Both changes can alter access for current users, so plan a staged rollout, keep a rollback path and review the authentication documentation for the version you run. Confirm the exact configuration keys with your Backstage version before editing.
What recurs after the first Okta sign-in works?
Recurring work includes rotating the Okta client secret, reviewing Okta app assignments as people join and leave, keeping catalog user data current and retesting sign-in after Backstage upgrades. Upgrades matter because Backstage moves all packages together, so the authentication module must stay compatible with the rest of the release. Ask any partner whether ongoing support, upgrades and testing are offered as a retainer, and what is covered in each. Your own team should budget for these tasks even if the first configuration is outsourced.
What changes when Backstage or Okta is upgraded
Upgrading Backstage does not leave Okta sign-in untouched. Backstage moves all @backstage packages together, and the supported way to do that is yarn backstage-cli versions:bump, so the auth provider module for Okta rides along with the core packages on every bump. Treat each bump as a change to sign-in: after it, re-test the full Okta flow in a non-production environment, including the redirect back to Backstage, sign-out, the sign-in resolver result for a known user, and the groups that come through in the token. Check the Backstage Upgrade Helper for template changes to app-config.yaml and the auth backend module wiring before you merge the bump.
Changes on the Okta side need the same discipline. Okta can change its consent screens, claim behavior, or the scopes an application may request, and a Backstage release can change which scopes the provider asks for by default. Confirm the Web Application settings, redirect and sign-out URIs, and the groups claim in a test org after any Okta-side change or any Backstage bump. Do not assume the sign-in resolver still matches the same Okta user record after either side moves.
Decide now which release line your team runs, because that choice determines how fast you must act. The versioning policy describes a main line shipped monthly and a next line shipped weekly, and says high and critical severity vulnerabilities are backported to releases from the last 6 months where feasible, while other security fixes may be backported. A team that stays on an older line may fall outside that window and have to make a larger jump later. Read the versioning policy and schedule a sign-in regression test as part of each upgrade cycle, so a security patch does not wait on an untested sign-in path.
How DeployOpen scopes and delivers Backstage sign-in with Okta
DeployOpen is a Chainscore Labs company that plans, implements, hardens and documents self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Backstage sign-in with Okta, we start with a written scope covering the Okta application, the Backstage configuration and how Okta users map to catalog users.
How we scope
- We confirm the Okta org type, the Web Application settings and the redirect and sign-out URIs for each Backstage environment.
- We agree which default and additional scopes, including any group claims, the sign-in needs and who owns that Okta configuration.
- We document the user-to-catalog matching rule and which users may sign in, so the written scope is clear before work starts.
How we build
- We configure the Okta OIDC provider in Backstage's app-config and set the sign-in resolver so each Okta identity resolves to one catalog user.
- We disable guest access for production and test that unmatched Okta accounts are refused rather than admitted without a catalog entity.
- We verify sign-in, sign-out, group-based access and resolver behavior in staging before any production change is requested.
How we hand over
- You receive the configuration, the Okta application settings and the resolver logic, documented for your own administrators.
- We record the test cases used for sign-in, sign-out and failed matching, so your team can repeat them after changes.
- We walk your identity and platform engineers through the runbook for rotating the client secret and adding Okta groups.
How we support
- Ongoing support, Backstage upgrades and continuous testing are available as retainers after the fixed-scope delivery ends.
- Where a Backstage release changes the Okta provider or resolver API, we include that change in the upgrade plan for your environment.
- Your team should confirm Okta-side changes, such as group rule edits or app assignments, are routed through a change process we can review.
