How Backstage sign-in with Microsoft Entra ID works
Your platform team needs employees to sign in to Backstage with their Entra ID accounts and land on the right catalog identity. Backstage uses its built-in Microsoft authentication provider, the Azure provider described in the Backstage authentication documentation, which signs users in over OpenID Connect. The work has two parts: registering an application in Entra ID so Backstage can request tokens, and designing the sign-in resolvers that decide which catalog user each Entra ID account maps to. The provider only proves who the user is. It does not decide which catalog entity that person owns, and that matching decision is where most access problems start.
The Backstage authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity, and it advises against offering guest access in production. For this topic, that means the Entra ID sign-in path should produce the same user reference that other sign-in methods would produce for the same person, so ownership, group membership and permissions do not depend on how someone happened to log in. Guest access should be off before any pilot users are invited, because a guest identity has no catalog entity to anchor ownership or permissions. Confirm the current guest settings in your configuration before go-live, not after.
Resolver design is a decision you make before writing configuration. Ask which Entra ID claim is trusted as the match key, whether the tenant is single or multi-tenant, and which accounts exist in the directory without a mailbox or a catalog entry, such as service or shared accounts. Each answer changes which resolver you use and how the domain restriction is set. Plan a test sign-in for each account type your organization actually has, and record which catalog user each one resolves to, so the mapping is verified rather than assumed.
What you need before configuring Entra ID sign-in
Entra ID sign-in touches your Microsoft tenant, your Backstage release, and your catalog data at the same time. Confirm each prerequisite below before you create anything, because a missing role or a mismatched user record shows up later as a failed sign-in with little detail.
Entra tenant and admin roles
Confirm which Entra tenant the users belong to and who can create an app registration there. Someone with the Application Administrator or Cloud Application Administrator role can create the registration, but granting admin consent for Graph permissions usually needs a Global Administrator or Privileged Role Administrator. Agree that person in advance, or the registration will sit waiting for consent. If you serve users from more than one tenant, decide now which tenant owns the registration.
Backstage release and Node.js line
Check the latest release on the Backstage GitHub releases page before you start, and pin your app to that release line. Backstage supports exactly two adjacent even-numbered Node.js releases, so confirm which pair applies to your Backstage version in the versioning policy and install one of them in your build and runtime images. Authentication code changes between releases, so verify the provider configuration keys against the version you run.
Catalog users and groups
Entra sign-in only works when the signed-in identity resolves to a catalog entity. Decide which users and groups will exist as User and Group entities, and how those entries get created, either by a catalog provider or by a manual descriptor. Confirm that the email addresses in Entra match the emails in your catalog, because the default resolvers depend on that match. Users with no catalog entry will be refused at sign-in.
HTTPS base URL and redirect target
Choose the public HTTPS base URL for the frontend and the backend before you register the app, since the redirect URI in Entra must match it exactly. Plan separate values for development and production so the production redirect URI is not reused by a test instance. Confirm your DNS record, TLS certificate and any reverse proxy path rules that route the auth callback to the backend.
PostgreSQL backend
Production Backstage uses PostgreSQL, and the auth plugin stores its own state in a logical database of its own. Provision the PostgreSQL instance and its credentials before configuring sign-in, and confirm that the connection settings you plan to use work from the backend pods or hosts. Sign-in problems and database problems can look alike, so a verified database connection removes one variable from troubleshooting.
Secrets storage for client credentials
The Entra client secret and tenant identifiers should be stored in your secrets manager and injected at runtime, not written into a configuration file committed to source control. Record who owns the secret and when it expires, because an expired client secret stops sign-in without any code change. Confirm how your platform rotates secrets and where the rotation is documented.
Configuring the Entra ID app registration and Backstage provider
This sequence creates the Entra ID app registration, grants Backstage the Microsoft Graph access it needs, and wires the Microsoft auth provider into app-config with resolvers that match each signed-in user to a catalog entity. The output is a working sign-in in a test browser and a clear record of which catalog user each identity matched.
Create the Entra ID app registration
An identity administrator in the tenant that holds your workforce accounts creates a new app registration in the Microsoft Entra admin center, choosing a name that identifies the Backstage environment (for example, a separate registration for staging and production). Record the Application (client) ID and the Directory (tenant) ID, because both go into the Backstage configuration later. Confirm that the registration is in the tenant your users sign in to, since a registration in the wrong tenant produces sign-in errors that look like permission problems. Check: the registration appears in the directory with both IDs visible on its overview page.
Set the redirect URI to the Microsoft auth handler
In the registration's authentication settings, add a web redirect URI that points to the Microsoft provider handler on the Backstage backend, using the exact scheme, host and path of your backend base URL followed by the auth handler path for the Microsoft provider. Any difference in scheme, port, trailing slash or host causes the callback to fail after the user approves sign-in, so copy the value from your app-config rather than retyping it. Use a separate redirect URI for each environment. Check: the URI is listed under web platform redirect URIs and matches the backend base URL in your configuration exactly.
Create a client secret and store it securely
Under certificates and secrets, create a client secret for the registration and copy its value immediately, because Entra ID shows it only once. Store the value in your secrets manager or the environment variable your Backstage deployment reads, not in a committed app-config file. Note the expiry date that Entra ID assigns so the renewal is scheduled before sign-in breaks. Check: the secret value is available to the Backstage backend process as an environment variable, and a calendar reminder or ticket exists for the expiry date.
Add the Microsoft Graph permissions
Under API permissions, add the Microsoft Graph delegated permissions that Backstage needs to read the signed-in user's profile and group membership. Confirm the exact permission names against the current Backstage Microsoft provider documentation, because the set that the resolvers depend on determines which claims and group data reach Backstage. Keep the list to what the resolvers and catalog ingestion use, since broader permissions widen what a compromised client can read. Check: the permissions list shows each Graph permission with the status Not granted, and you have written down the list that the reviewer approved.
Grant admin consent for the tenant
A user with the Global Administrator or Privileged Role Administrator role selects grant admin consent for the directory so the delegated permissions apply to all users in the tenant without a consent prompt for each person. Admin consent is a tenant-wide decision that should be recorded with the change ticket, because it affects every user who signs in through this registration. If your tenant restricts user consent, this step is the only way the permissions take effect. Check: every permission shows Granted for your organization, and a test sign-in does not prompt a standard user for consent.
Configure the Microsoft provider in app-config
In the auth section of the Backstage backend configuration, add the Microsoft provider under the sign-in environment you run, setting the clientId to the Application (client) ID, the tenantId to the Directory (tenant) ID, and the clientSecret to a reference to the environment variable from step three. Add a domain hint for a multi-tenant audience so that Entra ID routes users straight to their home tenant instead of showing an account picker, using the domain value your identity team confirms. Set the sign-in resolvers in the same block, starting with the email-based resolver and adding the annotation or fallback resolvers your catalog data supports, in the order you have agreed. Check: the backend starts without configuration errors and the sign-in page shows the Microsoft option.
Test sign-in and confirm the catalog match
Open Backstage in a private browser window, select Microsoft sign-in, and sign in with a test account that has a matching User entity in the catalog. Then review the backend logs for the resolver that matched the identity and the catalog user reference it returned, since this confirms the mapping works before wider rollout. Repeat with a user from a second tenant, if you have one, to confirm the domain hint behaves as intended. Check: the test user lands on the Backstage home page under the expected catalog user, and the log entry names the resolver that succeeded. Users without a matching entity should receive a clear error, not a guest session.
Choosing among the four sign-in resolvers
Resolver order decides which catalog user a Microsoft sign-in becomes, so set it deliberately before the first user signs in. Backstage's Microsoft provider tries its resolvers in the order you configure them and accepts the first one that finds a matching catalog User entity. The four options match on email, on the Microsoft user ID stored in a catalog annotation, on the username, and on the fallback for accounts with no email address. A resolver that cannot find a match should throw a NotFoundError so Backstage moves to the next one. Any other error stops the chain. Confirm the exact resolver names, their order semantics and the annotation keys in the authentication documentation for your Backstage version before you write the configuration.
The most important control is that every sign-in ends at a catalog entity you already trust. The Backstage authentication documentation advises configuring resolvers so every provider resolves to the same identity and not offering guest access in production. A resolver that accepts any valid token and invents a user, or a permissive fallback that matches on a loosely checked claim, lets an account that was never provisioned into your catalog act as a real user. Pair the resolvers with a tenant check and an allowed-domain restriction, and test with an account that has no catalog entity to confirm the sign-in is refused.
The no-email case needs a decision, not a default. Users without a mail attribute cannot be matched by email, so you must choose which identifier links them to the catalog. The user principal name is readable and easy to audit, but it changes when people are renamed or their domain changes. The object ID is stable for the life of the account, but your catalog entities must carry it in an annotation, which means your ingestion process has to populate it. The username is the weakest choice because names can collide across directories. Check which claims your tenant actually returns for these accounts, and record the chosen identifier in the sign-in design so the catalog owners know what to populate.
Mapping Entra ID attributes to Backstage catalog users
This table shows which Entra ID or Microsoft Graph value feeds each Backstage sign-in decision, from the resolver that matches a user to a catalog entity to the controls that limit who can sign in. Read each row as a question to answer in your tenant before you choose a resolver, because the fields returned depend on your Graph permissions and directory configuration. The main takeaway is that the email resolver depends on a verified mail claim, so users without email need a deliberate fallback rather than an open door.
| Entra ID or Graph value | Backstage field or control | How it is used | What to confirm in your tenant |
|---|---|---|---|
| User principal name | Sign-in name and fallback match | Often the basis for a user entity name when no email claim is used | Whether UPNs follow your naming convention and are unique across tenants |
| Primary email (mail or verified email claim) | Email sign-in resolver, allowedDomains | Matched to the catalog User entity spec.profile.email to resolve the identity | Which claim your app returns and whether guest or external addresses appear |
| Object ID (oid) | Stable identifier annotation or resolver key | Stays constant when a UPN or email changes, so it suits a long-lived link to the catalog entity | That oid is included in the token and that teams agree on storing it as an annotation |
| Tenant ID (tid) | Domain hint and issuer validation | Limits sign-in to your directory and can pre-select the tenant for multi-tenant apps | Whether the app registration is single-tenant or multi-tenant, and which tenant IDs are accepted |
| Group membership (Graph memberOf) | Group ownership and catalog Group references | Maps directory groups to Backstage Group entities so ownership follows team membership | That the GroupMember.Read.All or equivalent permission is granted with admin consent and that groups are not nested beyond what you expect |
| Users without email | Fallback resolver using UPN or object ID | Lets accounts with no mail attribute sign in only when a catalog entity already exists for them | Which service accounts or contractors lack mail, and whether they should sign in at all |
| Domain hint (domain_hint parameter) | Sign-in routing, not an access control | Sends users straight to the correct tenant or domain at the sign-in prompt | That the hint is set for your primary domain and that it does not replace server-side checks |
| Allowed domains (allowedDomains) | Server-side sign-in restriction | Rejects tokens whose email domain is not on the list, regardless of who the user is | Your full list of accepted domains, including any subsidiary domains that must be covered |
Hardening Entra ID sign-in for production
Sign-in is the front door to your developer portal, so the controls around Entra ID matter as much as the setup itself. The cards below cover the credentials, the permissions, the tenant boundary, the resolvers and the logs that together decide who can get in and which catalog identity they become.
Client secret storage and rotation
The Entra ID app registration uses a client secret that Backstage reads from configuration. Keep the value in your secret manager and inject it at runtime, never in the app-config file committed to Git. Ask who owns rotation, how often it happens, and what breaks if the old secret is removed before the new one is deployed. Overlapping two valid secrets during rotation avoids a sign-in outage. Confirm the expiry date of the current secret so it does not lapse unnoticed.
Least-privilege Graph permissions
Sign-in needs only the delegated permissions that the chosen resolver and sign-in flow actually read. Review the Microsoft Graph permissions granted to the registration and remove any application-level permissions that are not required by a catalog import. Grant admin consent deliberately, record who consented and when, and re-check consent after each change to the permission list. Broad directory read access makes a compromised registration more damaging.
Restricting sign-in to expected tenants
A multi-tenant app registration accepts users from any Entra ID tenant unless you restrict it. Decide which tenant or tenants may sign in, and enforce that boundary in the authentication configuration as well as the app registration audience. Pair this with domain restrictions on the resolver so that a valid Microsoft account from an outside organization cannot create a catalog identity. Test with an account from a non-approved tenant to confirm it is refused.
Disabling guest access in production
Backstage ships a guest sign-in option intended for local evaluation. Turn it off in production configuration and confirm that no environment variable or fallback re-enables it. Guest users have no real identity, so ownership, audit and permission decisions made for them cannot be traced to a person. Also check that Entra ID B2B guest accounts from partner tenants are handled by the same tenant and domain rules as any other external user.
Verifying resolver identity consistency
Each sign-in resolver should map a user to the same catalog user entity, whichever provider or path they used. Test the primary resolver with a user who has an email address, then the fallback that matches on the user principal name or object ID, and confirm both return one identity. A mismatch can create duplicate users or give a person the ownership of another team. Keep a written test case for every resolver in the order it runs.
Audit logging of sign-in events
Record sign-in attempts, successful resolutions and refusals so that security reviews can answer who entered the portal, when, and through which resolver. Send these events to the log platform your security team already monitors and set retention to match your policy. Check that logs record the Entra ID tenant and the resolved catalog identity, but never the client secret or access tokens. Review refusals regularly, since they reveal misconfiguration and probing.
Common Entra ID sign-in failures and fixes
This table lists the sign-in failures teams hit most often when connecting Backstage to Microsoft Entra ID, with the likely cause, the check to run and the fix for each. Work down the rows in order of the sign-in flow, from the browser redirect through token exchange to resolver matching, because an early failure hides later ones. Confirm exact error text and configuration keys against your own Backstage version and Entra ID tenant.
| Failure | Likely cause | Check | Fix |
|---|---|---|---|
| Redirect URI mismatch after sign-in | The redirect URI registered on the Entra ID app registration does not match the callback URL Backstage sends, often because of a different host, port or path between staging and production. | Compare the redirect URI in the app registration's Authentication blade with the auth backend callback URL built from your app's base URL. | Add the exact callback URL for each environment as a Web platform redirect URI, then retry the sign-in in a new browser session. |
| Admin consent required for Graph permissions | The app registration requests Microsoft Graph permissions that a tenant administrator has not granted, so the consent prompt is blocked for ordinary users. | Open the API permissions blade and check whether each permission shows granted status for the tenant, not only as requested. | Have a tenant administrator grant admin consent for the tenant, then confirm the status changes before testing with a standard user. |
| NotFoundError for a user with no email claim | The sign-in resolver matches users by email, but the token or Graph profile for that user carries no email value, so no catalog user is found. | Check the user's Entra ID profile for a mail or userPrincipalName value and look at the resolver logs for NotFoundError. | Use a resolver that matches on another attribute the catalog user carries, such as an annotation or user principal name, and map that attribute in the catalog entity. |
| Multi-tenant user blocked at sign-in | The user belongs to a different Entra ID tenant from the one Backstage expects, and no domain hint steers the login to the correct tenant. | Reproduce with the user's home tenant domain and see whether the login page offers the wrong account or fails outright. | Set the domain hint option in the Entra ID provider configuration for the expected tenant, and test users from other tenants to confirm the expected behavior. |
| Wrong tenant ID in configuration | The tenant ID in the Backstage configuration belongs to another directory, or a placeholder was left in place when the config moved between environments. | Compare the configured tenant ID with the Directory (tenant) ID shown on the app registration overview page. | Correct the tenant ID in each environment's configuration file, restart the backend and confirm sign-in reaches the expected directory. |
| Expired client secret | The client secret used by the auth backend reached its expiry date and Entra ID now rejects the token exchange. | Open Certificates and secrets on the app registration and check the expiry date of the secret stored in your secrets manager. | Create a new client secret, store it in the secrets store used by the deployment, roll it out, and remove the expired secret. Record the expiry date in your renewal calendar. |
| User signs in but has no catalog entity | The resolver finds no matching user entity, and the deployment allows sign-in without one, so the user gets a session with no catalog identity. | Confirm whether a catalog User entity exists for the signed-in person and review how the sign-in resolver handles a missing match. | Make the resolver fail closed so users without a catalog entity are refused, and provision their User entities through your org data import before they sign in. |
| Guest access enabled in production | A guest sign-in provider was left on from development, so people can reach the portal without resolving to an Entra ID identity. | Search the production configuration for guest provider settings and confirm that no unauthenticated access path is active. | Remove the guest provider from production configuration and test that an unauthenticated request to a protected API is refused. |
Questions teams ask before configuring Entra ID sign-in
How much effort does Entra ID sign-in for Backstage take, and what drives it?
Effort depends mostly on three things: the tenant policy around app registrations and consent, the number of sign-in resolvers you need, and how clean your catalog user data is. A single tenant with a clear owner for app registrations and a catalog that already contains user entities is a much smaller job than a multi-tenant setup where users arrive from several directories. Each resolver you add needs a test case, and each mismatch between an Entra ID account and a catalog user adds investigation work. Ask the partner to show how they will count these items in the written scope before you agree on effort.
Can an internal team set up Entra ID sign-in without a partner?
Yes, if your team already runs Backstage and has someone who can read the Backstage authentication documentation and work with Entra ID administrators. The steps are well defined: register the application, set the redirect URI, grant Microsoft Graph permissions, obtain admin consent, configure the provider, and choose resolvers. The harder parts are the decisions: which resolver can match a user to a catalog entity without allowing the wrong person in, and how to handle users outside your primary tenant. A partner is useful when those decisions need review by security and identity teams, or when the internal team lacks time to test them.
What does the identity team need to provide for this work?
The identity team needs to make three things available. First, someone with the right to create or approve app registrations in the Entra ID tenant. Second, an administrator who can grant admin consent for the Microsoft Graph permissions that Backstage requests, because user-level consent may not cover them in your tenant. Third, a decision on which tenants and domains may sign in. Your team should also confirm the redirect URI that will be used in each environment, since it must match the deployed Backstage address exactly. Ask the identity team early, because consent and approval steps often decide the schedule more than the configuration does.
How long does the work take when approvals and catalog state are involved?
The duration is not fixed by the technology. It depends on how quickly your organization approves app registrations and admin consent, and on whether the catalog already holds user entities that match your directory. If users must be imported or matched before sign-in works, that data work can take longer than the sign-in configuration itself. Ask any partner to list the approval gates, the people who own each gate, and the catalog checks that must pass before go-live, and to tie the schedule to those dependencies in the written scope rather than to a generic number of days.
Is Backstage free to use, and what does implementation cost?
Backstage is open source under the Apache License 2.0 (Apache-2.0), according to its GitHub repository, and the project itself does not offer a paid edition. The license cost is therefore zero, but running Backstage is not free. You pay for the infrastructure that hosts it, the database and cache it depends on, the engineering time to operate and upgrade it, and any implementation work. Implementation cost is a separate line item. It covers configuration, testing, documentation and handover, and it is quoted from the agreed scope. Cost recurs for hosting, upgrades and support, while the sign-in setup itself is largely one-time work.
What should we ask for in a fixed-scope quote for this work?
Ask for a written scope that lists each deliverable by name: the app registration settings, the redirect URIs for every environment, the Microsoft Graph permissions requested, the admin consent steps, the domain hint behavior, and each resolver with its matching rule. The quote should state which party performs each approval step, which tests prove each resolver, and what documentation and handover you receive. Also ask what is excluded, such as catalog data cleanup, changes to your tenant policy, and sign-in for other identity providers. Finally, ask how changes to scope are priced and approved before work starts, since most engagements are agreed in writing before work begins.
What breaks most often after Entra ID sign-in goes live?
The most common failures come from configuration details rather than from the platform. A redirect URI that differs by a trailing slash or hostname from the deployed address causes sign-in to fail after the Microsoft prompt. Missing admin consent leaves users blocked on a permission screen. A resolver that matches on email can fail when a user's primary email differs from the one in the catalog, and a user without email needs a resolver that matches on another attribute. Check each of these in a staging environment, and keep guest access turned off in production as the Backstage authentication documentation advises.
Keeping the Entra ID configuration through Backstage upgrades
Treat the Entra ID sign-in configuration as part of every Backstage upgrade, not as something set once and left alone. Each version bump made with yarn backstage-cli versions:bump moves all @backstage packages together, and the auth provider module, the sign-in resolvers and the auth.providers.microsoft block in app-config.yaml can all change behavior along with it. Before the bump, use the Backstage Upgrade Helper to compare the template files between your current version and the target, and check every change that touches app-config.production.yaml, the packages/backend auth wiring or the sign-in page in packages/app. Your Entra ID app registration does not change during an upgrade, so the risk is in how Backstage reads it.
After the bump, run a repeatable sign-in test rather than a quick browser check. Confirm that the redirect URI registered in Entra ID still matches the callback path of the new release, that a test user from your primary tenant and a user from a second tenant both reach the catalog, and that the resolver still maps each user to the expected User entity. Check the tenantId and domain_hint settings against a real multi-tenant sign-in, and confirm that a user with no matching catalog entity is still refused rather than admitted. Record the results so the next upgrade has a baseline to compare against.
Plan for security fixes arriving outside your normal upgrade window. The Backstage versioning policy says high and critical severity vulnerabilities will always be backported to releases from the last 6 months if feasible, and other security fixes may be backported. That means a patch can reach a release line you already run, but it can also mean you must move to a newer line to receive a fix. Ask your team to confirm which Backstage release line and Node.js version you run, and set a standing task to review the GitHub releases page for security notes. For the full provider setup and the resolver behavior you should be testing against, read the Backstage authentication documentation.
How DeployOpen scopes and delivers Entra ID sign-in for Backstage
DeployOpen plans and builds Backstage sign-in with Microsoft Entra ID inside your own infrastructure, from the app registration through resolver design and handover. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm your Entra ID tenant model, including whether single-tenant or multi-tenant users must sign in.
- Agree which resolvers map Entra identities to catalog users and which users are allowed to sign in.
- Record app registration ownership, Graph permissions, admin consent steps and who approves them in writing.
How we build
- Create the app registration, redirect URI and client secret or certificate settings for each Backstage environment.
- Configure the domain hint, allowed domains and resolver order, then test each resolver with sample accounts.
- Verify sign-in against the catalog, removing guest access from production and checking that failed lookups are rejected.
How we hand over
- Deliver configuration files, secret handling notes and a runbook for rotating the client secret or certificate.
- Document the resolver logic, the Graph permissions requested and the reasons each one is needed.
- Walk your identity and platform teams through test results, known limitations and the change process for future edits.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover.
- Review sign-in configuration when Backstage releases change authentication modules or resolver behavior.
- Confirm with your Entra ID administrators any tenant policy changes that could affect sign-in before they are made.
